diff --git a/backend/workflows/templates/workflows/developer_handbook.html b/backend/workflows/templates/workflows/developer_handbook.html index 205a165..d991796 100644 --- a/backend/workflows/templates/workflows/developer_handbook.html +++ b/backend/workflows/templates/workflows/developer_handbook.html @@ -33,6 +33,7 @@ Builders Testing Backup + CI/CD Deployment Troubleshooting Security @@ -266,7 +267,95 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
  • The staff UI uses the shared action-progress overlay for backup creation and verification so long-running actions present one standard app behavior.
    • -

    13) Deployment and Release Checklist

    +

    13) CI/CD

    + +

    GitHub Environments

    + +

    Current test deployment values

    + +
    + The current LAN test deployment intentionally uses DJANGO_DEBUG=1 in .env.test because the security checks correctly reject insecure cookie settings when DEBUG=0 and the deployment is still plain HTTP. This is acceptable for the internal test box only. Production must run with HTTPS and DEBUG=0. +
    + +

    14) Deployment

    +

    Test server stack

    + +

    What the deploy script does

    +
      +
    1. Validate env file presence
      2. +
    2. Build web, worker, and caddy
      3. +
    3. Start db and redis
      4. +
    4. Initialize writable volume ownership for media/static/backups
      5. +
    5. Run migrations
      6. +
    6. Run bootstrap_initial_users
      7. +
    7. Run collectstatic
      8. +
    8. Optionally run manage.py check
      9. +
    9. Start web, worker, and caddy
      10. +
    10. Wait until /healthz/ becomes healthy
      11. +
    +

    Manual deploy

    + 
    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
    +

    Validation after deploy

    + 
    curl -I http://192.168.2.55:8088/healthz/
+ssh root@192.168.2.55 "cd /opt/workdock && docker compose --env-file .env.test -f docker-compose.prod.yml ps"
    +

    Proxmox / LXC requirement

    +

    The current server is an Ubuntu CT on Proxmox running Docker inside the container. The CT required Proxmox-side configuration before Docker containers could start correctly.

    + 
    features: nesting=1,keyctl=1
+lxc.apparmor.profile: unconfined
+lxc.mount.entry: /dev/null sys/module/apparmor/parameters/enabled none bind 0 0
    +

    Those lines belong in /etc/pve/lxc/<CTID>.conf on the Proxmox host, followed by pct restart <CTID>.

    +

    Production expectations

    + +

    Release checklist

    1. Run manage.py check
    2. Run tests or targeted verification
      3. @@ -275,11 +364,11 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
    3. Generate at least one onboarding/offboarding PDF if PDF templates changed
    4. Verify MailHog or SMTP path if email behavior changed
    5. Verify Nextcloud upload if integration behavior changed
      6. -
    6. Update Project Wiki and Developer Handbook if architecture/workflow changed
      7. +
    7. Update Project Wiki and Developer Handbook if architecture or operational workflow changed
    8. Take a snapshot commit before major next-phase work
    -

    14) Troubleshooting

    +

    15) Troubleshooting

    -

    15) Security and Maintenance Notes

    +

    16) Security and Maintenance Notes

    {% trans "Open Developer Handbook" %}