Version 0.2.1

Container image and local stack

The design and its reasons are on the wiki page Container and Deployment. This page shows how to use the image.

The image

Property Value
Registry ghcr.io/mavrovde/viafrei-api
Platforms linux/amd64, linux/arm64
Base gcr.io/distroless/static-debian12:nonroot, pinned by digest. There is no shell and no package manager.
Build multi-stage: a pinned Go builder, then CGO_ENABLED=0, -trimpath, and the version and commit stamped in with -ldflags
User nonroot (65532). The root filesystem can be mounted read-only, because the service writes no file.
Port 8080 (VFAPI_SERVER_LISTEN_ADDR=:8080)
Entry point /app serve. /app healthcheck exits 0 when /healthz answers ok within health.probe_timeout.
Secrets none in the image. The database URL is given at run time as VFAPI_DB_URL or VFAPI_DB_URL_FILE.
Labels org.opencontainers.image.source, .revision, .version, .title, .description, .url, .documentation

Tags

Tag Set by Moves
X.Y.Z, for example 0.2.0 a release tag vX.Y.Z never
X.Y a release tag to the newest patch of that minor
latest a release tag, but not a release candidate to the newest release
X.Y.Z-rc.N a release-candidate tag never
sha-<12 hex> a push to main once CI passed on it, if that commit is still the head of main when image.yml starts (otherwise the newer head's run publishes); every release never
edge a push to main once CI passed on it (image.yml follows the CI run) to the newest main only, never back to an older commit

Deploy by digest (ghcr.io/mavrovde/viafrei-api@sha256:…), not by a moving tag.

Run with Docker

docker run --rm --read-only --cap-drop ALL --security-opt no-new-privileges \
  -p "[::1]:8080:8080" \
  -e VFAPI_DB_URL_FILE=/run/secrets/db_url -v "$PWD/db_url:/run/secrets/db_url:ro" \
  ghcr.io/mavrovde/viafrei-api:edge

The configuration keys are the same as for the binary (configuration.md). Every key is set with a VFAPI_ environment variable. An unknown variable or a value out of bounds stops the container at once with exit status 78.

Resource limits for one instance are design targets, not yet measured: 256 MiB of memory, one CPU and 128 processes. The benchmark plan replaces them with measured values.

Verify an image

Images built from main and from release tags are signed with cosign (keyless, GitHub OIDC). They also carry an SBOM and a SLSA build-provenance attestation.

IMAGE=ghcr.io/mavrovde/viafrei-api@sha256:<digest>

# Signature: made by this repository's workflows, for main or a v* tag
cosign verify "$IMAGE" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/mavrovde/viafrei-api/\.github/workflows/(image|release)\.yml@refs/(heads/main|tags/v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?)$'

# Build provenance (SLSA)
gh attestation verify "oci://$IMAGE" --repo mavrovde/viafrei-api

# SBOM (SPDX), attached to the image by BuildKit
docker buildx imagetools inspect "$IMAGE" --format '{{ json .SBOM }}'

Each release page also lists the digest, the tags, these commands and the SBOM as an asset (RELEASING.md).

Local development with Compose

compose.yaml runs two services:

cp .env.example .env        # replace both placeholders
make up                     # build, start, wait until both are healthy
curl -s localhost:8080/v1/meta
make logs                   # follow the logs
make down                   # stop, keep the database
make reset                  # stop and delete this project's volume; the fixtures reload on the next up
make compose-test           # the CI smoke: healthz, readyz, meta and Schemathesis, then teardown

On a host without IPv6 loopback, set API_PUBLISH in .env to the IPv4 loopback address followed by :8080. make up and make compose-test run scripts/compose-guard.sh first (SSC-019). The guard does not parse .env itself. It asks Compose for the configuration it will run (docker compose config --format json), so Compose's own precedence and .env syntax apply. It refuses (exit 2) in these cases:

The upstream PostGIS image is published for linux/amd64 only. On an arm64 machine it runs under emulation, which is slower to start.

Build locally

make image                  # this machine's platform, loaded as viafrei-api:local
make image-multiarch        # amd64 and arm64, not loaded and not pushed