compose.yml

# Local development Postgres.
#
# The maintainer's standing direction is Docker Compose over hand-built
# `docker run` invocations, for full portability — this file, plus
# `backends/crates/sms-test-support`'s conversion to drive it via `docker compose`
# instead of raw `docker run`, is the first step.
#
# **Correction, containerize-tooling PR:** an earlier revision of this
# comment predicted `scripts/demo.sh` would eventually point at this same
# file (a distinct Compose *project name*, the same way the test harness
# does below). That script is gone now — replaced by `compose.dev.yaml`,
# its own full, from-source stack — but it does NOT `include:`/`-f` this
# file. Considered and rejected once actually built: Compose's multi-file
# merge rules for list-typed keys (`ports`, specifically) made publishing a
# *different* host port than this file's own `VSMS_POSTGRES_PORT` default
# more fragile to verify than a six-line duplicated `postgres:` service —
# and `compose.demo.yaml` had already independently made the identical
# call for the identical reason. See `compose.dev.yaml`'s own header
# comment for the full reasoning; this paragraph exists so this file
# doesn't keep asserting a plan nothing downstream of it actually took.
#
# What is deliberately NOT here: `deploy/docker-compose.yml` is the
# production-shaped stack (Caddy edge, the migrate job, the real gateway/
# worker binaries), `compose.demo.yaml` is the GHCR-only showcase, and
# `compose.dev.yaml` is the from-source developer stack — all three
# untouched by this file. This one is Postgres alone, for whichever local
# process wants a database — `cargo run`, a live test suite, a human at a
# `psql` prompt — without pulling in anything else.
#
# Default project name is `vsms` (a bare `docker compose up` uses it).
# `backends/crates/sms-test-support` overrides it with `-p vsms-test-harness` and
# `VSMS_POSTGRES_PORT=55432`, so the two can never collide on a container,
# network, volume, or host port — Compose scopes every resource it creates
# to the project name that created it (`com.docker.compose.project`, a real
# label Compose itself enforces, not a convention this repo has to
# maintain), so a teardown of one project structurally cannot reach a
# container started under the other. See that crate's own module doc for
# the full reasoning, including what does and doesn't change from the
# `docker run`-based design it replaces.

name: vsms

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: vsms
      POSTGRES_PASSWORD: vsms
      POSTGRES_DB: vsms
    # Loopback only, never `0.0.0.0` — matches the `docker run` design this
    # replaces (`backends/crates/sms-test-support`'s own module doc). Compose's
    # default `<port>:<container-port>` shorthand binds every interface;
    # that was caught live, not assumed, running this exact mapping and
    # seeing `0.0.0.0:55432->5432/tcp` in `docker ps` before this line was
    # added.
    ports:
      - "127.0.0.1:${VSMS_POSTGRES_PORT:-5432}:5432"
    # A real, protocol-level readiness check — `pg_isready` performs the
    # actual startup handshake, not a bare TCP probe. The official image
    # accepts TCP connections briefly during its own internal
    # restart-after-initdb before it is actually ready to serve queries,
    # and a bare port check races that window (this bit
    # `backends/crates/sms-test-support` once already; see its own module doc).
    # `docker compose up --wait` blocks on this reporting `healthy`.
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vsms -d vsms"]
      interval: 2s
      timeout: 3s
      retries: 30
    volumes:
      - vsms_pgdata:/var/lib/postgresql/data

volumes:
  vsms_pgdata: