codedematrix/datacollection

1# NCA Data Collection System — Deployment Guide2 3**Target environment:** Ubuntu 22.04 LTS server on a local VM  4**Audience:** IT administrator performing the initial installation  5**Last updated:** 2026-06-086 7---8 9## Prerequisites10 11The server needs:12- Ubuntu 22.04 LTS (desktop or server edition)13- 4 GB RAM minimum (8 GB recommended)14- 20 GB free disk space15- Internet access (for the initial Docker image pull only)16- A static IP address on the LAN (e.g. `192.168.1.100`)17 18---19 20## Step 1 — Install Docker and Docker Compose21 22```bash23# Remove any old Docker packages24sudo apt-get remove -y docker docker-engine docker.io containerd runc25 26# Install dependencies27sudo apt-get update28sudo apt-get install -y ca-certificates curl gnupg lsb-release29 30# Add Docker's official GPG key and repository31sudo install -m 0755 -d /etc/apt/keyrings32curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg33sudo chmod a+r /etc/apt/keyrings/docker.gpg34echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \35  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \36  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null37 38# Install Docker Engine + Compose plugin39sudo apt-get update40sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin41 42# Allow running Docker without sudo (log out and back in after this)43sudo usermod -aG docker $USER44```45 46Verify the installation:47 48```bash49docker --version          # Docker 24.x or later50docker compose version    # Docker Compose v2.x51```52 53---54 55## Step 2 — Clone the Repository56 57```bash58cd /opt59sudo git clone https://github.com/dozzlee/NCA_Data_CollectionSystem.git nca-data-collection60sudo chown -R $USER:$USER nca-data-collection61cd nca-data-collection62```63 64---65 66## Step 3 — Configure Environment Variables67 68Copy the example file and fill in the required values:69 70```bash71cp .env.example .env72nano .env73```74 75Set these values in `.env`:76 77```78# Required — change both of these before starting79DB_PASSWORD=<strong-random-password>80SECRET_KEY=<generate-with-the-command-below>81 82# Set to your server's LAN IP (and hostname if applicable)83ALLOWED_HOSTS=localhost,127.0.0.1,192.168.1.10084 85# Email addresses for system notifications86SUPPORT_EMAIL=it@nca.org.gh87FEEDBACK_EMAIL=feedback@nca.org.gh88```89 90Generate a strong `SECRET_KEY`:91 92```bash93python3 -c "import secrets; print(secrets.token_urlsafe(50))"94```95 96> **Security note:** `.env` contains credentials. Never commit it to version control. The `.gitignore` already excludes it.97 98---99 100## Step 4 — Start the Application101 102```bash103docker compose -f docker-compose.prod.yml up -d --build104```105 106This builds all images and starts four containers:107- `db` — PostgreSQL 16108- `backend` — Django + Gunicorn109- `frontend` — Next.js (standalone)110- `nginx` — Reverse proxy on port 80111 112Wait ~60 seconds for all services to become healthy, then check:113 114```bash115docker compose -f docker-compose.prod.yml ps116```117 118All four services should show `Up`.119 120---121 122## Step 5 — Run Migrations and Seed Data (one-time)123 124These commands only need to be run once — on the initial installation.125 126```bash127# Apply database migrations128make migrate129 130# Load fixtures (Ghana regions + email templates)131make seed132 133# Create the first NCA Admin account134make createsuperuser135```136 137When prompted for the superuser, enter:138- Email (e.g. `admin@nca.org.gh`)139- Password (use something strong — this is the primary admin account)140 141---142 143## Step 6 — Verify the Installation144 145Open a browser on the LAN and go to `http://192.168.1.100` (replace with your server's IP).146 147You should see the NCA login page. Sign in with the superuser credentials you created in Step 5.148 149Run the smoke test checklist in `SMOKE_TEST.md` to confirm all features are working.150 151---152 153## Step 7 — Schedule the Due-State Refresh Job154 155The system needs to recompute submission due states daily. Set up a cron job on the host:156 157```bash158crontab -e159```160 161Add this line (runs at 01:00 every day):162 163```1640 1 * * * docker exec nca-data-collection-backend-1 python manage.py refresh_due_states >> /var/log/nca-due-states.log 2>&1165```166 167> Confirm the container name with `docker ps --format '{{.Names}}'` — it may differ slightly.168 169---170 171## Routine Operations172 173### Start / stop174 175```bash176make up        # Start all services177make down      # Stop all services (data is preserved)178```179 180### View logs181 182```bash183make logs             # All containers184make logs-backend     # Django/Gunicorn only185make logs-nginx       # Nginx access/error logs186```187 188### Database backup189 190```bash191make backup192```193 194Backups are written to `./backups/` as timestamped `.sql.gz` files. Run this before any upgrade.195 196### Restore a backup197 198```bash199make restore FILE=backups/nca_db_2026-06-08_01-00.sql.gz200```201 202### Upgrade the application203 204```bash205git pull origin main206make backup                                            # Always backup first207docker compose -f docker-compose.prod.yml up -d --build208make migrate209```210 211---212 213## Firewall214 215Open only port 80 (HTTP) to LAN clients. SSH (22) should be restricted to the administrator's machine.216 217```bash218sudo ufw allow from 192.168.0.0/16 to any port 80219sudo ufw allow from <admin-ip> to any port 22220sudo ufw enable221```222 223---224 225## HTTPS (Optional but Recommended)226 227If the server has a hostname resolvable on the LAN (e.g. via internal DNS), use Certbot with a self-signed cert or an internal CA cert placed at:228 229- `/etc/ssl/nca/nca.crt`230- `/etc/ssl/nca/nca.key`231 232Then update `nginx/nginx.conf` to add an HTTPS server block (port 443) and redirect port 80 → 443. Restart nginx:233 234```bash235docker compose -f docker-compose.prod.yml restart nginx236```237 238---239 240## Troubleshooting241 242| Symptom | Check |243|---|---|244| Blank page / 502 Bad Gateway | `make logs-nginx` — backend may still be starting |245| Login fails immediately | `make logs-backend` — check for migration errors |246| File uploads fail | Check `media_files` Docker volume is mounted; check disk space |247| Emails not sending | Verify `SUPPORT_EMAIL` in `.env`; check `make logs-backend` for SMTP errors |248| Container won't start | `docker compose -f docker-compose.prod.yml logs <service>` |249