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

PartDetails
ServerNode.js 24, Express. One process listens on PORT (default 3000) and serves the API under /api and all three web apps.
DatabasePostgreSQL 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 jobsMap 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.
MapsMap tiles from the public OpenStreetMap server by default, or your own tile server. The map scan reads OpenStreetMap data from an Overpass API server.
FilesEvidence and photos on local disk (UPLOAD_DIR) or any S3-compatible store such as MinIO.
EmailAny SMTP server (Nodemailer).
SMSTermii.
Bank, BVN and NIN checksMonnify, or a built-in mock for testing.

Host names

The server picks the app from the host name of each request:

HostServesSettingFallback path
survey.<domain>Field survey app (offline PWA)SURVEY_URL/survey/
docs.<domain>This user guideDOCS_URL/docs/
any other hostOffice appAPP_URL—

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.

Windows

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)

SettingWhat it does
DATABASE_URLPostgreSQL connection string.
PORTPort to listen on (default 3000).
JWT_SECRETSigns log-in sessions. A long random string (openssl rand -base64 48). Changing it logs everyone out.
APP_URL, SURVEY_URL, DOCS_URLPublic addresses of the three apps.
ADMIN_EMAIL, ADMIN_PASSWORDThe first administrator, created only when the database has no users.
NODE_ENV=productionRefuses to start with a weak JWT_SECRET, a non-HTTPS APP_URL or other unsafe settings. Set by the Docker image.
TRUST_PROXYNumber 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_FROMEmail. MAIL_PROVIDER=console only prints mail to the server log.
OUTBOX_VIEWER_ENABLEDtrue lets administrators read every sent email and SMS (Messages › Outbox).
TERMII_API_KEY, TERMII_SENDER_ID, TERMII_CHANNELSMS. 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_SSEFile 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_PROVIDERBank, 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_ATTRIBUTIONMap tiles for the office and field apps. Default: the public OpenStreetMap tiles.
MAP_OFFLINE_DOWNLOAD, MAP_OFFLINE_MAX_TILEStrue 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_KM2Overpass 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_PCTSpatial 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”:

Never run a live payment process on the mock.

Health and logs

AddressUse
/api/healthLiveness: the process is up. Includes the version.
/api/health/readyReadiness: checks the database and file storage. Returns 503 if either fails. Use for load balancer and container health checks.
/api/linksThe 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

Updating

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