Production readiness and recovery

Use the same application revision, frozen parcel CRS, PostgreSQL/PostGIS versions and media configuration for rehearsal and recovery. Record the revision, backup timestamp, size, last committed workflow event and achieved recovery time. The operator sets the recovery time and data-loss objectives for the installation.

Check for a superuser after deployment

After deployment or a database restore, run this read-only check on the Dokku host. Replace lmstool2 with the deployed app name if it differs.

dokku run lmstool2 python manage.py shell -c "from django.contrib.auth import get_user_model; print(get_user_model().objects.filter(is_active=True, is_staff=True, is_superuser=True).exists())"

True means the deployed database contains an active staff account with superuser status. If the result is False, create a superuser interactively:

dokku run lmstool2 python manage.py createsuperuser

Enter an unused username, a recovery email address and a password. Repeat the check and verify that you can sign in at /admin/ with the new account.

Traffic and monitoring

Dokku's web startup and readiness checks request /readyz/. A 200 response requires PostGIS and the application's expected migration heads. An unavailable database or pending schema returns 503. Keep /healthz/ as the independent process liveness check. Configure external monitoring to request the HTTPS readiness URL with the deployment hostname, alert on repeated non-200 responses or timeouts, and check request latency and server errors separately. Verify the actual proxy and alert destination in staging by withholding the database from an isolated release and observing both traffic withdrawal and the alert. Restore access and observe recovery before promotion.

Worker count and request timeout

Gunicorn loads gunicorn.conf.py at startup. Configure these positive integer values in the installation's .env or container environment:

GUNICORN_WORKERS=10
GUNICORN_TIMEOUT_SECONDS=300

These example values are for the 16-CPU training server. Unset values preserve the image's previous defaults: three workers and a 60-second worker timeout. Invalid values, including zero, fail Gunicorn startup. Container environment values take precedence over .env. Worker count and timeout are operational settings; changing them requires restarting or recreating the web process. Do this between imports, because an in-flight request can be interrupted by a restart even when its normal worker timeout is longer.

For a source installation, Gunicorn reads the .env beside gunicorn.conf.py. Docker Compose passes the two values from the workstation's .env into the web container. After the initial image update, use docker compose up -d --no-deps --force-recreate web to apply edited values; docker compose restart alone does not refresh container environment variables. The .env file remains excluded from image builds.

For Dokku, set the same two variables explicitly on the app. Dokku does not read the workstation's .env. Its app configuration persists across code updates, and each new web process reads the current values:

dokku config:set --no-restart APP GUNICORN_WORKERS=10 GUNICORN_TIMEOUT_SECONDS=300
dokku nginx:set APP proxy-read-timeout 330s

Nginx runs outside Django and has a separate host configuration. Keep its proxy read timeout longer than the Gunicorn timeout; 330 seconds provides headroom for this 300-second example. The web process restart rebuilds the Dokku proxy configuration. If changing only Nginx, apply its setting with dokku proxy:build-config APP.

The training server previously used a full dockerfile-start-cmd override containing --workers and --timeout. Those command-line flags override the new configuration file. Once the environment-aware image has been deployed, clear that old override and restart the web process:

dokku ps:set APP dockerfile-start-cmd
dokku ps:restart APP web

Replace APP with the intended application name. A new installation does not need the override-clearing step. An existing installation with an intentionally custom startup command should retain its required options while removing only the hardcoded worker and timeout flags. No source or image rebuild is needed for subsequent value changes; set the variables, coordinate Nginx, and restart. Verify /readyz/ after each change. On Gunicorn versions with the control interface, gunicornc -c "show config" -j inside the web container reports the effective startup settings.

Before deployment

  1. Quiesce all writers, including background jobs, imports and media writers. Finish or abort in-flight requests. Keep writes paused until both archives and the verification inventory are complete.
  2. Use a private backup directory and a configured PostgreSQL service or protected credential file. Record required database owner/grantee roles, memberships and extensions separately. Provision those roles from trusted infrastructure configuration on the recovery server. Preserve object ownership and grants during restore.
  3. With the source database selected by PGDATABASE and the configured media directory in MEDIA_ROOT, run the following in the private backup directory:

sh umask 077 pg_dump --format=custom --file=database.dump tar -C "$MEDIA_ROOT" -cf media.tar . sha256sum database.dump media.tar > SHA256SUMS

  1. Retain a protected off-host copy. Record parcel version counts and exact geometry checksums (ordered parcel IDs and ST_AsEWKB(geometry)), frozen SRID, draft/event counts, selection receipt/item counts and linked event counts. Inventory media by relative path and hash and verify that database-referenced upload previews exist.

Restore rehearsal and rollback

  1. Start an isolated instance, create the recorded roles and an empty database, and select that database explicitly. Use a new empty media directory. Confirm both targets before loading data.
  2. Verify and restore the matched pair:

sh sha256sum --check SHA256SUMS pg_restore --exit-on-error --single-transaction --dbname="$RECOVERY_DATABASE" database.dump tar -C "$RECOVERY_MEDIA_ROOT" -xf media.tar

  1. Connect the matching application revision to the restored database and media. Compare the inventory, run manage.py migrate --check, and verify /readyz/, restricted access, parcel history and an upload preview as an authorized user. Rehearse the intended forward migration on a copy. Record elapsed time and the interval between the snapshot and any writes accepted after it.
  2. Migration 0028 refuses reversal once selection receipts exist. If the release must be rolled back, pause writes, preserve the failed environment, restore the pre-deployment database/media pair and matching code, verify the inventory and readiness, then switch traffic. Identify and reconcile any work accepted after the snapshot before reopening writes. Do not fake migration records or delete receipts to make reversal succeed.

Concurrent edits

The browser submits the revision displayed when the edit form opened. A stale save returns HTTP 409 and keeps the submitted values in that tab. Open Review current draft and reapply the desired changes in the new tab. For the parcel draft API, GET the draft detail and include its opaque draft_revision field alongside payload in PATCH. On 409, retain the attempted patch, retrieve the latest detail and reconcile before submitting again.