mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-27 07:21:14 +00:00
Oleksandr Bezdieniezhnykh
67530eb169
Probe API reachability after JWT mint; exit 7 with compose-up instructions when the perf stack is down. Document in environment and containerization guides. Co-authored-by: Cursor <cursoragent@cursor.com>
80 lines
4.2 KiB
Markdown
80 lines
4.2 KiB
Markdown
# 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](../tests/environment.md) § Platform and [ci_cd_pipeline.md](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).
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build
|
|
```
|
|
|
|
File contents:
|
|
|
|
```yaml
|
|
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](../tests/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
|