Skip to content

README.md

Latest commit

 

History

History
122 lines (83 loc) · 5.43 KB

README.md

File metadata and controls

122 lines (83 loc) · 5.43 KB

Container Deployment Template

This folder contains public-safe Docker deployment templates for DiffAudit Platform.

Only templates are committed. Real environment files, hostnames, TLS settings, proxy rules, OAuth secrets, API keys, and server notes must stay in the deployment environment.

For the full productization and migration contract, see ../docs/portability.md.

Files

File Purpose
docker-compose.example.yml Generic two-service compose template for the web app and Go gateway
compose.env.example Compose interpolation values such as image tag, bind address, and snapshot host path
compose.ghcr.env.example Compose interpolation values for published GHCR images
runtime.env.example Runtime environment variables passed into containers

Build Traceable Images

From the repository root:

powershell -ExecutionPolicy Bypass -File .\scripts\build_docker_images.ps1

The script tags images with the current Git revision and writes OCI labels including org.opencontainers.image.revision.

Published GHCR Images

The repository can publish release images to GitHub Container Registry through .github/workflows/publish-images.yml.

Image Purpose
ghcr.io/deliciousbuding/diffaudit-platform-web Next.js product surface
ghcr.io/deliciousbuding/diffaudit-platform-api Go gateway

The workflow publishes:

  • sha-<short-sha> for immutable revision pinning;
  • main for the current default branch image;
  • latest for simple demos and local evaluation.

Production-like deployments should prefer sha-<short-sha> or an explicitly recorded revision tag. latest is convenient but should not be the rollback anchor.

Pull From GHCR

For a compose deployment that pulls published images instead of building locally:

Copy-Item .\deploy\compose.ghcr.env.example .\deploy\.env
# Edit DIFFAUDIT_IMAGE_TAG to a real immutable tag, for example sha-1c9d67d.
docker compose --env-file .\deploy\.env -f .\deploy\docker-compose.example.yml pull
docker compose --env-file .\deploy\.env -f .\deploy\docker-compose.example.yml up -d

Use GHCR when the host has reliable registry egress and you want reproducible image provenance without moving tar archives. If registry egress is unreliable, build or transfer a revision-labeled image archive and still validate the OCI revision label before restart.

Run With Compose

Copy-Item .\deploy\compose.env.example .\deploy\.env
Copy-Item .\deploy\runtime.env.example .\deploy\runtime.env
docker compose --env-file .\deploy\.env -f .\deploy\docker-compose.example.yml up -d --build

Before running this outside local development:

  • replace placeholder credentials only in untracked files;
  • point DIFFAUDIT_PUBLIC_SNAPSHOT_DIR at a sanitized snapshot bundle;
  • set DIFFAUDIT_PLATFORM_URL and DIFFAUDIT_CORS_ALLOWED_ORIGINS for the deployment environment;
  • pin image tags to a Git revision or GHCR sha-<short-sha> tag;
  • keep proxy, certificate, firewall, and host-specific process details outside this repository.

Server-Local Deployment Boundary

Servers may use compose, systemd, or another process manager. Keep those real units and env files local to the server because they usually contain host paths, bind addresses, domains, proxy assumptions, or secret file locations.

A safe deployment record should capture only:

  • Git revision;
  • image tag and OCI revision label;
  • snapshot manifest timestamp;
  • health check result.

Do not copy server-local unit files or deployment notes back into the public repository.

Verify

docker compose --env-file .\deploy\.env -f .\deploy\docker-compose.example.yml ps
docker image inspect diffaudit-platform-web:local --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'
docker image inspect diffaudit-platform-api:local --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'

The gateway should serve /health, and the web app should load through the configured platform URL.

For GHCR tags, also verify the pulled image reference and the redacted build metadata:

docker image inspect ghcr.io/deliciousbuding/diffaudit-platform-api:sha-1c9d67d --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'
curl http://127.0.0.1:8780/health

You can automate the revision-label check with the repository helper:

# Verify local images built by scripts/build_docker_images.ps1 with its default tag.
python .\scripts\verify_image_provenance.py --local-tag (git rev-parse --short=12 HEAD)

# Verify pulled GHCR images pinned to an immutable tag.
python .\scripts\verify_image_provenance.py --ghcr-tag sha-1c9d67d --expected-revision 1c9d67d

The helper checks org.opencontainers.image.revision and exits non-zero when a web or API image does not match the expected Git revision. Add --expected-source https://github.com/DeliciousBuding/DiffAudit-Platform when you also want to verify the public source label.

Migration Checklist

  • Pin image tags to a Git revision or immutable GHCR sha-<short-sha> tag.
  • Copy only sanitized public snapshot files into the configured snapshot directory.
  • Recreate real environment values in the target secret store or untracked compose env files.
  • Keep public domains, TLS/proxy rules, SSH aliases, process-manager files, and host notes outside Git.
  • Confirm /health and the web landing page before exposing the deployment.