docs: add tubco setup runbook

TUBCO_SETUP.md

@@ -0,0 +1,190 @@
+# TUBCO Customer Setup Runbook
+
+Use this runbook when you want to set up or rebuild the TUBCO customer deployment from scratch.
+
+This is the customer-specific path. Normal product work still happens on:
+- `develop`
+- `main`
+
+TUBCO delivery happens from:
+- `release/tubco-v1`
+
+## 1. Use the right branch
+```bash
+git checkout release/tubco-v1
+git pull --ff-only origin release/tubco-v1
+```
+
+If you plan to push an approved customer fix to the TUBCO remote:
+```bash
+./scripts/git_remote_target.sh status
+./scripts/git_remote_target.sh push-tubco release/tubco-v1
+```
+
+## 2. Prepare the target server once
+Target assumptions:
+- repo path: `/opt/workdock`
+- env file: `.env.prod`
+- public URL: `https://portal.tub.co`
+
+Create the server env file from the example:
+```bash
+ssh root@<customer-host>
+cd /opt/workdock
+cp .env.prod.example .env.prod
+```
+
+Required values to review in `.env.prod`:
+- `APP_DOMAIN=portal.tub.co`
+- `APP_BASE_URL=https://portal.tub.co`
+- `DJANGO_ALLOWED_HOSTS=portal.tub.co,...`
+- `DJANGO_CSRF_TRUSTED_ORIGINS=https://portal.tub.co`
+- `DJANGO_DEBUG=0`
+- `DJANGO_SECURE_COOKIES=1`
+- `DJANGO_SECURE_SSL_REDIRECT=1`
+- `DJANGO_SECRET_KEY=<strong secret>`
+- `POSTGRES_PASSWORD=<strong secret>`
+
+## 3. Optional: export the intended local TUBCO config baseline
+Run from the local repo:
+```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
+```
+
+This gives you the local baseline for:
+- app registry visibility/order
+- branding text and colors
+- company metadata
+
+## 4. Reset the customer stack from scratch
+This is destructive and wipes:
+- database state
+- generated media/documents
+- staticfiles volume
+- backup volume
+
+Run:
+```bash
+git checkout release/tubco-v1
+RESET_CONFIRM=RESET \
+EXPECTED_BRANCH=release/tubco-v1 \
+DEPLOY_HOST=root@<customer-host> \
+DEPLOY_PATH=/opt/workdock \
+REMOTE_ENV_FILE=.env.prod \
+HEALTH_URL=https://portal.tub.co/healthz/ \
+RUN_DJANGO_CHECK=1 \
+./scripts/reset_stack_from_mac.sh
+```
+
+Use this when you want a fresh customer environment with only default bootstrap data.
+
+## 5. Import the TUBCO config baseline
+Copy the exported JSON to the target host:
+```bash
+scp -4 /tmp/portal-app-config.json /tmp/portal-deployment-config.json root@<customer-host>:/opt/workdock/
+```
+
+Copy the files into the running web container:
+```bash
+ssh -4 root@<customer-host> '
+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
+'
+```
+
+Dry-run the import first:
+```bash
+ssh -4 root@<customer-host> '
+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
+'
+```
+
+If the dry run looks correct, apply it:
+```bash
+ssh -4 root@<customer-host> '
+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
+'
+```
+
+Note:
+- uploaded branding assets are not included in this JSON sync
+- logo, favicon, and PDF letterhead still need explicit upload on the customer system
+
+## 6. Normal customer deployment after the first setup
+After the first reset/bootstrap, regular TUBCO updates should usually be deploys, not resets.
+
+If you do not want a destructive reset, use the normal deploy path:
+```bash
+git checkout release/tubco-v1
+rsync -az --delete \
+  --filter 'P .env.test' \
+  --filter 'P .env.prod' \
+  --exclude '.git' \
+  --exclude '.github' \
+  --exclude '.venv' \
+  --exclude '__pycache__' \
+  --exclude 'node_modules' \
+  --exclude 'backend/media' \
+  --exclude 'backend/staticfiles' \
+  -e 'ssh -4' \
+  /Users/bostame/Documents/workdock-platform/ \
+  root@<customer-host>:/opt/workdock/
+
+ssh -4 root@<customer-host> '
+cd /opt/workdock &&
+RUN_DJANGO_CHECK=1 DEPLOY_HEALTH_URL="https://portal.tub.co/healthz/" ./scripts/deploy_stack.sh .env.prod docker-compose.prod.yml
+'
+```
+
+## 7. Verify the deployment
+Health:
+```bash
+curl -I https://portal.tub.co/healthz/
+```
+
+Container state:
+```bash
+ssh -4 root@<customer-host> '
+cd /opt/workdock &&
+docker compose --env-file .env.prod -f docker-compose.prod.yml ps
+'
+```
+
+Django checks inside the running app:
+```bash
+ssh -4 root@<customer-host> '
+docker exec workdock-web-1 python manage.py check
+'
+```
+
+## 8. Customer policy
+For TUBCO:
+- deploy from `release/tubco-v1`
+- do not give them future product features by default
+- only backport approved:
+  - bug fixes
+  - security updates
+  - UI improvements
+
+Do not deploy TUBCO from:
+- `develop`
+- `main`
+
+## 9. Access and roles
+Current intended customer rule:
+- highest customer-facing application role: `Super Admin`
+- `Platform Owner` remains product-level
+
+TUBCO-specific behavior already in the customer branch:
+- `Super Admin` can access:
+  - Branding
+  - Company Config
+- `Super Admin` cannot access:
+  - App Registry
+  - Trial Management
+  - Django Admin link