Containerize & Deploy with CI/CD

# script_id: day_082_containerize_deploy/app
# Compact Atlas API to containerize (built on Day 77; see ../Day_077_fastapi_serving/fastapi_serving.md).
# Install: uv add fastapi uvicorn     Env: ATLAS_ENV, ATLAS_RELEASE, ORBIT_DATA (see config.py)
# Run: uv run uvicorn app:app --port 8000     No API key: ask() is an offline stand-in for R2's ask().
import re
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel, Field

from config import Settings

class AskRequest(BaseModel):
    question: str = Field(max_length=2000)
    top_k: int = 3

def keyword_ask(settings: Settings, question: str, top_k: int) -> dict:
    """Rank Orbit docs by shared words and cite the best ones (Day 77's stand-in shape)."""
    words = {w for w in re.findall(r"[a-z0-9]+", question.lower()) if len(w) > 3}
    scored = []
    for path in sorted((settings.data_dir / "docs").glob("*.md")):
        text = path.read_text(encoding="utf-8").lower()
        scored.append((sum(text.count(w) for w in words), path.stem))
    hits = [doc for score, doc in sorted(scored, reverse=True)[:top_k] if score > 0]
    return {"answer": f"See {', '.join(hits)}." if hits else "I don't know.", "citations": hits}

# script_id: day_082_containerize_deploy/app
def create_app(settings: Settings | None = None) -> FastAPI:
    settings = settings or Settings.from_env()     # fail fast, before the port opens

    @asynccontextmanager
    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
        app.state.settings = settings              # Day 77 also builds AsyncOpenAI here
        yield

    app = FastAPI(title="Atlas API", version=settings.release, lifespan=lifespan)

    @app.get("/healthz")
    async def healthz() -> dict:                   # liveness, plus "what is deployed?"
        return {"status": "ok", "env": settings.env, "release": settings.release}

    @app.get("/readyz")
    async def readyz(request: Request) -> dict:    # local dependencies only; never the model
        checks = {"settings": hasattr(request.app.state, "settings"),
                  "docs": any((settings.data_dir / "docs").glob("*.md"))}
        if not all(checks.values()):
            raise HTTPException(status_code=503, detail=checks)
        return {"status": "ready", "checks": checks}

    @app.post("/v1/ask")
    def ask(body: AskRequest) -> dict:             # plain def: file reads run in the threadpool
        return keyword_ask(settings, body.question, body.top_k)

    return app

app = create_app()          # `uvicorn app:app` imports this

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

# file: Dockerfile  (first version: single stage)
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.13.7 /uv /uvx /bin/
ENV UV_NO_DEV=1 UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
WORKDIR /app
# Dependencies first: this layer is reused until uv.lock changes
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv uv sync --locked
ENV PATH="/app/.venv/bin:$PATH"
RUN useradd --create-home app
USER app
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t atlas:dev .
docker run --rm -p 8000:8000 --env-file .env atlas:dev
curl -s localhost:8000/healthz      # in a second terminal

{"status":"ok","env":"dev","release":"dev"}

# file: Dockerfile.naive  (don't ship this)
FROM python:3.12
WORKDIR /app
COPY . .
RUN pip install fastapi uvicorn openai sentence-transformers
ENV OPENAI_API_KEY=sk-proj-not-a-real-key
HEALTHCHECK CMD curl -f http://localhost:8000/healthz || exit 1
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -f Dockerfile.naive -t atlas:naive .
docker image ls atlas
docker history --no-trunc --format '{{.Size}}  {{.CreatedBy}}' atlas:naive | head -5
docker run --rm atlas:naive whoami

REPOSITORY   TAG     SIZE
atlas        naive   9.12GB
atlas        dev     312MB
0B      HEALTHCHECK &{["CMD-SHELL" "curl -f http://localhost:8000/healthz || exit 1"] ...}
0B      ENV OPENAI_API_KEY=sk-proj-not-a-real-key
6.85GB  RUN /bin/sh -c pip install fastapi uvicorn openai sentence-transformers
root

# script_id: day_082_containerize_deploy/dockerfile_lint
# Static checks for the mistakes above. Stdlib only, no Docker needed.
# Run: python dockerfile_lint.py Dockerfile     (no argument: lint the naive example below)
import re
import sys
from pathlib import Path

SECRET_NAME = re.compile(r"^(ENV|ARG)\s+\S*(KEY|TOKEN|SECRET|PASSWORD)", re.I)
HEAVY = ("torch", "sentence-transformers", "transformers", "tensorflow")
NAIVE = """FROM python:3.12
COPY . .
RUN pip install fastapi uvicorn openai sentence-transformers
ENV OPENAI_API_KEY=sk-proj-not-a-real-key
HEALTHCHECK CMD curl -f http://localhost:8000/healthz || exit 1
"""

def lint(text: str) -> list[str]:
    found = []
    for n, raw in enumerate(text.splitlines(), 1):
        line = raw.strip()
        word = line.split(maxsplit=1)[0].upper() if line and not line.startswith("#") else ""
        if SECRET_NAME.match(line):
            found.append(f"line {n}: secret-like {word} is baked into the image: {line.split('=')[0]}")
        if word == "HEALTHCHECK" and "curl" in line:
            found.append(f"line {n}: curl healthcheck (python:*-slim has no curl)")
        if word == "RUN" and any(h in line for h in HEAVY):
            found.append(f"line {n}: heavy ML dependency in the API image")
    if not any(ln.strip().upper().startswith("USER ") for ln in text.splitlines()):
        found.append("no USER instruction: the container runs as root")
    return found

if __name__ == "__main__":
    path = Path(sys.argv[1]) if len(sys.argv) > 1 else None
    problems = lint(path.read_text(encoding="utf-8") if path else NAIVE)
    print("\n".join(problems) or "no problems found")
    sys.exit(1 if problems and path else 0)    # a real file with problems fails the CI step

line 3: heavy ML dependency in the API image
line 4: secret-like ENV is baked into the image: ENV OPENAI_API_KEY
line 5: curl healthcheck (python:*-slim has no curl)
no USER instruction: the container runs as root

# script_id: day_082_containerize_deploy/image_report
# Size and layer audit of a built image. Needs a running Docker daemon.
# Install: uv add --dev docker     Run: python image_report.py atlas:dev
import re
import sys

import docker
from docker.errors import DockerException, ImageNotFound

# python:* base images set `ENV GPG_KEY <public key id>` (docker-library/python Dockerfile; it verifies
# the Python download), so it is excluded: it is not a secret
SECRETISH = re.compile(r"(?<!GPG_)(KEY|TOKEN|SECRET|PASSWORD)\S*=\S+|sk-[A-Za-z0-9_-]{8,}", re.I)

def report(tag: str) -> int:
    image = docker.from_env().images.get(tag)
    print(f"{tag}: {image.attrs['Size'] / 1e6:.0f} MB")
    layers = image.history()                       # newest first; each has CreatedBy and Size
    for layer in sorted(layers, key=lambda h: h["Size"], reverse=True)[:3]:
        print(f"  {layer['Size'] / 1e6:9.1f} MB  {layer['CreatedBy'][:60]}")
    leaks = [SECRETISH.sub(lambda m: m.group(0)[:4] + "***", h["CreatedBy"])
             for h in layers if SECRETISH.search(h["CreatedBy"])]
    for leak in leaks:
        print(f"  LEAK: {leak[:80]}")
    return 1 if leaks else 0

if __name__ == "__main__":
    try:
        sys.exit(report(sys.argv[1] if len(sys.argv) > 1 else "atlas:dev"))
    except ImageNotFound as err:
        sys.exit(f"no such image: {err}")
    except DockerException as err:
        sys.exit(f"Docker isn't reachable ({type(err).__name__}); start Docker first")

atlas:naive: 9120 MB
     6850.0 MB  RUN /bin/sh -c pip install fastapi uvicorn openai sentence-tr
     1050.3 MB  RUN /bin/sh -c set -eux;  apt-get update;  apt-get install -y
      ...
  LEAK: ENV OPENAI_API_KEY=***

# file: Dockerfile
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:0.13.7 /uv /uvx /bin/
# UV_PYTHON_DOWNLOADS=0: use the image's Python, so both stages share one interpreter path
ENV UV_NO_DEV=1 UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=0
WORKDIR /app
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv uv sync --locked

FROM python:3.12-slim
RUN groupadd --system --gid 999 app \
 && useradd --system --gid 999 --uid 999 --create-home app
COPY --from=builder --chown=app:app /app /app
RUN mkdir -p /app/logs && chown app:app /app/logs
# The release is a build argument: not a secret, and visible on /healthz
ARG ATLAS_RELEASE=dev
ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1 ATLAS_RELEASE=${ATLAS_RELEASE}
USER app
WORKDIR /app
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

# file: .dockerignore
.venv
.env
.env.*
!.env.example
.git
logs/
__pycache__/
*.pyc
.pytest_cache/
tests/

no problems found
atlas:dev: 241 MB
       94.6 MB  RUN /bin/sh -c set -eux;  savedAptMark="$(apt-mark showmanual)"
       71.2 MB  COPY /app /app # buildkit

# script_id: day_082_containerize_deploy/config
# Atlas settings: every knob from the environment, checked once at startup (extends Day 12's MODEL/DATA_DIR).
# Install: stdlib only.   Env: ATLAS_* below; OPENAI_API_KEY is checked for presence, never stored.
from __future__ import annotations

import os
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Literal

DEPLOYED_REQUIRED = ("ATLAS_RELEASE", "ATLAS_REDIS_URL", "OPENAI_API_KEY")

class ConfigError(RuntimeError):
    """Startup configuration is invalid; the message lists every problem found."""

def _split(value: str) -> tuple[str, ...]:
    return tuple(part.strip() for part in value.split(",") if part.strip())

@dataclass(frozen=True)
class Settings:
    env: Literal["dev", "staging", "prod"]
    release: str
    model: str
    fallback_models: tuple[str, ...]
    embed_model: str
    data_dir: Path
    redis_url: str
    database_url: str | None
    api_url: str
    allowed_origins: tuple[str, ...]

# script_id: day_082_containerize_deploy/config
    # (the same class continues: the constructor reads every setting from the environment)
    @classmethod
    def from_env(cls, environ: Mapping[str, str] | None = None) -> Settings:
        e = os.environ if environ is None else environ
        env = e.get("ATLAS_ENV", "dev")
        problems: list[str] = []
        if env not in ("dev", "staging", "prod"):
            problems.append(f"ATLAS_ENV must be dev, staging or prod, not {env!r}")
        if env != "dev":                           # deployed environments get no silent defaults
            missing = [k for k in DEPLOYED_REQUIRED if not e.get(k)]
            if missing:
                problems.append("missing " + ", ".join(missing))
        origins = _split(e.get("ATLAS_ALLOWED_ORIGINS", "http://localhost:7860"))
        if env == "prod" and "*" in origins:
            problems.append("ATLAS_ALLOWED_ORIGINS='*' is not allowed in prod")
        if problems:
            raise ConfigError(f"ATLAS_ENV={env}: " + "; ".join(problems))
        return cls(
            env=env,  # type: ignore[arg-type]  (validated above)
            release=e.get("ATLAS_RELEASE", "dev"),
            model=e.get("ATLAS_MODEL", "gpt-6-luna"),
            fallback_models=_split(e.get("ATLAS_FALLBACK_MODELS", "gpt-6.1-terra")),
            embed_model=e.get("ATLAS_EMBED_MODEL", "text-embedding-3-small"),
            data_dir=Path(e.get("ORBIT_DATA", "datasets/orbit")),
            redis_url=e.get("ATLAS_REDIS_URL", "redis://localhost:6379/0"),
            database_url=e.get("ATLAS_DATABASE_URL") or None,
            api_url=e.get("ATLAS_API_URL", "http://localhost:8000"),
            allowed_origins=origins,
        )

if __name__ == "__main__":
    print(Settings.from_env().release, Settings.from_env().model)     # your shell: dev defaults
    try:
        Settings.from_env({"ATLAS_ENV": "staging", "ATLAS_RELEASE": "3f2c1ab"})
    except ConfigError as err:
        print(f"ConfigError: {err}")

dev gpt-6-luna
ConfigError: ATLAS_ENV=staging: missing ATLAS_REDIS_URL, OPENAI_API_KEY

# file: .env.example   (committed; copy to .env and fill in; .env stays git-ignored)
ATLAS_ENV=dev
# ATLAS_RELEASE is not set here: the image build sets it, and a value in this file would override it
ATLAS_MODEL=gpt-6-luna
ATLAS_FALLBACK_MODELS=gpt-6.1-terra
ATLAS_REDIS_URL=redis://localhost:6379/0
ATLAS_API_URL=http://localhost:8000
ATLAS_ALLOWED_ORIGINS=http://localhost:7860
OPENAI_API_KEY=

# script_id: day_082_containerize_deploy/test_deploy
# Install: uv add --dev pytest   (TestClient needs httpx2, which openai 3.x installs)
# Run: uv run pytest test_deploy.py -q     No key, no network.
import os

import pytest
from fastapi.testclient import TestClient

from app import create_app
from config import ConfigError, Settings

DATA = os.environ.get("ORBIT_DATA", "datasets/orbit")

def test_staging_lists_every_missing_var() -> None:
    with pytest.raises(ConfigError) as err:
        Settings.from_env({"ATLAS_ENV": "staging"})
    assert "missing ATLAS_RELEASE, ATLAS_REDIS_URL, OPENAI_API_KEY" in str(err.value)

def test_prod_rejects_wildcard_origins() -> None:
    env = {"ATLAS_ENV": "prod", "ATLAS_RELEASE": "3f2c1ab", "ATLAS_REDIS_URL": "redis://r:6379/0",
           "OPENAI_API_KEY": "test-not-a-key", "ATLAS_ALLOWED_ORIGINS": "*"}
    with pytest.raises(ConfigError, match="not allowed in prod"):
        Settings.from_env(env)

def test_healthz_reports_the_release() -> None:
    settings = Settings.from_env({"ATLAS_RELEASE": "3f2c1ab", "ORBIT_DATA": DATA})
    with TestClient(create_app(settings)) as client:      # `with` runs the lifespan
        assert client.get("/healthz").json()["release"] == "3f2c1ab"
        assert client.get("/readyz").status_code == 200

if __name__ == "__main__":
    raise SystemExit(pytest.main([__file__, "-q"]))

...                                                                      [100%]
3 passed in 0.41s

# file: compose.yaml
x-atlas: &atlas                       # shared by api, worker and ui: one image, three commands
  image: ${ATLAS_IMAGE:-atlas}:${ATLAS_TAG:-dev}
  env_file: ${ATLAS_ENV_FILE:-.env}   # secrets are read at run time, never baked in
  environment:
    ATLAS_ENV: ${ATLAS_ENV:-dev}
    ATLAS_REDIS_URL: redis://redis:6379/0   # the service name, not localhost
    ATLAS_API_URL: http://api:8000
    GRADIO_SERVER_NAME: 0.0.0.0             # the UI must listen beyond its own container
  restart: unless-stopped

services:
  redis:
    image: redis:8
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    volumes: [redis-data:/data]
    restart: unless-stopped

  api:
    <<: *atlas
    build: { context: ., args: { ATLAS_RELEASE: "${ATLAS_TAG:-dev}" } }
    ports: ["127.0.0.1:8000:8000"]      # localhost only: staging has no auth until Day 83
    volumes: [atlas-logs:/app/logs]
    depends_on:
      redis: { condition: service_healthy }
    healthcheck:                         # slim has no curl, so probe with Python
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/readyz', timeout=3)"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 20s

  worker:
    <<: *atlas
    command: ["rq", "worker", "atlas-reports", "--url", "redis://redis:6379/0", "--with-scheduler"]
    depends_on:
      redis: { condition: service_healthy }

  ui:
    <<: *atlas
    command: ["python", "atlas_ui.py"]  # Day 79's Gradio app
    ports: ["127.0.0.1:7860:7860"]
    depends_on:
      api: { condition: service_healthy }

volumes:
  redis-data:
  atlas-logs:

cp .env.example .env              # then fill in OPENAI_API_KEY
docker compose up --build --wait  # --wait returns once every healthcheck passes
docker compose ps

NAME            SERVICE   STATUS
atlas-api-1     api       Up 31 seconds (healthy)
atlas-redis-1   redis     Up 37 seconds (healthy)
atlas-ui-1      ui        Up 9 seconds
atlas-worker-1  worker    Up 31 seconds

# file: .github/workflows/deploy.yml
name: deploy
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
defaults:
  run:
    shell: bash                       # ${VAR,,} below lowercases; GHCR names must be lowercase
concurrency:
  group: deploy-${{ github.ref }}     # one deploy at a time per branch
  cancel-in-progress: false

jobs:
  test:                               # Day 19: mocked tests and the Dockerfile linter, no key
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.3.3        # pin a full version: there is no @v10 tag
        with: { enable-cache: true }
      - run: uv sync --locked --all-extras --dev
      - run: uv run pytest -m "not eval and not live" -q
      - run: uv run python scripts/dockerfile_lint.py Dockerfile

  eval:                               # Day 47's fast suite is the quality gate
    needs: test
    # Fork PRs get no secrets: skip (shown as "skipped", never as a green pass)
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      ATLAS_MODEL: gpt-6-luna
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.3.3
        with: { enable-cache: true }
      - run: uv sync --locked --all-extras --dev
      - run: uv run pytest -m eval -q             # a regression fails here; nothing below runs

  build:
    needs: eval
    if: github.event_name == 'push'               # PRs never publish images
    runs-on: ubuntu-latest
    permissions: { contents: read, packages: write }
    steps:
      - uses: actions/checkout@v7
      - run: |
          IMAGE="ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/atlas:${GITHUB_SHA}"
          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
          docker build --build-arg ATLAS_RELEASE="${GITHUB_SHA}" -t "$IMAGE" .
          docker push "$IMAGE"

  deploy-staging:
    needs: build
    runs-on: [self-hosted, staging]
    environment: staging                          # protection rules + staging-only secrets
    permissions: { contents: read, packages: read }
    env:
      ATLAS_ENV: staging
      ATLAS_ENV_FILE: /etc/atlas/staging.env      # secrets live on the host, outside the checkout
      ATLAS_RELEASES_FILE: /var/lib/atlas/releases
    steps:
      - uses: actions/checkout@v7
      - run: |
          echo "ATLAS_IMAGE=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/atlas" >> "$GITHUB_ENV"
          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
      - run: python3 scripts/deploy.py deploy "$GITHUB_SHA"
      - run: python3 scripts/smoke_test.py http://localhost:8000
      - run: python3 scripts/deploy.py mark-good "$GITHUB_SHA"
      - if: failure()                             # deploy or smoke failed: put the last good SHA back
        run: python3 scripts/deploy.py rollback

# script_id: day_082_containerize_deploy/smoke_test
# Post-deploy smoke test: three requests, exit code 1 on any failure. Stdlib only.
# Run: python smoke_test.py http://localhost:8000     Env: ATLAS_SMOKE_KEY (optional bearer token)
# Needs the API running (compose stack or a deploy); without one it reports FAILED, by design.
import json
import os
import sys
import urllib.request

CANARY = "How do I configure the Redis broker?"

def _call(url: str, payload: dict | None, api_key: str | None) -> dict:
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(url, data=data, headers={"Content-Type": "application/json"})
    if api_key:
        req.add_header("Authorization", f"Bearer {api_key}")
    with urllib.request.urlopen(req, timeout=30) as resp:    # raises HTTPError on 4xx/5xx
        return json.load(resp)

def smoke(base_url: str, *, api_key: str | None = None) -> bool:
    base = base_url.rstrip("/")
    try:
        health = _call(f"{base}/healthz", None, api_key)
        _call(f"{base}/readyz", None, api_key)
        body = _call(f"{base}/v1/ask", {"question": CANARY}, api_key)
    except OSError as err:                  # URLError, HTTPError and timeouts are all OSErrors
        print(f"smoke FAILED: {err}")
        return False
    nested = body.get("answer")             # R5's AskResponse nests citations under "answer"
    cites = body.get("citations") or (nested.get("citations") if isinstance(nested, dict) else None)
    if not cites:
        print(f"smoke FAILED: canary answer has no citations: {body}")
        return False
    print(f"smoke OK release={health.get('release', '?')[:7]} citations={len(cites)}")
    return True

if __name__ == "__main__":
    url = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("ATLAS_API_URL", "http://localhost:8000")
    sys.exit(0 if smoke(url, api_key=os.environ.get("ATLAS_SMOKE_KEY")) else 1)

smoke OK release=3f2c1ab citations=3

# script_id: day_082_containerize_deploy/deploy
# Deploy, record and roll back releases on a compose host. Stdlib only.
# Run: python deploy.py deploy <sha> | mark-good <sha> | rollback | status   (--dry-run: print commands)
# Needs Docker + compose.yaml in the working dir, and `docker login ghcr.io` for private images.
import os
import subprocess
import sys
from pathlib import Path

HISTORY = Path(os.environ.get("ATLAS_RELEASES_FILE", ".atlas-releases"))   # one good SHA per line
DRY_RUN = "--dry-run" in sys.argv

def compose(*args: str, tag: str) -> None:
    print(f"$ ATLAS_TAG={tag[:12]} docker compose {' '.join(args)}")
    if not DRY_RUN:
        subprocess.run(["docker", "compose", *args], check=True, env={**os.environ, "ATLAS_TAG": tag})

def deploy(sha: str) -> None:
    compose("pull", "api", "worker", "ui", tag=sha)   # fail on a missing image before stopping anything
    compose("up", "-d", "--wait", tag=sha)            # non-zero exit if a healthcheck never passes

def good_releases() -> list[str]:
    return HISTORY.read_text().split() if HISTORY.exists() else []

def mark_good(sha: str) -> None:
    HISTORY.parent.mkdir(parents=True, exist_ok=True)
    with HISTORY.open("a") as f:
        f.write(sha + "\n")
    print(f"recorded {sha[:12]} as last good")

def rollback() -> None:
    good = good_releases()
    if not good:
        sys.exit("rollback: no known-good release recorded; fix forward instead")
    print(f"rolling back to {good[-1][:12]}")
    deploy(good[-1])

if __name__ == "__main__":
    args = [a for a in sys.argv[1:] if a != "--dry-run"]
    action = args[0] if args else "status"
    if action == "deploy":
        deploy(args[1])
    elif action == "mark-good":
        mark_good(args[1])
    elif action == "rollback":
        rollback()
    else:
        print(f"known-good releases: {good_releases()[-5:] or 'none yet'}")

$ ATLAS_TAG=9b81e07c44d2 docker compose pull api worker ui
$ ATLAS_TAG=9b81e07c44d2 docker compose up -d --wait
container atlas-api-1 is unhealthy
rolling back to 3f2c1ab0d9e1
$ ATLAS_TAG=3f2c1ab0d9e1 docker compose pull api worker ui
$ ATLAS_TAG=3f2c1ab0d9e1 docker compose up -d --wait