# 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 `nginx` 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, Nginx

---

### 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-nginx`

**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}`
- `nginx.image` to `${NGINX_IMAGE:-${REGISTRY_HOST:-127.0.0.1:5000}/ctms/ctms-nginx: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.