# 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:

1. Dedicated Gitea runner on a separate machine.
2. Local developer machine with Docker installed.
3. 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:

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

The script writes:

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

## Upload artifact

Upload to production:

```bash
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:

```bash
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:

```bash
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:

```bash
python scripts/smoke_public_auth_flow.py
python scripts/smoke_public_upload_flow.py
```

Then verify project detail endpoint:

```bash
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