{% extends 'workflows/base_shell.html' %} {% load static %} {% block title %}Developer Handbook{% endblock %} {% block extra_css %} {% endblock %} {% block shell_body %} {% include 'workflows/includes/app_header.html' with header_show_home=1 header_inside_shell=1 %}

Developer Handbook

Project Wiki

Engineering runbook for development, deployment, maintenance, and extension of the current company portal deployment.

Overview Structure Local Dev Docker Database Translations PDF Pipeline Email Pipeline Nextcloud Builders Testing Backup Hosts & Domains CI/CD Deployment Troubleshooting Security

1) Overview

This handbook is for developers and maintainers. It documents the actual engineering workflow of the standalone product repository.

2) Repository Structure

3) Local Development Workflow

Start

cd /path/to/workdock-platform
docker compose up -d --build

Main URLs

Bootstrap users

4) Docker Operations

docker compose up -d --build
docker compose restart web
docker compose restart worker
docker compose logs --no-color --tail=120 web
docker compose logs --no-color --tail=120 worker
docker compose down
docker compose down -v
The source code is bind-mounted into the container. Most template/view/static changes only require a web restart, not a full rebuild. Image changes such as system packages require docker compose up -d --build.

5) Database and Migrations

docker compose exec -T web python manage.py makemigrations
docker compose exec -T web python manage.py migrate
docker compose exec -T web python manage.py check

Role and Permission Model

6) Translation Workflow

Standard Django i18n path

make i18n-update-en
make i18n-compile

Equivalent raw commands:

docker compose exec -T web django-admin makemessages -l en
docker compose exec -T web django-admin compilemessages

7) PDF Pipeline

xhtml2pdf is sensitive to layout complexity. Keep print templates conservative and verify every structural change with a real generated PDF.

8) Email Pipeline

9) Nextcloud Integration

10) Branding

10b) App Registry

10c) Trial Lifecycle

11) Builder Architecture

Form Builder

Intro Builder

Dynamic content should use explicit DE/EN fields with German fallback, not machine translation at runtime.

Audit Trail

11) Testing and Validation

docker compose exec -T web python manage.py check
docker compose exec -T web python manage.py test
docker compose exec -T web python manage.py run_staging_e2e_check

12) Backup and Restore

make backup-create
make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS

13) Host and Domain Configuration

14) CI/CD

GitHub Environments

Exact GitHub UI steps

  1. Open the private repository on GitHub.
  2. Open Settings.
  3. Open Environments in the left sidebar.
  4. Create the environment development.
  5. Create the environment production.
  6. Open development.
  7. Under Environment secrets, add the deployment secrets one by one.
  8. Repeat later for production.

Current test deployment values

Current development secrets

First GitHub Actions test

  1. Open GitHub Actions.
  2. Run the workflow Deploy Test on branch develop.
  3. Wait for the SSH upload and deploy steps to finish successfully.
  4. Verify http://192.168.2.55:8088/healthz/ returns HTTP 200.
  5. Then verify the app UI in the browser.
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.

15) Deployment

Test server stack

What the deploy script does

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

Manual deploy

The preferred current test-deployment path is the local helper script from a Mac or another LAN-connected workstation:

./scripts/deploy_test_from_mac.sh

This script fast-forwards develop, checks that the remote env file exists, syncs the repo to the server with rsync, runs the remote deployment, verifies the health endpoint, and prints the deployed commit hash.

The script explicitly preserves server-local env files such as .env.test and .env.prod so deployment does not wipe machine-specific secrets.

Direct server-side deploy is still available if the code is already on the server:

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. Run translation compile step
  4. Rebuild containers if Python dependencies changed, then verify python -c "import requests" does not emit a compatibility warning
  5. Generate at least one onboarding/offboarding PDF if PDF templates changed
  6. Verify MailHog or SMTP path if email behavior changed
  7. Verify Nextcloud upload if integration behavior changed
  8. Update Project Wiki and Developer Handbook if architecture or operational workflow changed
  9. Take a snapshot commit before major next-phase work

16) Troubleshooting

17) Security and Maintenance Notes

{% endblock %}