HiveGrid-Wireframes/hivegrid-cloud/docs/deployment-porting.md

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:

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:

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:

pnpm run verify:deploy-workflow

Focused verifier references may also include:

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:

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:

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.