satellite-provider/_docs/02_document/deployment/containerization.md

Containerization

Docker Image

Base image: mcr.microsoft.com/dotnet/aspnet:10.0 (was :8.0 through cycle 3 — bumped by AZ-500) Build image: mcr.microsoft.com/dotnet/sdk:10.0 (was :8.0 through cycle 3 — bumped by AZ-500) Build strategy: Multi-stage (restore → build → publish → runtime) Target platform: Native host architecture — no platform: pins in compose. Mac M1 dev and the Woodpecker arm64 agent run linux/arm64; the Woodpecker amd64 agent runs linux/amd64 for production images. On arm64, Docker build stages install Debian protobuf-compiler and set PROTOBUF_PROTOC (bundled Grpc.Tools protoc segfaults). See tests/environment.md § Platform and ci_cd_pipeline.md § Multi-Architecture Strategy.

Registry tags (Woodpecker 02-build-push): {branch}-arm (arm64 agent), {branch}-amd64 (amd64 agent). Production deploy (suite/_infra/deploy/satellite-provider/) pulls ${BRANCH}-amd64 via Watchtower. Exposed ports: 8080 (HTTP), 8081 (management/metrics)

Container Composition (docker-compose.yml)

Service	Image	Ports (host:container)	Purpose
postgres	postgres:16	5433:5432	Database (host port 5433 chosen to avoid conflicts with sibling-project Postgres instances on dev laptops)
api	Custom (Dockerfile)	18980:8080, 18981:8081	Application

Compose overlays (dev / test / perf)

The default docker-compose.yml publishes Postgres on host port 5433 so tools on the host can reach the DB. On multi-repo dev laptops another local Postgres container may already bind 5433, producing address already in use when starting the stack.

Use case	Compose files	Postgres host port
Default local dev	docker-compose.yml	5433:5432
Integration tests (Step 11)	docker-compose.tests.yml only	None — internal compose network only
Perf tests / dev API without host DB (Step 15)	docker-compose.yml + docker-compose.perf.yml	None — overlay clears the publish

Perf overlay (docker-compose.perf.yml)

Unsets the postgres port mapping so only the API port (18980) is published to the host. Postgres remains reachable as postgres:5432 inside the compose network (same as integration tests).

docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build

File contents:

services:
  postgres:
    ports: !reset []

Use this when Step 15 (scripts/run-performance-tests.sh) or manual perf probing against https://localhost:18980 must run while another project owns host port 5433.

run-performance-tests.sh probes API reachability after JWT mint and before PT-01. If the stack is down, the script exits 7 and prints the docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build command. See environment.md § Performance tests.

Integration tests do not use this overlay — scripts/run-tests.sh starts docker-compose.tests.yml alone, which never publishes postgres to the host.

Mount	Container Path	Purpose
./tiles	/app/tiles	Tile image storage
./ready	/app/ready	Output artifacts (CSV, summary, stitched, ZIP)
./logs	/app/logs	Serilog file output
postgres_data (named)	/var/lib/postgresql/data	Database persistence

Health Checks

• PostgreSQL: pg_isready -U postgres (interval 5s, timeout 5s, retries 5)
• API: depends on postgres health (startup ordering)

Environment Variables

Variable	Source	Purpose
ASPNETCORE_ENVIRONMENT	docker-compose	Environment selection
ASPNETCORE_URLS	docker-compose	Listen address
ConnectionStrings__DefaultConnection	docker-compose	DB connection string
MapConfig__ApiKey	Host env GOOGLE_MAPS_API_KEY	Google Maps API key
AZAION_REVISION	Build arg (CI_COMMIT_SHA)	Git revision tracking

Build Labels (OCI)

• org.opencontainers.image.revision — Git commit SHA
• org.opencontainers.image.created — Build timestamp
• org.opencontainers.image.source — Repository URL