Runtime Image Build Host Runbook

Purpose: build API/Worker runtime image artifacts outside the production host.

Why

Production host currently runs Gitea, Gitea Actions runner, Web/API/Worker/Postgres/Redis. It has about 2 CPU and 1.7GiB memory. Building API/Worker images there can make SSH/Web/API unstable, so production must only load prebuilt images and restart containers.

Allowed build hosts

Use one of:

Dedicated Gitea runner on a separate machine.
Local developer machine with Docker installed.
Temporary cloud build VM that is destroyed after artifact upload.

Do not use the production host unless an emergency exception is explicitly approved with ALLOW_SHARED_PRODUCTION_BUILD_HOST=true.

Build steps

From a clean checkout of the target release commit:

git checkout develop
git pull --ff-only origin develop
scripts/build_release_images.sh v0.1.5

The script writes:

dist/release-images/xiaoxia-runtime-images-v0.1.5.tar

Upload artifact

Upload to production:

scp dist/release-images/xiaoxia-runtime-images-v0.1.5.tar \
  xiaoxia-server:/var/lib/xiaoxia-saas-production/runtime-images-v0.1.5.tar

Release tag

After the runtime image tar exists on production:

git tag -a v0.1.5 -m "Release v0.1.5"
git push origin v0.1.5

The Gitea production deploy passes RELEASE_VERSION=v0.1.5 to infra/docker/deploy-production.sh. The deploy must fail if the runtime image tar is missing.

Manual production deploy fallback

If tag deploy is unavailable but the runtime image tar has been uploaded:

ssh xiaoxia-server \
  "HOST_PREFIX= RELEASE_VERSION=v0.1.5 \
   RUNTIME_IMAGE_TAR=/var/lib/xiaoxia-saas-production/runtime-images-v0.1.5.tar \
   /var/lib/xiaoxia-saas-production/repo/infra/docker/deploy-production.sh"

Verification

Run from local repo after deploy:

python scripts/smoke_public_auth_flow.py
python scripts/smoke_public_upload_flow.py

Then verify project detail endpoint:

curl -fsS https://saas.xiaoxiajianji.com/api/v1/projects/<project_id>

Required release notes

Record:

tag
commit
runtime image tar path
public auth smoke result
public upload smoke result
production API image tag
production Worker image tag

2.2 KiB Raw Permalink Blame History