docs: add config sync runbook and command reference

2026-03-29 01:42:45 +01:00
parent 22ab9a0849
commit 80a93bdf70
2 changed files with 199 additions and 2 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -211,6 +211,67 @@ cd /opt/workdock
 RUN_DJANGO_CHECK=1 ./scripts/deploy_stack.sh .env.prod docker-compose.prod.yml
 ```

+## Runtime config sync
+Deployment updates code. It does not automatically overwrite runtime database configuration.
+
+Use explicit sync when you want local configuration to be compared or applied to another environment.
+
+### Supported sync scopes
+- `PortalAppConfig`
+- `PortalBranding`
+- `PortalCompanyConfig`
+
+### Step 1: export locally
+```bash
+docker compose exec -T web python manage.py export_portal_app_config --output /tmp/portal-app-config.json
+docker compose exec -T web python manage.py export_portal_deployment_config --output /tmp/portal-deployment-config.json
+docker compose cp web:/tmp/portal-app-config.json /tmp/portal-app-config.json
+docker compose cp web:/tmp/portal-deployment-config.json /tmp/portal-deployment-config.json
+```
+
+### Step 2: copy JSON files to the server host
+```bash
+scp -4 /tmp/portal-app-config.json /tmp/portal-deployment-config.json root@192.168.2.55:/opt/workdock/
+```
+
+### Step 3: copy JSON files into the running web container
+The server uses baked images, not a bind-mounted app tree. Because of that, the running `web` container cannot automatically read arbitrary files from `/opt/workdock`.
+
+Use:
+```bash
+ssh -4 root@192.168.2.55 '
+  docker cp /opt/workdock/portal-app-config.json workdock-web-1:/tmp/portal-app-config.json &&
+  docker cp /opt/workdock/portal-deployment-config.json workdock-web-1:/tmp/portal-deployment-config.json
+'
+```
+
+### Step 4: dry-run the import on the server
+```bash
+ssh -4 root@192.168.2.55 '
+  docker exec workdock-web-1 python manage.py import_portal_app_config /tmp/portal-app-config.json --dry-run &&
+  docker exec workdock-web-1 python manage.py import_portal_deployment_config /tmp/portal-deployment-config.json --dry-run
+'
+```
+
+### Step 5: apply the import on the server
+Only do this if the dry run looks correct.
+
+```bash
+ssh -4 root@192.168.2.55 '
+  docker exec workdock-web-1 python manage.py import_portal_app_config /tmp/portal-app-config.json &&
+  docker exec workdock-web-1 python manage.py import_portal_deployment_config /tmp/portal-deployment-config.json
+'
+```
+
+### Notes
+- `PortalAppConfig` covers app order, section, visibility, and overrides.
+- deployment-config sync covers branding/company text and metadata.
+- uploaded branding files are intentionally excluded:
+  - logo
+  - favicon
+  - PDF letterhead
+- use dry-run first. Treat config sync as an explicit operator action, not something hidden inside deploy.
+
 ## GitHub Actions workflows
 ### Test deployment workflow
 File:
@@ -406,6 +467,65 @@ For production, you may later want image-tag based rollback. That is not necessa
 - test deployment is intentionally weaker than production on transport security
 - production should not reuse the test env model

+## Command reference
+Use this as the short operational index.
+
+### Local development
+```bash
+docker compose up -d --build
+```
+Start or rebuild the local stack.
+
+```bash
+docker compose restart web
+docker compose restart worker
+```
+Restart the app services after code/template changes.
+
+### Validation
+```bash
+docker compose exec -T web python manage.py check
+```
+Run Django system checks.
+
+```bash
+docker compose exec -T web python manage.py test
+```
+Run the full test suite.
+
+### Local test deployment
+```bash
+./scripts/deploy_test_from_mac.sh
+```
+Sync the current `develop` checkout to the LAN test server and deploy it.
+
+### Direct server deployment
+```bash
+cd /opt/workdock
+RUN_DJANGO_CHECK=0 DEPLOY_HEALTH_URL="http://127.0.0.1:8088/healthz/" ./scripts/deploy_stack.sh .env.test docker-compose.prod.yml
+```
+Deploy when code is already present on the server.
+
+### Config export/import
+```bash
+docker compose exec -T web python manage.py export_portal_app_config --output /tmp/portal-app-config.json
+docker compose exec -T web python manage.py export_portal_deployment_config --output /tmp/portal-deployment-config.json
+```
+Export runtime configuration from local.
+
+```bash
+docker exec workdock-web-1 python manage.py import_portal_app_config /tmp/portal-app-config.json --dry-run
+docker exec workdock-web-1 python manage.py import_portal_deployment_config /tmp/portal-deployment-config.json --dry-run
+```
+Validate server-side config import before applying it.
+
+### Backup
+```bash
+make backup-create
+make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
+```
+Create and verify backup bundles.
+
 ## Current known-good state
 Validated manually:
 - repository pushed to private GitHub