IT operator guide
For whoever installs and looks after the server. The system is one Node.js server with a PostgreSQL database. It serves the office app, the field app and this guide, each on its own host name. Step-by-step deployment to Dokploy is in DEPLOY.md in the code repository; this page is the operational overview.
What runs where
| Part | Details |
|---|---|
| Server | Node.js 24, Express. One process listens on PORT (default 3000) and serves the API under /api and all three web apps. |
| Database | PostgreSQL 17 with PostGIS (the postgis/postgis:17-3.5 image in both compose files), through Prisma. PostGIS holds the project and property boundaries and runs the overlap checks. Migrations live in prisma/migrations. |
| Background jobs | Map scans and spatial checks are kept in the jobs table and run by the server that serves the office app (the admin service on Dokploy), next to the email and SMS queue, including a nightly re-check of all boundaries. Several copies of the server never run the same job twice. Administrators see the jobs under Administration › Background jobs. |
| Maps | Map tiles from the public OpenStreetMap server by default, or your own tile server. The map scan reads OpenStreetMap data from an Overpass API server. |
| Files | Evidence and photos on local disk (UPLOAD_DIR) or any S3-compatible store such as MinIO. |
| Any SMTP server (Nodemailer). | |
| SMS | Termii. |
| Bank, BVN and NIN checks | Monnify, or a built-in mock for testing. |
Host names
The server picks the app from the host name of each request:
| Host | Serves | Setting | Fallback path |
|---|---|---|---|
survey.<domain> | Field survey app (offline PWA) | SURVEY_URL | /survey/ |
docs.<domain> | This user guide | DOCS_URL | /docs/ |
| any other host | Office app | APP_URL | — |
- In development,
http://localhost:3000,http://survey.localhost:3000andhttp://docs.localhost:3000all work without a hosts file: Chrome, Edge and Firefox send*.localhostto your own machine. - In production, point each host name’s DNS at the server and serve them all over HTTPS. The field app’s offline mode and GPS only work on secure origins.
- Set
APP_URL,SURVEY_URLandDOCS_URLto the public addresses. Invitation emails link toAPP_URL, and the apps’ Help links useDOCS_URL. - The fallback paths work on the main host when a sub-domain is not set up.
Install and run (without Docker)
npm install # also runs prisma generate
cp .env.example .env # then fill it in (see below)
npx prisma migrate deploy # create or upgrade the tables
npm start # or: npm run dev (restarts on file changes)
On first start with an empty database the server creates the default roles, the 23 Kaduna LGAs with their 255 wards, and the first administrator from ADMIN_EMAIL / ADMIN_PASSWORD (staff ID KADGIS-0001). Change that password straight after the first log-in.
Stop the server before running prisma generate or prisma migrate: the running server locks Prisma’s engine file.
With Docker, npm run docker:up builds the image and runs it with a throwaway database. The container applies migrations on start (turn off with RUN_MIGRATIONS=false). See DEPLOY.md for Dokploy.
Settings (.env)
| Setting | What it does |
|---|---|
DATABASE_URL | PostgreSQL connection string. |
PORT | Port to listen on (default 3000). |
JWT_SECRET | Signs log-in sessions. A long random string (openssl rand -base64 48). Changing it logs everyone out. |
APP_URL, SURVEY_URL, DOCS_URL | Public addresses of the three apps. |
ADMIN_EMAIL, ADMIN_PASSWORD | The first administrator, created only when the database has no users. |
NODE_ENV=production | Refuses to start with a weak JWT_SECRET, a non-HTTPS APP_URL or other unsafe settings. Set by the Docker image. |
TRUST_PROXY | Number of proxies in front of the app (1 behind Traefik / Dokploy), so log-in rate limits see the real client address. |
MAIL_PROVIDER, SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASS, MAIL_FROM | Email. MAIL_PROVIDER=console only prints mail to the server log. |
OUTBOX_VIEWER_ENABLED | true lets administrators read every sent email and SMS (Messages › Outbox). |
TERMII_API_KEY, TERMII_SENDER_ID, TERMII_CHANNEL | SMS. Without a key, texts are only printed to the log. Channel generic or dnd. |
STORAGE_PROVIDER, UPLOAD_DIR, S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION, S3_SSE | File storage: disk (default) or s3. Files saved before switching to S3 are still read from disk. |
MONNIFY_BASE_URL, MONNIFY_API_KEY, MONNIFY_SECRET_KEY, BANK_PROVIDER, IDENTITY_PROVIDER | Bank, BVN and NIN checks. They stay on the mock until BANK_PROVIDER=monnify / IDENTITY_PROVIDER=monnify. |
MAP_TILE_URL, MAP_TILE_ATTRIBUTION, MAP_MAX_ZOOM, MAP_SATELLITE_URL, MAP_SATELLITE_ATTRIBUTION | Map tiles for the office and field apps. Default: the public OpenStreetMap tiles. |
MAP_OFFLINE_DOWNLOAD, MAP_OFFLINE_MAX_TILES | true shows Download this project’s map for offline use in the field app. Only works with your own MAP_TILE_URL: the public OpenStreetMap servers forbid bulk downloads. |
OVERPASS_URL, SCAN_MAX_AREA_KM2 | Overpass API servers for the map scan, comma-separated, tried in order until one answers; and the largest project area a scan accepts (default 150 km²). |
SPATIAL_MIN_OVERLAP_SQM, SPATIAL_MIN_OVERLAP_PCT, SPATIAL_BLOCKING_OVERLAP_PCT, SPATIAL_DUPLICATE_PCT | Spatial check tolerances: overlaps smaller than 1 m² or 2% are ignored as slivers; over 20% blocks compensation; over 60% raises a possible duplicate property. |
Keep .env out of version control. Administrators can see which service each part uses, test SMTP and storage, and send test messages under Messages › Delivery settings (see the Administrator guide).
The mock checks
Without Monnify, bank, BVN and NIN checks use test rules and results are marked “test mode”:
- Account numbers starting with
000are “not found”. - A BVN or NIN ending in
0000does not match. - Anything else matches the claimant’s own details.
Never run a live payment process on the mock.
Health and logs
| Address | Use |
|---|---|
/api/health | Liveness: the process is up. Includes the version. |
/api/health/ready | Readiness: checks the database and file storage. Returns 503 if either fails. Use for load balancer and container health checks. |
/api/links | The configured app, survey and docs addresses (used by the apps’ Help links). |
The server log has one JSON line per API request with its status and duration. Mail and SMS printed by the console drivers also appear there, which is how to find an invitation link when email is not set up.
Backups
- Database: back up PostgreSQL daily (
pg_dump, or your platform’s scheduled backups). This holds every record and minute. - Files: back up
UPLOAD_DIR(whenSTORAGE_PROVIDER=disk) or turn on versioning / replication on the S3 bucket. - Test a restore at least once: database and files must come from the same point in time.
Updating
- Deploy the new code and run
prisma migrate deploy(the container does this on start). - After changing anything in
web/survey/orweb/common/, bumpVERSIONinweb/survey/sw.js. Phones then fetch the new files the next time they open the app online. - After a change to the screens, refresh this guide’s screenshots (below).
Maintaining this guide
The guide is plain HTML in web/docs/, served as-is: no build step. Tables of roles, permissions, statuses and limits are drawn from shared/constants.js when the page opens, so they always match the running system.
Refreshing the screenshots
npm run docs:capture # every screenshot (a few minutes)
npm run docs:capture -- --only login,field-list # just some
npm run docs:check # every screenshot and link in the guide exists
docs:capturewipes and refills a separate demo database (DOCS_DATABASE_URL, or yourDATABASE_URLwith the database renamed tokadgis-compensation-docs). It refuses to run unless the database name ends in-docs, so the real database cannot be touched. The user running it needs permission to create that database.- It starts its own server on port 3100 with console email and SMS, disk storage and the mock checks, so nothing is sent anywhere. All people and numbers in the demo are made up.
- Screens and pointers are defined in
scripts/docs/shots.mjs. Each pointer is found on the live page, so a run fails loudly (naming the shot) if a screen changed so much that a pointer can no longer be found. --keepleaves the demo server running afterwards;--servestarts it again on the existing demo data;--reusecaptures against a running one.- Pictures go to
web/docs/screens/withmanifest.json(pointer positions). Commit them with the code.