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

Tencent Cloud Private Registry Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add CI that triggers remote builds on a Tencent Cloud CVM and pushes private backend and frontend images into a self-hosted Docker Registry protected by htpasswd, for dev, release, release/*, and main.

Architecture: GitHub Actions runs on pushes to dev, release, release/*, and main, connects to the Tencent Cloud server over SSH, syncs the repository into a fixed build directory, and invokes a repository-owned shell script that logs in to the private registry, builds the images locally on the server, tags them according to branch, and pushes them.

Tech Stack: GitHub Actions, SSH, Docker, self-hosted registry:2, Docker Compose, FastAPI, Node.js

---

Task 1: Replace GHCR Workflow with Tencent Registry Publish Workflow

Files:

• Modify: .github/workflows/publish-images.yml

Step 1: Define push triggers and remote execution secrets

Ensure the workflow triggers on pushes to dev, release, release/*, and main, and uses repository secrets for SSH host, port, user, SSH key, registry host, registry username, and registry password.

Step 2: Sync repository content to the Tencent Cloud server

Use an SSH-capable action or shell step to create the remote build directory and copy the current repository contents into /opt/ctms-build/<repo>.

Step 3: Invoke the remote publish script

Run the repository-owned remote script over SSH with environment values for:

• branch name
• commit SHA
• registry host
• registry credentials

Step 4: Verify workflow structure

Run: ruby -e 'require "yaml"; YAML.load_file(".github/workflows/publish-images.yml")' Expected: PASS

Task 2: Add Remote Build-And-Push Script

Files:

• Create: scripts/build-and-push-registry.sh

Step 1: Implement branch-aware tag logic

For dev, compute:

• dev-latest
• dev-<short_sha>

For release, compute:

• rc-release
• rc-<short_sha>

For release/*, compute:

• rc-<release-branch>
• rc-<short_sha>

For main, compute:

• latest
• sha-<short_sha>

Fail fast for unsupported branches.

Step 2: Implement registry login and image builds

Log in to ${REGISTRY_HOST} using the supplied username and password, then build:

• ${REGISTRY_HOST}/ctms/ctms-backend
• ${REGISTRY_HOST}/ctms/ctms-frontend

Step 3: Push both tags for both images

Push every computed tag explicitly so the branch and immutable tags are both published.

Step 4: Verify script syntax

Run: bash -n scripts/build-and-push-registry.sh Expected: PASS

Task 3: Point Compose Defaults at the Private Registry

Files:

• Modify: docker-compose.yaml

Step 1: Replace GHCR defaults with private registry defaults

Set:

• backend.image to ${BACKEND_IMAGE:-${REGISTRY_HOST:-127.0.0.1:5000}/ctms/ctms-backend:latest}
• backend-init.image to ${BACKEND_IMAGE:-${REGISTRY_HOST:-127.0.0.1:5000}/ctms/ctms-backend:latest}
• frontend.image to ${FRONTEND_IMAGE:-${REGISTRY_HOST:-127.0.0.1:5000}/ctms/ctms-frontend:latest}

Keep the current build: blocks intact.

Step 2: Verify rendered compose

Run: docker compose config Expected: PASS with private registry image defaults rendered.

Task 4: Update Deployment Documentation

Files:

• Modify: README.md
• Modify: docs/guides/release-checklist.md

Step 1: Document the Tencent registry flow

Explain that GitHub Actions triggers remote builds on the Tencent Cloud server and publishes to the private registry at <IP>:5000.

Step 2: Document deployment commands

Show that deployment hosts must run:

• docker login <IP>:5000
• docker compose pull
• docker compose run --rm backend-init
• docker compose up -d

Step 3: Update release checklist

Add checks for remote publish success on dev, release, release/*, and main, and for deployment-host registry authentication.

Task 5: End-To-End Local Verification

Files:

• Verify only

Step 1: Parse the workflow YAML

Run: ruby -e 'require "yaml"; YAML.load_file(".github/workflows/publish-images.yml")' Expected: PASS

Step 2: Verify script syntax

Run: bash -n scripts/build-and-push-registry.sh Expected: PASS

Step 3: Render compose

Run: docker compose config Expected: PASS

Step 4: Inspect documentation

Run: sed -n '1,120p' README.md Expected: PASS with Tencent private registry deployment steps present.

Run: sed -n '1,120p' docs/guides/release-checklist.md Expected: PASS with private registry release verification present.