Chapter 2: System Requirements & Installation

Complete hardware specifications, software prerequisites, installation procedures, environment configuration, database setup, and deployment guides for the NDSS CRM platform.

2.1 Hardware Requirements

NDSS CRM is a web-based application that runs on a server (or cloud hosting environment) and is accessed by end users through a web browser. The hardware requirements are divided into two categories: server-side (where the application is hosted) and client-side (the devices used by staff and participants to access the platform).

2.1.1 Server Requirements

The following specifications apply to self-hosted deployments. If you are using Vercel, AWS, or another cloud hosting provider, these requirements are managed by the provider and can be scaled dynamically.

2.1.2 Client (End User) Requirements

2.2 Software Prerequisites

The following software must be installed on the development or server machine before NDSS CRM can be built and run. All version numbers represent the minimum supported version.

2.2.1 Verifying Prerequisites

Run the following commands to verify that all required software is installed and meets the minimum version requirements:

# Node.js and npm
$ node --version
v20.11.0

$ npm --version
10.2.4

# Python
$ python3 --version
Python 3.12.2

$ pip3 --version
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)

# PHP
$ php --version
PHP 8.3.4 (cli) (built: Mar 16 2024 00:00:00)

$ composer --version
Composer version 2.7.1 2024-02-09

# PostgreSQL
$ psql --version
psql (PostgreSQL) 16.2

# Git
$ git --version
git version 2.44.0

# Supabase / Oracle CLI
$ supabase --version
1.142.2

2.3 Browser Compatibility

NDSS CRM is a modern web application built with React 19 and Next.js 16. It requires a recent version of a major web browser. The following table shows the compatibility matrix across supported browsers and operating systems.

2.3.1 Required Browser Features

NDSS CRM relies on the following browser capabilities. All listed browsers (at the minimum versions above) support these features:

• ES2022+ JavaScript: Modern JavaScript features including optional chaining, nullish coalescing, top-level await, and private class fields.
• CSS Grid & Flexbox: Used extensively for responsive layouts throughout the application.
• WebSocket: Required for real-time notifications, messaging, and live data updates via Supabase / Oracle real-time channels.
• Fetch API: Used for all HTTP requests to the Supabase / Oracle backend.
• localStorage / sessionStorage: Used for caching user preferences and session state.
• Service Workers: Used for offline notification support and PWA functionality (v1.1.0+).
• CSS Custom Properties: Used for theming and dynamic style customisation.

2.4 Installation Guide

This section provides a complete, step-by-step guide for installing NDSS CRM on a local development machine. For production deployment, see Section 2.7: Deployment Guide.

2.4.1 Step 1: Clone the Repository

# Clone the NDSS CRM repository
$ git clone https://github.com/newdawn-support/newdawnss.git

# Navigate to the project directory
$ cd newdawnss

# Verify the repository structure
$ ls -la
drwxr-xr-x  src/
drwxr-xr-x  public/
drwxr-xr-x  supabase/
drwxr-xr-x  scripts/
drwxr-xr-x  services/
-rw-r--r--  package.json
-rw-r--r--  next.config.ts
-rw-r--r--  tailwind.config.ts
-rw-r--r--  tsconfig.json
-rw-r--r--  .env.example
-rw-r--r--  requirements.txt
-rw-r--r--  composer.json

2.4.2 Step 2: Install Node.js Dependencies

# Using npm (recommended)
$ npm install

# OR using Yarn
$ yarn install

# Verify installation
$ npm ls --depth=0
newdawnss@V3.8
+-- @radix-ui/react-accordion@1.2.0
+-- @radix-ui/react-alert-dialog@1.1.0
+-- @radix-ui/react-checkbox@1.1.0
+-- @radix-ui/react-dialog@1.1.0
+-- @radix-ui/react-dropdown-menu@2.1.0
+-- @radix-ui/react-label@2.1.0
+-- @radix-ui/react-popover@1.1.0
+-- @radix-ui/react-select@2.1.0
+-- @radix-ui/react-tabs@1.1.0
+-- @radix-ui/react-tooltip@1.1.0
+-- @supabase/supabase-js@2.45.0
+-- @tanstack/react-query@5.50.0
+-- next@16.0.0
+-- react@19.0.0
+-- react-dom@19.0.0
+-- react-hook-form@7.52.0
+-- tailwindcss@3.4.0
+-- typescript@5.5.0
+-- zod@3.23.0
+-- zustand@4.5.0
... and 127 more

2.4.3 Step 3: Install Python Dependencies

# Create a Python virtual environment
$ python3 -m venv venv

# Activate the virtual environment
$ source venv/bin/activate   # Linux/macOS
$ .\venv\Scripts\activate    # Windows

# Install Python dependencies
(venv) $ pip install -r requirements.txt

# Key Python packages installed:
# - psycopg2-binary==2.9.9      (PostgreSQL adapter)
# - pandas==2.2.1                (Data manipulation)
# - openpyxl==3.1.2              (Excel report generation)
# - reportlab==4.1.0             (PDF report generation)
# - fastapi==0.110.0             (API microservice framework)
# - uvicorn==0.29.0              (ASGI server)
# - pydantic==2.6.4              (Data validation)
# - python-dotenv==1.0.1         (Environment variable loading)

# Verify installation
(venv) $ python3 -c "import pandas; print(pandas.__version__)"
2.2.1

2.4.4 Step 4: Install PHP Dependencies

# Install PHP dependencies via Composer
$ composer install

# Key PHP packages installed:
# - guzzlehttp/guzzle: ^7.8      (HTTP client for API integrations)
# - vlucas/phpdotenv: ^5.6        (Environment variable loading)
# - monolog/monolog: ^3.5         (Logging framework)
# - league/csv: ^9.15             (CSV data processing)
# - firebase/php-jwt: ^6.10       (JWT token handling)

# Verify installation
$ php -r "require 'vendor/autoload.php'; echo 'PHP dependencies loaded successfully.\n';"
PHP dependencies loaded successfully.

2.4.5 Step 5: Configure Environment Variables

# Copy the example environment file
$ cp .env.example .env.local

# Open .env.local in your editor and configure the required variables
$ nano .env.local    # or use your preferred editor

See Section 2.5 for a complete listing of all environment variables.

2.4.6 Step 6: Set Up the Database

# Option A: Using Supabase / Oracle CLI (recommended for development)
$ supabase init
$ supabase start

# This starts local Supabase / Oracle services:
#   - PostgreSQL on port 54322
#   - Auth on port 54321
#   - Storage on port 54321
#   - Realtime on port 54321

# Run database migrations
$ supabase db push

# Seed the database with initial data
$ supabase db seed

# Option B: Using a standalone PostgreSQL instance
$ createdb newdawnss_dev
$ psql newdawnss_dev < supabase/migrations/00001_initial_schema.sql
$ psql newdawnss_dev < supabase/seed.sql

See Section 2.6 for detailed database setup instructions.

2.4.7 Step 7: Start the Development Server

# Start the Next.js development server
$ npm run dev

  ▲ Next.js 16.0.0
  - Local:        http://localhost:3000
  - Environments: .env.local
  - Experiments:  (none)
  - Ready in 2.4s

# In a separate terminal, start the Python microservice
$ source venv/bin/activate
(venv) $ uvicorn services.main:app --port 8001 --reload

INFO:     Uvicorn running on http://127.0.0.1:8001
INFO:     Started reloader process

# In a third terminal, start the PHP integration service (if needed)
$ php -S localhost:8002 -t services/php/public

PHP Development Server started at http://localhost:8002

2.4.8 Step 8: Build for Production

# Create a production build
$ npm run build

  ▲ Next.js 16.0.0
  Creating an optimized production build ...
  ✓ Compiled successfully
  ✓ Linting and type checking
  ✓ Collecting page data
  ✓ Generating static pages (42/42)
  ✓ Collecting build traces
  ✓ Finalizing page optimization

  Route (app)                              Size     First Load JS
  ┌ ○ /                                    5.2 kB   89.4 kB
  ├ ○ /(auth)/login                        3.8 kB   87.9 kB
  ├ ○ /(auth)/signup                       4.1 kB   88.3 kB
  ├ ○ /(dashboard)/dashboard               8.7 kB   92.8 kB
  ├ ○ /(dashboard)/clients                 12.3 kB  96.4 kB
  ├ ○ /(dashboard)/staff                   9.8 kB   93.9 kB
  └ ... 36 more routes

  ○  (Static)   prerendered as static content
  ●  (SSG)      prerendered as static HTML

# Start the production server
$ npm start

  ▲ Next.js 16.0.0
  - Local:   http://localhost:3000
  - Ready in 1.1s

2.5 Environment Configuration

NDSS CRM uses environment variables for all configuration that varies between environments (development, staging, production). These variables are loaded from a .env.local file during development and from the hosting platform's environment variable system in production.

2.5.1 Supabase / Oracle Configuration

2.5.2 Database Configuration

2.5.3 Application Configuration

2.5.4 Email & Notification Configuration

2.5.5 Complete Example .env.local

# ============================================
# NDSS CRM Environment Configuration
# ============================================

# --- Supabase / Oracle ---
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# --- Database ---
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

# --- Application ---
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_NAME=NDSS CRM
NODE_ENV=development

# --- Services ---
PYTHON_SERVICE_URL=http://localhost:8001
PHP_SERVICE_URL=http://localhost:8002

# --- Email (optional for local dev) ---
# SMTP_HOST=smtp.sendgrid.net
# SMTP_PORT=587
# SMTP_USER=apikey
# SMTP_PASS=SG.xxxxxxxxxxxx
# SMTP_FROM=noreply@newdawnss.com.au

# --- SMS (optional for local dev) ---
# SMS_PROVIDER=twilio
# SMS_API_KEY=ACxxxxxxxxxxxxxxxx
# SMS_API_SECRET=xxxxxxxxxxxxxxxx

2.6 Database Setup

NDSS CRM uses PostgreSQL as its primary database, accessed through Supabase / Oracle. This section covers local database setup for development, cloud database configuration for production, and database migration management.

2.6.1 Local Development with Supabase / Oracle CLI

The Supabase / Oracle CLI provides a complete local development environment that mirrors the production Supabase / Oracle setup. This is the recommended approach for development.

# Initialise Supabase / Oracle (first time only)
$ supabase init

# Start local Supabase / Oracle services
$ supabase start

  Started supabase local development setup.

           API URL: http://127.0.0.1:54321
       GraphQL URL: http://127.0.0.1:54321/graphql/v1
            DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
        Studio URL: http://127.0.0.1:54323
      Inbucket URL: http://127.0.0.1:54324
        JWT secret: super-secret-jwt-token
          anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2.6.2 Running Migrations

Database migrations are stored in the supabase/migrations/ directory and are applied in chronological order.

# Apply all pending migrations
$ supabase db push

Applying migration 00001_initial_schema.sql...done
Applying migration 00002_rls_policies.sql...done
Applying migration 00003_seed_roles.sql...done
Applying migration 00004_client_tables.sql...done
Applying migration 00005_staff_tables.sql...done
Applying migration 00006_rostering_tables.sql...done
Applying migration 00007_finance_tables.sql...done
Applying migration 00008_compliance_tables.sql...done
Applying migration 00009_clinical_tables.sql...done
Applying migration 00010_messaging_tables.sql...done

All migrations applied successfully.

# Create a new migration
$ supabase migration new add_training_module
Created new migration: supabase/migrations/20260404120000_add_training_module.sql

# Reset the database (destroys all data)
$ supabase db reset

2.6.3 Database Seeding

# Seed with sample data for development
$ supabase db seed

Seeding database...
  - 3 admin users created
  - 24 role definitions inserted
  - 50 sample clients created
  - 30 sample staff members created
  - 200 sample shifts created
  - 100 sample invoices created
  - 15 sample incidents created
  Done.

2.6.4 Supabase / Oracle Studio

Supabase / Oracle Studio is a web-based database management interface available at http://127.0.0.1:54323 during local development. It provides a visual table editor, SQL query runner, authentication user management, and storage bucket management. This is useful for inspecting data during development without writing SQL queries.

2.6.5 Production Database (Supabase / Oracle Cloud)

For production deployments, create a Supabase / Oracle Cloud project:

1. Navigate to supabase.com and create an account or sign in.
2. Click New Project and select your organisation.
3. Enter a project name (e.g., newdawnss-production).
4. Set a strong database password and store it securely.
5. Select the Australia (Sydney) region for Australian data residency compliance.
6. Click Create new project and wait for provisioning to complete.
7. Navigate to Settings → API to obtain your project URL, anon key, and service role key.
8. Link your local project to the cloud project: supabase link --project-ref your-project-ref
9. Push migrations to production: supabase db push --linked

2.7 Deployment Guide

NDSS CRM supports multiple deployment strategies. Choose the one that best fits your organisation's infrastructure, technical capabilities, and compliance requirements.

2.7.1 Vercel Deployment (Recommended)

Vercel is the recommended hosting platform for NDSS CRM's Next.js frontend. It provides automatic builds, global CDN distribution, preview deployments, and native Next.js optimisations.

1. Push your NDSS CRM repository to GitHub, GitLab, or Bitbucket.
2. Navigate to vercel.com and sign in with your Git provider.
3. Click Import Project and select the NDSS CRM repository.
4. Configure the project settings:
   • Framework Preset: Next.js (auto-detected)
   • Build Command: npm run build
   • Output Directory: .next
   • Install Command: npm install
5. Add all required environment variables (see Section 2.5) in the Vercel project settings under Settings → Environment Variables.
6. Click Deploy. Vercel will build and deploy the application.
7. Configure a custom domain in Settings → Domains (e.g., app.newdawnss.com.au).

# Deploy via Vercel CLI (alternative)
$ npm install -g vercel
$ vercel login
$ vercel --prod

Vercel CLI 33.5.0
🔗 Linked to newdawn/newdawnss
🔍 Inspect: https://vercel.com/newdawn/newdawnss/xxxxx
✅ Production: https://newdawnss.vercel.app

2.7.2 Docker Deployment

NDSS CRM includes a multi-stage Dockerfile for containerised deployments.

# Build the Docker image
$ docker build -t newdawnss:latest .

# Run the container
$ docker run -d \
  --name newdawnss \
  -p 3000:3000 \
  -e NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co \
  -e NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG... \
  -e SUPABASE_SERVICE_ROLE_KEY=eyJhbG... \
  -e DATABASE_URL=postgresql://... \
  -e NEXT_PUBLIC_APP_URL=https://app.newdawnss.com.au \
  newdawnss:latest

# Verify the container is running
$ docker ps
CONTAINER ID   IMAGE             STATUS          PORTS
abc123def456   newdawnss:latest   Up 10 seconds   0.0.0.0:3000->3000/tcp

Docker Compose (Full Stack)

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    env_file: .env.production
    depends_on:
      - python-service
      - php-service

  python-service:
    build:
      context: .
      dockerfile: services/python/Dockerfile
    ports:
      - "8001:8001"
    env_file: .env.production

  php-service:
    build:
      context: .
      dockerfile: services/php/Dockerfile
    ports:
      - "8002:8002"
    env_file: .env.production

# Start all services
$ docker-compose up -d

2.7.3 Traditional Server Deployment

For organisations that prefer traditional server deployments (e.g., on an Ubuntu VPS or dedicated server):

# 1. Install system dependencies
$ sudo apt update && sudo apt upgrade -y
$ sudo apt install -y curl git build-essential

# 2. Install Node.js via nvm
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
$ source ~/.bashrc
$ nvm install 20
$ nvm use 20

# 3. Install Python 3.12
$ sudo apt install -y python3.12 python3.12-venv python3-pip

# 4. Install PHP 8.3
$ sudo apt install -y php8.3 php8.3-cli php8.3-curl php8.3-mbstring php8.3-xml
$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

# 5. Clone and build
$ git clone https://github.com/newdawn-support/newdawnss.git /opt/newdawnss
$ cd /opt/newdawnss
$ npm install
$ pip install -r requirements.txt
$ composer install
$ cp .env.example .env.local
$ nano .env.local   # Configure environment variables
$ npm run build

# 6. Set up PM2 for process management
$ npm install -g pm2
$ pm2 start npm --name newdawnss -- start
$ pm2 start services/python/main.py --name newdawnss-python --interpreter python3
$ pm2 startup
$ pm2 save

# 7. Configure Nginx reverse proxy
$ sudo apt install -y nginx
$ sudo nano /etc/nginx/sites-available/newdawnss

Nginx Configuration

server {
    listen 80;
    server_name app.newdawnss.com.au;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    location /api/python/ {
        proxy_pass http://127.0.0.1:8001/;
    }

    location /api/php/ {
        proxy_pass http://127.0.0.1:8002/;
    }
}

# Enable the site and configure SSL
$ sudo ln -s /etc/nginx/sites-available/newdawnss /etc/nginx/sites-enabled/
$ sudo nginx -t
$ sudo systemctl restart nginx
$ sudo certbot --nginx -d app.newdawnss.com.au

2.8 Post-Installation Verification

After completing the installation, run through the following checklist to verify that all components are functioning correctly.