# 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:

```text
<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:

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