CapaKraken/tooling/deploy/README.md

Deploy Tooling

This directory contains the canonical host-side tooling for the image-based staging and production path.

Files

• deploy-compose.sh: validates compose input, pulls images, runs migrations, starts the app, and waits for readiness
• .env.production.example: example host-side runtime configuration
• deploy.env.example: example short-lived deployment manifest written by GitHub Actions

Host Layout

On the target host, the deploy directory should contain:

<deploy-path>/
  docker-compose.prod.yml
  deploy.env
  .env.production
  tooling/deploy/deploy-compose.sh

deploy.env is ephemeral and written by GitHub Actions for one deployment. .env.production stays on the host and contains the long-lived runtime secrets and app configuration.

First Setup

1. Copy tooling/deploy/.env.production.example to the target host as .env.production.
2. Fill in the required secrets and URLs.
3. Keep RATE_LIMIT_BACKEND=redis so production uses the shared counter path intentionally.
4. Copy tooling/deploy/deploy.env.example to the host only if you want to dry-run the deploy script manually.
5. Replace the placeholder images in deploy.env.example with a real sha-<commit> tag and save it as deploy.env for a manual dry run.
6. Provision runtime AI/SMTP/anonymization secrets on the host through .env.production or the platform's secret facility.
7. Keep admin settings for status/verification only; do not use them to enter or rotate operational secrets.
8. After migration, use the admin cleanup action to remove any legacy database-stored runtime secrets.
9. Ensure Docker Engine and Docker Compose v2 are installed.
10. Ensure the target host can pull from ghcr.io.
11. A normal release no longer needs a Git checkout on the host. The host only needs the deploy bundle plus the two env files.
12. Merge to main, let release-image.yml publish the immutable images, then run the staging or production deploy workflow with the same image tag.

Manual Host Test

After the files are present on the host, the canonical flow can be tested manually:

set -a
. ./deploy.env
set +a
bash tooling/deploy/deploy-compose.sh staging