157 lines
9.0 KiB
Markdown
157 lines
9.0 KiB
Markdown
# Deployment Porting Guide
|
|
|
|
## Purpose
|
|
|
|
Use this guide when updating boilerplate deployment and CI documentation. It keeps deployment prose aligned with the current static evidence without overstating live proof, registry state, or production runtime behavior.
|
|
|
|
This document is a documentation entrypoint only. It does not authorize runtime workflow changes, secret creation, live registry pushes, Coolify deployments, browser checks, Playwright runs, Cypress runs, or other E2E execution from Auto-Mode.
|
|
|
|
## Source Evidence
|
|
|
|
Use these sources as the deployment-porting baseline:
|
|
|
|
- `README.md` for the active Gitea CI summary, Corepack/pnpm setup, Docker smoke description, and manual E2E policy.
|
|
- `docs/porting-guide.md` section `Deployment and CI docs` for wording rules that distinguish Gitea CI, local Docker smoke validation, static verification, and manual browser/E2E review.
|
|
- `docs/deployment.md` for the current deploy workflow contract, Gitea Package Registry placeholder slots, Coolify runner-side triggering, and health/readiness inspection guidance.
|
|
- `.tc/baselines/porting-docs/baseline-health.md` for the Porting Docs baseline gate evidence and documentation inventory scope.
|
|
|
|
When a later document claims stronger proof than these sources, it must name the later human-approved run or slice evidence that provided that proof.
|
|
|
|
## CI Terminology
|
|
|
|
Describe the active pipeline as Gitea CI on the self-hosted `toolctrl-ci` runner. The baseline CI contract starts with Corepack and the pinned pnpm version, installs dependencies with `pnpm install --frozen-lockfile`, then runs static/package gates for quality, API, worker, database, and Docker smoke validation.
|
|
|
|
Use these safe local verification references for CI documentation updates:
|
|
|
|
```sh
|
|
pnpm run verify:ci-baseline
|
|
pnpm run verify:gitea-ci-workflow
|
|
pnpm run verify:production-seed-artifact
|
|
```
|
|
|
|
Do not describe baseline CI as publishing images, pushing to a registry, triggering Coolify, running browser automation, or proving live deployment. Those claims require separate focused evidence.
|
|
|
|
## Docker Smoke Boundaries
|
|
|
|
Document Docker smoke as local build and configuration validation. It may prove that Dockerfile targets and Docker Compose configuration are shaped correctly, but it is not proof of a live runtime, registry publish, artifact upload, production rollout, or browser/E2E behavior.
|
|
|
|
Safe static/package verifier references include focused scripts and tests such as:
|
|
|
|
```sh
|
|
node scripts/verify-docker-baseline.mjs
|
|
pnpm exec vitest run scripts/verify-docker-baseline.test.mjs
|
|
```
|
|
|
|
If a human later performs a live Docker build/run smoke check, record it as manual evidence and keep secrets out of commands, logs, screenshots, and summaries.
|
|
|
|
## Deploy Workflow Verification
|
|
|
|
The deploy workflow contract is static unless a later human-approved run proves otherwise. Use this command as the supported shorthand when documenting the deploy workflow verifier:
|
|
|
|
```sh
|
|
pnpm run verify:deploy-workflow
|
|
```
|
|
|
|
Focused verifier references may also include:
|
|
|
|
```sh
|
|
node scripts/verify-gitea-deploy-workflow.mjs
|
|
pnpm exec vitest run scripts/verify-gitea-deploy-workflow.test.mjs
|
|
```
|
|
|
|
The static deploy workflow may document versioned image targets for `web`, `api`, and `worker`, immutable full-SHA tags, stage-and-promote alias behavior, and required placeholder configuration slots. Do not turn this into a claim that a registry login, image push, artifact publication, or production deployment actually happened unless the corresponding Gitea run evidence is attached separately.
|
|
|
|
## Placeholder-Only Secret Handling
|
|
|
|
Deployment docs must use placeholder names only. These names identify required CI variable or secret slots; they are not example values:
|
|
|
|
- `REGISTRY_USER`
|
|
- `REGISTRY_PAT`
|
|
- `COOLIFY_API_URL`
|
|
- `COOLIFY_RESOURCE_UUIDS`
|
|
- `COOLIFY_TOKEN`
|
|
- `COOLIFY_STAGING_API_URL`
|
|
- `COOLIFY_STAGING_RESOURCE_UUIDS`
|
|
- `COOLIFY_STAGING_TOKEN`
|
|
|
|
Do not include real registry hosts, namespaces, usernames, passwords, Coolify URLs, UUIDs, tokens, webhook query strings, deploy endpoints, database URLs, Redis URLs, Supabase keys, mail provider keys, or secret-shaped sample values. Use the image placeholder form `{registry}/{namespace}/{web|api|worker}:{tag}` when explaining image naming.
|
|
|
|
## Coolify Runner Trigger
|
|
|
|
Coolify triggering is runner-side after image publication. Document staging as the push-to-`main` path and production as the `workflow_dispatch` `promote` path. Promotion must require `staged_sha` as a full 40-character staged commit SHA, require `backup_confirmed=true` after backup or restore-point readiness is confirmed, verify the requested SHA image set against the current `staging` alias, and then move production `main` aliases without rebuilding.
|
|
|
|
The workflow must read endpoint and resource data only from configured CI variables and secrets. Documentation must not imply Coolify triggers from pull requests, schedules, or release tags unless a later approved workflow change and verifier evidence explicitly establish that behavior.
|
|
|
|
## Health and Readiness Inspection
|
|
|
|
Health/readiness inspection is separate from deployment proof. Static verification can document repository contracts for `GET /healthz`, `GET /readyz`, API health/readiness responses, and worker health reporting, while live runtime inspection remains manual.
|
|
|
|
Safe verifier references include:
|
|
|
|
```sh
|
|
node scripts/verify-health-baseline.mjs
|
|
pnpm exec vitest run scripts/verify-health-baseline.test.mjs
|
|
```
|
|
|
|
Manual runtime inspection may check web or API health/readiness endpoints, compare request IDs, or inspect worker health output. It must not record database connection strings, Redis URLs, stack traces, tokens, passwords, provider secrets, or other deployment-only values.
|
|
|
|
## Auto-Mode Exclusions
|
|
|
|
Auto-Mode-safe proof for deployment documentation is limited to static and package-level commands. Auto-Mode must not run live Docker builds, live Docker containers, registry pushes, Coolify dispatches, browser automation, Playwright, Cypress, or E2E commands unless a human explicitly approves that exact focused run in the current session.
|
|
|
|
When porting deployment docs, write manual-only language for those excluded checks. If a document needs to mention a future live deployment, phrase it as a manual verification step and keep the current static contract clear.
|
|
|
|
## Negative Verification Terms
|
|
|
|
Deployment documentation must fail review when it introduces any of these contract breaks:
|
|
|
|
- Real deploy endpoints, real registry hosts, real Coolify URLs, UUIDs, tokens, passwords, or secret-shaped examples.
|
|
- Claims that baseline CI, pull requests, schedules, or static verifiers prove production deployment.
|
|
- Claims that Coolify triggers before all deployable images are published.
|
|
- Browser, Playwright, Cypress, or E2E commands presented as Auto-Mode defaults.
|
|
- Unresolved marker words from the common task-note vocabulary.
|
|
|
|
## Forking To A Different Infra
|
|
|
|
When a fork runs the boilerplate on its own Gitea/registry/runner, the literal
|
|
infra strings in `.gitea/workflows/*.yml` must change but the verify gates
|
|
(`scripts/verify-gitea-ci-workflow.mjs`, `scripts/verify-gitea-deploy-workflow.mjs`)
|
|
keep enforcing structural correctness. Both gates read their expected
|
|
infra strings from `scripts/infra-config.mjs`, which honours the following
|
|
optional env vars (fallback values shown in parentheses):
|
|
|
|
| Env var | Default | Used for |
|
|
| --- | --- | --- |
|
|
| `TOOLCTRL_CI_RUNNER` | `toolctrl-ci` | `runs-on:` label asserted in every job |
|
|
| `TOOLCTRL_IMAGE_PREFIX` | `toolctrl` | Docker smoke tags `<prefix>-{web,api,worker}:smoke` |
|
|
| `TOOLCTRL_GIT_HOST` | `git.tool-ctrl.de` | `REGISTRY:` and `docker login` host pattern + `/etc/hosts` override |
|
|
| `TOOLCTRL_REGISTRY_NAMESPACE` | `toolctrl-labs` | Gitea Package Registry namespace expectations |
|
|
| `TOOLCTRL_DB_USER` | `toolctrl` | Preflight `DATABASE_URL` user component |
|
|
| `TOOLCTRL_DB_NAME` | `toolctrl` | Preflight `DATABASE_URL` database name |
|
|
|
|
Fork procedure:
|
|
|
|
1. `sed`-replace the literal `toolctrl-ci`, `toolctrl-{web,api,worker}:smoke`,
|
|
`git.tool-ctrl.de`, `toolctrl-labs`, and DB credentials in
|
|
`.gitea/workflows/*.yml` to match the fork's infra.
|
|
2. Export the matching `TOOLCTRL_*` env vars in CI so the verify gates assert
|
|
against the new strings instead of the ToolCTRL defaults.
|
|
3. Run `pnpm run verify:gitea-ci-workflow` and `pnpm run verify:deploy-workflow`
|
|
locally to confirm the fork's workflow shape still satisfies the contract.
|
|
|
|
No verify-gate assertions change. Forks inherit the same structural guarantees
|
|
without rewriting the Gitea verification scripts.
|
|
|
|
## Static Verification
|
|
|
|
After editing this guide, use non-E2E checks only:
|
|
|
|
```sh
|
|
test -s docs/deployment-porting.md
|
|
grep -Eq "Gitea|Docker smoke|verify:ci-baseline|verify:gitea-ci-workflow|verify:deploy-workflow|REGISTRY_PAT|COOLIFY_TOKEN|workflow_dispatch|promote|staging|main" docs/deployment-porting.md
|
|
pnpm run verify:production-docs
|
|
pnpm run verify:docs-links
|
|
```
|
|
|
|
These checks confirm the guide exists, keeps required deployment contract terms visible, and stays covered by the active docs gates. They do not prove live deployment.
|