workdock-platform/TUBCO_SETUP.md

TUBCO Customer Setup Runbook

Use this runbook when you want to set up or rebuild the TUBCO customer deployment from scratch.

Maintenance policy reference:

• docs/TUBCO_MAINTENANCE_POLICY.md

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

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:

./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:

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:

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:

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:

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:

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:

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:

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:

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:

curl -I https://portal.tub.co/healthz/

Container state:

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:

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

Important:

• keep TUBCO on the old TUBCO database schema
• do not solve customer drift by importing the newer product schema into TUBCO
• if a deployed TUBCO environment starts failing on unknown non-null columns, verify DB/schema alignment first
• for the full maintenance rules, use:
  • docs/TUBCO_MAINTENANCE_POLICY.md

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