feat: Add Docker image versioning & DockerHub snapshot/restore workflow

[0xrushi]

Summary

• Add image: fields with CHRONICLE_REGISTRY / CHRONICLE_TAG env-var substitution to every custom service in the four docker-compose files (backends/advanced, extras/asr-services, extras/speaker-recognition, extras/havpe-relay)
• Add scripts/push-images.sh — tags and pushes locally-built images to DockerHub, records a release entry in scripts/releases.json
• Add scripts/pull-images.sh — pulls images from DockerHub and retags them so docker-compose can find them by version
• Add --use-prebuilt TAG flag to services.py start — sets CHRONICLE_REGISTRY/CHRONICLE_TAG and skips the build step, so pulled images are used directly
• Add unit tests covering the new flag, all image fields, and bash script input validation

Motivation

When something breaks after building from source there was no way to quickly roll back. This PR adds a snapshot → push → restore workflow:

# Snapshot a known-good state
DOCKERHUB_USERNAME=myuser ./scripts/push-images.sh v1.2.0 "stable before audio refactor"

# Restore it later (on any machine)
DOCKERHUB_USERNAME=myuser ./scripts/pull-images.sh v1.2.0
DOCKERHUB_USERNAME=myuser ./start.sh --use-prebuilt v1.2.0

How it works

CHRONICLE_REGISTRY / CHRONICLE_TAG env vars (both default to empty/latest)

When not set, docker-compose behaves exactly as before — images are named chronicle-backend:latest etc. and are built locally.

When set (e.g. CHRONICLE_REGISTRY=myuser/ CHRONICLE_TAG=v1.2.0), docker-compose resolves image names to myuser/chronicle-backend:v1.2.0 and uses the pre-pulled image without rebuilding.

push-images.sh

• Does not rebuild — pushes whatever is already built locally (ensures what you tested = what you push)
• Yellow warning (not failure) for any image not found locally — users may not run all services
• Also pushes :latest tag alongside the versioned tag
• Appends a release record to scripts/releases.json

pull-images.sh

• Pulls all images for the given tag and retags each to its local name so CHRONICLE_TAG=v1.2.0 works correctly

--use-prebuilt TAG in services.py

• Requires DOCKERHUB_USERNAME env var; exits with a clear error if missing
• Injects CHRONICLE_REGISTRY and CHRONICLE_TAG into the subprocess environment before docker-compose runs
• Forces build=False regardless of whether --build is also passed

Test plan

• Run ./start.sh --build — verify services start normally (no behaviour change without env vars)
• Run DOCKERHUB_USERNAME=testuser ./scripts/push-images.sh v0.1-test "test" without any images built — verify yellow warnings, non-zero exit
• Build images, run push script again — verify images appear on DockerHub
• Run DOCKERHUB_USERNAME=testuser ./scripts/pull-images.sh v0.1-test — verify pull + retag
• Run DOCKERHUB_USERNAME=testuser ./start.sh --use-prebuilt v0.1-test — verify services start without a build step
• Run ./start.sh --use-prebuilt v0.1-test (no DOCKERHUB_USERNAME) — verify clear error, no containers started
• Run cd tests && uv run pytest unit/test_docker_image_versioning.py -v — all 35 tests pass

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[AnkushMalaker]

Great!! Thanks!