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](/Users/bostame/Documents/workdock-platform/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
```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

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](/Users/bostame/Documents/workdock-platform/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