ctms/docs/plans/2026-03-30-tcloud-private-registry-design.md

Tencent Cloud Private Registry Design

Goal: Add CI that automatically builds and pushes private backend and frontend images to a self-hosted Docker Registry running on a Tencent Cloud CVM, with dev publishing test tags, release and release/* publishing release-candidate tags, and main publishing formal tags.

Decisions

• Publish only two runtime images: <registry-host>/ctms/ctms-backend and <registry-host>/ctms/ctms-frontend.
• Keep the private registry on the Tencent Cloud CVM as a self-hosted registry:2 instance protected by htpasswd.
• Trigger automation on pushes to dev, release, release/*, and main.
• Use GitHub Actions only as the orchestrator. Actual Docker build and push happen on the Tencent Cloud server over SSH.
• Keep docker-compose.yaml compatible with both local build workflows and private registry pulls.

Approaches Considered

• Recommended: GitHub Actions connects to the Tencent Cloud server over SSH and runs a server-local build-and-push script. This avoids GitHub-hosted runner limitations around insecure or self-signed private registries and keeps registry access local to the server.
• Alternative: GitHub Actions builds and pushes directly to <IP>:5000. This is simpler on paper but is fragile when the registry is exposed only as an IP endpoint and may use insecure or non-public TLS.
• Alternative: move first to a domain-backed HTTPS registry and then push directly from GitHub Actions. This is the clean long-term path but adds infrastructure work that is not required for the current goal.

Architecture

• A new GitHub Actions workflow triggers on pushes to dev, release, release/*, and main.
• The workflow authenticates to the Tencent Cloud server using SSH credentials stored in GitHub Secrets.
• The workflow syncs the repository contents to a fixed build directory such as /opt/ctms-build/<repo>.
• A server-local script logs in to the private registry, builds backend and frontend, applies branch-specific tags, and pushes the images to the registry.

Registry Naming

• Backend image: <registry-host>/ctms/ctms-backend
• Frontend image: <registry-host>/ctms/ctms-frontend

Tagging Strategy

• dev branch pushes publish:
  • <registry-host>/ctms/ctms-backend:dev-latest
  • <registry-host>/ctms/ctms-backend:dev-<short_sha>
  • <registry-host>/ctms/ctms-frontend:dev-latest
  • <registry-host>/ctms/ctms-frontend:dev-<short_sha>
• release branch pushes publish:
  • <registry-host>/ctms/ctms-backend:rc-release
  • <registry-host>/ctms/ctms-backend:rc-<short_sha>
  • <registry-host>/ctms/ctms-frontend:rc-release
  • <registry-host>/ctms/ctms-frontend:rc-<short_sha>
• release/* branch pushes publish:
  • <registry-host>/ctms/ctms-backend:rc-<release-branch>
  • <registry-host>/ctms/ctms-backend:rc-<short_sha>
  • <registry-host>/ctms/ctms-frontend:rc-<release-branch>
  • <registry-host>/ctms/ctms-frontend:rc-<short_sha>
• main branch pushes publish:
  • <registry-host>/ctms/ctms-backend:latest
  • <registry-host>/ctms/ctms-backend:sha-<short_sha>
  • <registry-host>/ctms/ctms-frontend:latest
  • <registry-host>/ctms/ctms-frontend:sha-<short_sha>

Server Requirements

• Docker installed on the Tencent Cloud server.
• A private registry:2 instance listening on <IP>:5000.
• htpasswd authentication configured for the registry.
• SSH access from GitHub Actions to the server.
• A writable build directory such as /opt/ctms-build.

GitHub Secrets

• TCLOUD_HOST
• TCLOUD_PORT
• TCLOUD_USER
• TCLOUD_SSH_KEY
• REGISTRY_HOST
• REGISTRY_USERNAME
• REGISTRY_PASSWORD

Compose Integration

• docker-compose.yaml should define image: for backend, backend-init, and frontend, with defaults based on private registry variables such as REGISTRY_HOST.
• Existing build: blocks stay in place so local docker compose up -d --build continues to work.
• Deployment hosts can export REGISTRY_HOST, then run docker login, docker compose pull, docker compose run --rm backend-init, and docker compose up -d.

Operational Notes

• This design assumes the server-local script runs on the same machine that can log in to the private registry reliably.
• The GitHub workflow should not embed long shell logic inline; the repository should own a script under scripts/ so the build logic stays versioned and testable.
• Direct verification of actual image publication depends on GitHub Actions reaching the Tencent Cloud server and cannot be proven locally without those secrets and network access.

Verification

• Push to dev and confirm both images appear with dev-latest and dev-<short_sha>.
• Push to release and confirm both images appear with rc-release and rc-<short_sha>.
• Push to release/* and confirm both images appear with rc-<release-branch> and rc-<short_sha>.
• Push to main and confirm both images appear with latest and sha-<short_sha>.
• Run docker compose config after compose changes and confirm the private registry defaults render correctly.
• Parse the workflow YAML successfully and inspect the remote build script for the expected tag logic and registry login behavior.