Compose + Nginx + MinIO
The runnable topology is in the root compose.yaml. The example Compose file
and contracts/infrastructure.json are teaching worksheets, not deployments.
The supported local entry point is Nginx; API, PostgreSQL, Redis and MinIO ports
are not published to the host.
| Role | Service / image | Persistence and readiness |
|---|---|---|
| API | api, built from Dockerfile / Python 3.12.11 |
Two stateless replicas; /health/ready; no host port |
| Load balancer | nginx:1.27.5-alpine |
Host port ${APP_PORT:-8080}; Docker DNS refresh 5 s; passive fail exclusion |
| Database | postgres:16.8-alpine |
postgres_data named volume; pg_isready |
| Sessions | redis:7.4.2-alpine |
redis_data named volume; AOF everysec; Redis PING |
| Object storage | MinIO RELEASE.2025-09-07T16-13-09Z, pinned by image digest in Compose |
minio_data named volume; MinIO readiness endpoint; S3 port 9000 and console 9001 are private |
| Migration job | Same API image | Runs ordered SQL migrations once before API replicas |
| Bucket bootstrap | Same pinned MinIO image, using its mc client |
Idempotently creates the private bucket, versioned policy, and restricted API user; replaces the prior policy without deleting volumes |
PostgreSQL and S3 hold different parts of an attachment: PostgreSQL is the source
of truth for metadata and access control; the private S3 bucket stores original
bytes under a random server-generated key. The bucket name is fixed as
messenger-attachments. No endpoint returns object keys or S3 credentials.
The MinIO root credentials are mounted only into MinIO and its one-shot bootstrap
job. The API receives a separate access key restricted to GetBucketLocation,
ListBucket with the objects/ prefix, and Get/Put/Delete on objects/*.
The bootstrap grants no anonymous policy. Verify
that from inside the Compose network with
py -3 -X utf8 student-tests/check_private_bucket.py; it expects an unsigned
bucket-list request to receive HTTP 403 and confirms MinIO has no host port
binding. The administrative console is not exposed.
Create local ignored secrets using scripts/init-local-secrets.ps1; never copy
secrets from another lab. Do not rotate credentials while retaining the
corresponding database or MinIO volumes. scripts/restart.bat / .sh restarts
the API, database, Redis, MinIO and Nginx without deleting volumes.
scripts/stop-one.bat / .sh stops only the API container whose hostname equals
TARGET_INSTANCE_ID and leaves it stopped for the failover check.
Attachment writes reserve PostgreSQL metadata in processing state before
writing S3. On success, the row becomes ready and the API returns 201. Errors
attempt to delete the object and mark the reservation failed; if compensation
cannot reach either store, the processing row remains visible to reconciliation.
Run scripts/reconcile_attachments.py in dry-run mode first. It only acts on
records/objects older than a 15-minute minimum grace period, marks stale uploads
failed, deletes old unreferenced objects, and reports missing objects for ready
metadata. --apply is required for changes.
MinIO, PostgreSQL, Redis, Nginx, and the Docker host are single-instance dependencies. This setup survives an API-replica failure and restarts with volumes, not loss of the Docker host or an individual state-store volume.