gpt-6-astra/03-infra-management/RESPONSE.md

gpt-6-astra/03-infra-management/RUNBOOK.md

cp .env.example .env
chmod 600 .env
openssl rand -hex 32
openssl rand -hex 32

docker compose config --quiet
docker compose build api
docker compose up -d --wait --wait-timeout 180
docker compose ps
curl --fail --show-error http://127.0.0.1:8080/

docker compose ps
docker compose exec -T api python /app/healthcheck.py
docker compose exec -T proxy nginx -t
curl --fail --show-error http://127.0.0.1:8080/health/live
curl --fail --show-error http://127.0.0.1:8080/health/ready
docker compose logs --tail=100 proxy api db cache

umask 077
mkdir -p backups
backup="backups/app-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose exec -T db sh -ec \
  'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_dump --host=127.0.0.1 --username="$POSTGRES_USER" --dbname="$POSTGRES_DB" --format=custom' \
  > "$backup.partial" && mv "$backup.partial" "$backup"
docker compose exec -T db pg_restore --list < "$backup" > /dev/null

backup=backups/REPLACE-WITH-VERIFIED-BACKUP.dump
test -r "$backup" && docker compose stop proxy api &&
docker compose exec -T db sh -ec \
  'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_restore --host=127.0.0.1 --username="$POSTGRES_USER" --dbname="$POSTGRES_DB" --clean --if-exists --no-owner --no-privileges --single-transaction --exit-on-error' \
  < "$backup" && docker compose up -d --wait --wait-timeout 180

docker compose up -d --no-build --pull never --wait --wait-timeout 180

gpt-6-astra/03-infra-management/TASK.md

gpt-6-astra/03-infra-management/.dockerignore

# Allowlist: credentials, backups, documentation, and VCS files stay out.
*
!Dockerfile
!requirements.txt
!app.py
!healthcheck.py

gpt-6-astra/03-infra-management/.env.example

# Copy to .env, chmod 600 .env, then set two different generated passwords.
# Empty passwords deliberately make Compose fail before startup.
POSTGRES_USER=app
POSTGRES_DB=app
POSTGRES_PASSWORD=
REDIS_PASSWORD=

# Use a unique API_IMAGE tag for each release; retain the previous image.
API_IMAGE=local-json-api:local
HTTP_BIND_ADDRESS=127.0.0.1
HTTP_PORT=8080

gpt-6-astra/03-infra-management/.gitignore

.env
.env.*
!.env.example
backups/
__pycache__/
*.py[cod]

gpt-6-astra/03-infra-management/app.py

"""Minimal JSON API supplied because the original deployment had no app source."""

import os
from contextlib import closing

import psycopg2
import redis
from flask import Flask, jsonify
from redis.backoff import NoBackoff
from redis.retry import Retry

app = Flask(__name__)


@app.get("/")
def index():
    return jsonify(service="api", status="ok")


@app.get("/health/live")
def live():
    return jsonify(status="alive")


@app.get("/health/ready")
def ready():
    """Test real dependency access with bounded I/O; never expose exceptions."""
    try:
        # Separate fields avoid URL-encoding problems with password characters.
        with closing(psycopg2.connect(
            host=os.environ["POSTGRES_HOST"],
            port=int(os.environ["POSTGRES_PORT"]),
            user=os.environ["POSTGRES_USER"],
            password=os.environ["POSTGRES_PASSWORD"],
            dbname=os.environ["POSTGRES_DB"],
            connect_timeout=2,
            options="-c statement_timeout=2000 -c lock_timeout=2000",
        )) as connection:
            with connection.cursor() as cursor:
                cursor.execute("SELECT 1")
                if cursor.fetchone() != (1,):
                    return jsonify(status="unavailable"), 503

        with redis.Redis(
            host=os.environ["REDIS_HOST"],
            port=int(os.environ["REDIS_PORT"]),
            password=os.environ["REDIS_PASSWORD"],
            socket_connect_timeout=2,
            socket_timeout=2,
            retry=Retry(NoBackoff(), 0),
        ) as cache:
            if cache.ping() is not True:
                return jsonify(status="unavailable"), 503
    except (psycopg2.Error, redis.exceptions.RedisError, KeyError, ValueError):
        return jsonify(status="unavailable"), 503

    return jsonify(status="ready")

gpt-6-astra/03-infra-management/compose.yaml

name: small-json-api

x-logging: &logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  proxy:
    image: nginx:1.28.0-alpine
    user: "101:101"
    entrypoint: ["nginx"]
    command: ["-g", "daemon off;"]
    ports:
      - "${HTTP_BIND_ADDRESS:-127.0.0.1}:${HTTP_PORT:-8080}:8080"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks: [frontend]
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-q", "-T", "8", "-O", "/dev/null", "http://127.0.0.1:8080/health/ready"]
      interval: 15s
      timeout: 10s
      start_period: 10s
      retries: 3
    restart: unless-stopped
    stop_signal: SIGQUIT
    stop_grace_period: 40s
    read_only: true
    tmpfs:
      - /tmp:size=16m,mode=1777
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    cpus: 0.50
    mem_limit: 128m
    pids_limit: 64
    logging: *logging

  api:
    image: ${API_IMAGE:-local-json-api:local}
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      POSTGRES_HOST: db
      POSTGRES_PORT: "5432"
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:-app}
      REDIS_HOST: cache
      REDIS_PORT: "6379"
      REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}
    expose: ["5000"]
    networks: [frontend, backend]
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "/app/healthcheck.py"]
      interval: 15s
      timeout: 10s
      start_period: 20s
      retries: 3
    init: true
    restart: unless-stopped
    stop_grace_period: 40s
    read_only: true
    tmpfs:
      - /tmp:size=32m,mode=1777
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    cpus: 1.0
    mem_limit: 256m
    pids_limit: 128
    logging: *logging

  db:
    image: postgres:17.6-bookworm
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:-app}
      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    expose: ["5432"]
    networks: [backend]
    healthcheck:
      test:
        - CMD-SHELL
        - >-
          PGPASSWORD="$${POSTGRES_PASSWORD}"
          psql --host=127.0.0.1 --username="$${POSTGRES_USER}"
          --dbname="$${POSTGRES_DB}" --no-password --set=ON_ERROR_STOP=1
          --command='SELECT 1' >/dev/null
      interval: 10s
      timeout: 5s
      start_period: 30s
      retries: 5
    restart: unless-stopped
    stop_grace_period: 60s
    security_opt: ["no-new-privileges:true"]
    shm_size: 128m
    cpus: 1.0
    mem_limit: 512m
    pids_limit: 200
    logging: *logging

  cache:
    image: redis:8.2.1-alpine
    user: redis
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}
    command:
      - /bin/sh
      - -ec
      - >-
        exec redis-server --save "" --appendonly no
        --maxmemory 128mb --maxmemory-policy allkeys-lru
        --requirepass "$$REDIS_PASSWORD"
    expose: ["6379"]
    networks: [backend]
    healthcheck:
      test:
        - CMD-SHELL
        - REDISCLI_AUTH="$${REDIS_PASSWORD}" redis-cli --host 127.0.0.1 ping | grep -qx PONG
      interval: 10s
      timeout: 5s
      start_period: 10s
      retries: 3
    restart: unless-stopped
    stop_grace_period: 15s
    read_only: true
    tmpfs:
      - /data:size=16m,mode=1777
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    cpus: 0.50
    mem_limit: 256m
    pids_limit: 64
    logging: *logging

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

volumes:
  postgres_data:

gpt-6-astra/03-infra-management/Dockerfile

FROM python:3.13.7-slim-bookworm

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=1

WORKDIR /app
RUN groupadd --gid 10001 app \
    && useradd --uid 10001 --gid app --no-create-home --shell /usr/sbin/nologin app

# All runtime dependencies, including transitive dependencies, are pinned.
# Do not silently resolve unpinned packages or compile native dependencies.
COPY requirements.txt ./
RUN python -m pip install --only-binary=:all: --no-deps -r requirements.txt \
    && python -m pip check

COPY app.py healthcheck.py ./
USER 10001:10001
EXPOSE 5000
HEALTHCHECK --interval=15s --timeout=10s --start-period=20s --retries=3 \
    CMD ["python", "/app/healthcheck.py"]
CMD ["gunicorn", "--bind=0.0.0.0:5000", "--workers=2", "--worker-class=gthread", "--threads=2", "--timeout=30", "--graceful-timeout=30", "--keep-alive=5", "--worker-tmp-dir=/tmp", "--max-requests=1000", "--max-requests-jitter=100", "--access-logfile=-", "--error-logfile=-", "app:app"]

gpt-6-astra/03-infra-management/healthcheck.py

"""An HTTP readiness probe using only the Python standard library."""

import json
import sys
from urllib.error import URLError
from urllib.request import urlopen


def main():
    try:
        with urlopen("http://127.0.0.1:5000/health/ready", timeout=8) as response:
            payload = json.load(response)
            return int(response.status != 200 or payload != {"status": "ready"})
    except (URLError, OSError, ValueError):
        return 1


if __name__ == "__main__":
    sys.exit(main())

gpt-6-astra/03-infra-management/nginx.conf

worker_processes 1;
pid /tmp/nginx.pid;
error_log /dev/stderr warn;

events {
  worker_connections 1024;
}

http {
  access_log /dev/stdout;
  server_tokens off;
  client_body_temp_path /tmp/client_body;
  proxy_temp_path /tmp/proxy;
  fastcgi_temp_path /tmp/fastcgi;
  uwsgi_temp_path /tmp/uwsgi;
  scgi_temp_path /tmp/scgi;

  client_max_body_size 1m;
  client_header_timeout 10s;
  client_body_timeout 15s;
  keepalive_timeout 30s;
  send_timeout 30s;

  # Docker DNS; refresh addresses when an API container is replaced.
  resolver 127.0.0.11 valid=10s ipv6=off;
  resolver_timeout 5s;
  upstream api_backend {
    zone api_backend 64k;
    server api:5000 resolve;
    keepalive 16;
  }

  server {
    listen 8080;
    server_name _;

    location / {
      proxy_pass http://api_backend;
      proxy_http_version 1.1;
      proxy_set_header Connection "";
      proxy_set_header Host $http_host;
      proxy_set_header X-Forwarded-Host $http_host;
      # This nginx is the first HTTP ingress; discard client-supplied identity.
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $remote_addr;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header Forwarded "";
      proxy_connect_timeout 5s;
      proxy_send_timeout 30s;
      proxy_read_timeout 35s;
      proxy_next_upstream off;
    }
  }
}

gpt-6-astra/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

# Complete transitive runtime set for Python 3.13; install with --no-deps.
blinker==1.9.0
click==8.2.1
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==3.0.2
packaging==25.0
Werkzeug==3.1.3

gpt-6-astra/03-infra-management/test_health.py

"""Offline unit checks with dependency doubles, not container/integration tests.

Run: python3 -B -m unittest -v test_health.py
No third-party packages, sockets, or Docker daemon are used.
"""

import importlib.util
import io
import os
from pathlib import Path
import types
import unittest
from unittest.mock import MagicMock, patch
from urllib.error import HTTPError, URLError

import healthcheck


class DatabaseError(Exception):
    pass


class CacheError(Exception):
    pass


class ReadinessTests(unittest.TestCase):
    def setUp(self):
        flask = types.ModuleType("flask")
        flask.Flask = lambda name: types.SimpleNamespace(
            get=lambda route: lambda handler: handler
        )
        flask.jsonify = lambda **payload: payload
        self.pg = types.ModuleType("psycopg2")
        self.pg.Error = DatabaseError
        self.pg.connect = MagicMock()
        self.connection = self.pg.connect.return_value
        self.cursor = self.connection.cursor.return_value.__enter__.return_value
        self.cursor.fetchone.return_value = (1,)
        self.redis = types.ModuleType("redis")
        self.redis.exceptions = types.SimpleNamespace(RedisError=CacheError)
        self.redis.Redis = MagicMock()
        self.cache = self.redis.Redis.return_value.__enter__.return_value
        self.cache.ping.return_value = True
        backoff = types.ModuleType("redis.backoff")
        backoff.NoBackoff = MagicMock()
        retry = types.ModuleType("redis.retry")
        retry.Retry = MagicMock()
        modules = {
            "flask": flask, "psycopg2": self.pg, "redis": self.redis,
            "redis.backoff": backoff, "redis.retry": retry,
        }
        spec = importlib.util.spec_from_file_location(
            "api_under_test", Path(__file__).with_name("app.py")
        )
        self.api = importlib.util.module_from_spec(spec)
        with patch.dict("sys.modules", modules):
            spec.loader.exec_module(self.api)
        environment = {
            "POSTGRES_HOST": "db", "POSTGRES_PORT": "5432",
            "POSTGRES_USER": "app", "POSTGRES_DB": "app",
            "POSTGRES_PASSWORD": "unit-test:@/$ value",
            "REDIS_HOST": "cache", "REDIS_PORT": "6379",
            "REDIS_PASSWORD": "unit-test-redis",
        }
        self.env = patch.dict(os.environ, environment, clear=True)
        self.env.start()
        self.addCleanup(self.env.stop)

    def test_ready_checks_both_dependencies_and_closes_connections(self):
        self.assertEqual(self.api.ready(), {"status": "ready"})
        self.cursor.execute.assert_called_once_with("SELECT 1")
        self.cache.ping.assert_called_once()
        self.connection.close.assert_called_once()
        self.redis.Redis.return_value.__exit__.assert_called_once()
        self.assertEqual(
            self.pg.connect.call_args.kwargs["password"], "unit-test:@/$ value"
        )

    def test_database_connection_failure_is_unavailable_without_details(self):
        self.pg.connect.side_effect = DatabaseError("private credential detail")
        self.assertEqual(self.api.ready(), ({"status": "unavailable"}, 503))
        self.redis.Redis.assert_not_called()

    def test_database_query_failure_closes_connection(self):
        self.cursor.execute.side_effect = DatabaseError("query failed")
        self.assertEqual(self.api.ready(), ({"status": "unavailable"}, 503))
        self.connection.close.assert_called_once()

    def test_unexpected_database_result_is_unavailable(self):
        self.cursor.fetchone.return_value = None
        self.assertEqual(self.api.ready(), ({"status": "unavailable"}, 503))
        self.connection.close.assert_called_once()

    def test_redis_failure_is_unavailable_and_closes_client(self):
        self.cache.ping.side_effect = CacheError("private credential detail")
        self.assertEqual(self.api.ready(), ({"status": "unavailable"}, 503))
        self.redis.Redis.return_value.__exit__.assert_called_once()

    def test_negative_redis_reply_is_unavailable(self):
        self.cache.ping.return_value = False
        self.assertEqual(self.api.ready(), ({"status": "unavailable"}, 503))

    def test_missing_configuration_is_unavailable(self):
        del os.environ["POSTGRES_PASSWORD"]
        self.assertEqual(self.api.ready(), ({"status": "unavailable"}, 503))

    def test_liveness_does_not_require_dependencies(self):
        self.assertEqual(self.api.live(), {"status": "alive"})
        self.pg.connect.assert_not_called()
        self.redis.Redis.assert_not_called()


class ProbeTests(unittest.TestCase):
    def test_http_status_and_payload_must_both_indicate_readiness(self):
        cases = [
            (200, b'{"status":"ready"}', 0),
            (503, b'{"status":"ready"}', 1),
            (200, b'{"status":"unavailable"}', 1),
            (200, b'not json', 1),
            (200, b'null', 1),
        ]
        for status, payload, expected in cases:
            with self.subTest(status=status, payload=payload):
                response = io.BytesIO(payload)
                response.status = status
                with patch.object(healthcheck, "urlopen", return_value=response):
                    self.assertEqual(healthcheck.main(), expected)

    def test_connection_timeout_and_http_errors_fail_the_probe(self):
        errors = [
            URLError("connection refused"), TimeoutError("timeout"),
            HTTPError("http://unused", 503, "unavailable", {}, None),
        ]
        self.addCleanup(errors[-1].close)
        for error in errors:
            with self.subTest(error=type(error).__name__):
                with patch.object(healthcheck, "urlopen", side_effect=error):
                    self.assertEqual(healthcheck.main(), 1)


if __name__ == "__main__":
    unittest.main()

sonnet-5.5/03-infra-management/RESPONSE.md

sonnet-5.5/03-infra-management/RUNBOOK.md

cp .env.example .env
sed -i.bak "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 24)|; \
            s|^REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -hex 24)|" .env && rm .env.bak
chmod 600 .env

docker compose build
docker compose up -d

docker compose ps                                   # every service: (healthy)
curl -fsS -i http://127.0.0.1:8080/healthz          # 200 through nginx to the app
docker compose exec db pg_isready -h 127.0.0.1      # accepting connections
docker compose exec cache redis-cli ping            # PONG
docker compose logs --tail=50 proxy api             # access + error logs (stdout/stderr)

docker compose ps --format '{{.Service}}\t{{.Ports}}'   # only proxy shows a host port
ss -ltn | grep -E ':(5432|6379|8000)\b' || echo "no db/cache/api ports on host"

mkdir -p backups
f=backups/app-$(date +%Y%m%d-%H%M%S).dump
( umask 077; docker compose exec -T db sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > "$f" )
test -s "$f" && docker compose exec -T db pg_restore --list < "$f" | head -5   # sanity check

docker compose exec db sh -c 'createdb -U "$POSTGRES_USER" restore_test'
docker compose exec -T db sh -c 'pg_restore -U "$POSTGRES_USER" -d restore_test --no-owner' < "$f"
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d restore_test -c "\dt"'
docker compose exec db sh -c 'dropdb -U "$POSTGRES_USER" restore_test'

docker compose stop proxy api
docker compose exec -T db sh -c \
  'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --single-transaction --clean --if-exists --no-owner' \
  < backups/app-YYYYMMDD-HHMMSS.dump
docker compose up -d

# deploy: take a backup first, note the current tag, then
sed -i.bak 's/^API_TAG=.*/API_TAG=2026-09-29a/' .env && rm .env.bak
docker compose build api && docker compose up -d --no-deps api

# roll back: set API_TAG back to the previous tag (kept locally as an image)
sed -i.bak 's/^API_TAG=.*/API_TAG=<previous-tag>/' .env && rm .env.bak
docker compose up -d --no-deps --no-build api    # fails loudly if that tag is gone

docker compose run --rm --no-deps proxy nginx -t    # validate first
docker compose up -d
docker compose restart proxy                        # single-file bind mount: a replaced file
                                                    # is only seen after a restart, not a reload

sonnet-5.5/03-infra-management/TASK.md

sonnet-5.5/03-infra-management/.dockerignore

# Never bake secrets, VCS history, or operational files into the image.
.env
.env.*
!.env.example
.git
.gitignore
backups/
__pycache__/
*.pyc
Dockerfile
.dockerignore
compose.yaml
nginx.conf
TASK.md
RUNBOOK.md
RESPONSE.md

sonnet-5.5/03-infra-management/.env.example

# Copy to .env and fill in the two passwords (commands in RUNBOOK.md).
# .env is git-ignored and docker-ignored. Never commit it.
# Compose refuses to start while a required value is empty.

POSTGRES_USER=app
POSTGRES_DB=app
# Required. Use URL-safe characters only (hex is ideal): these values are
# embedded in DATABASE_URL / REDIS_URL. Example: openssl rand -hex 24
POSTGRES_PASSWORD=
REDIS_PASSWORD=

# Where nginx is published on the host. Default is loopback only.
# For a public host use PROXY_BIND=0.0.0.0 PROXY_PORT=80 (and put TLS in front).
PROXY_BIND=127.0.0.1
PROXY_PORT=8080

# Image tag for the API. Bump per release; roll back by setting the old tag.
API_TAG=local

# Optional overrides (defaults shown).
# APP_MODULE=app:app
# WEB_CONCURRENCY=2

sonnet-5.5/03-infra-management/.gitignore

.env
backups/
__pycache__/
*.pyc

sonnet-5.5/03-infra-management/compose.yaml

name: apistack

# Single-host deployment. Compose restarts crashed containers but does not
# reschedule, scale, or fail over; see RUNBOOK.md for what that means in practice.

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  proxy:
    image: nginx:1.28-alpine
    restart: unless-stopped
    ports:
      # The only published port in the stack. Loopback by default (see .env.example).
      - "${PROXY_BIND:-127.0.0.1}:${PROXY_PORT:-8080}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks: [edge]
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      # End to end: nginx -> gunicorn -> app. 127.0.0.1 because busybox wget
      # resolves "localhost" to ::1 first and nginx only listens on IPv4.
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:80/healthz"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 5s
    read_only: true
    tmpfs:
      - /tmp
      - /var/cache/nginx
    cap_drop: [ALL]
    cap_add: [CHOWN, SETGID, SETUID, NET_BIND_SERVICE]
    security_opt: ["no-new-privileges:true"]
    logging: *default-logging
    deploy:
      resources:
        limits: { cpus: "0.50", memory: 128M }

  api:
    build: .
    image: apistack/api:${API_TAG:-local}
    restart: unless-stopped
    environment:
      # postgresql:// (not postgres://) is accepted by libpq, psycopg2 and SQLAlchemy.
      DATABASE_URL: postgresql://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}@db:5432/${POSTGRES_DB:-app}
      REDIS_URL: redis://:${REDIS_PASSWORD:?REDIS_PASSWORD must be set in .env}@cache:6379/0
      APP_MODULE: ${APP_MODULE:-app:app}
      WEB_CONCURRENCY: ${WEB_CONCURRENCY:-2}
      # Trust X-Forwarded-* from nginx. Safe because this service is not
      # published and only nginx shares a network with it besides the backend.
      FORWARDED_ALLOW_IPS: "*"
    # No `ports:`. Reached only by nginx over the edge network.
    networks: [edge, backend]
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      # Requires the app to serve GET /healthz -> 2xx (urlopen raises on 4xx/5xx).
      # Ideally that handler runs SELECT 1 and a Redis PING with short timeouts.
      test:
        - CMD
        - python
        - -c
        - "import urllib.request as u; u.urlopen('http://127.0.0.1:8000/healthz', timeout=3)"
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 20s
    read_only: true
    tmpfs:
      - /tmp
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    stop_grace_period: 35s  # > gunicorn --graceful-timeout 30
    logging: *default-logging
    deploy:
      resources:
        limits: { cpus: "1.00", memory: 512M }

  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
      POSTGRES_DB: ${POSTGRES_DB:-app}
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks: [backend]
    healthcheck:
      # -h 127.0.0.1 forces TCP. During first-run init the entrypoint runs a
      # temporary server on the unix socket only; a socket check would report
      # "ready" before the real server (and the init scripts) are done.
      test: ['CMD-SHELL', 'pg_isready -h 127.0.0.1 -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    stop_grace_period: 30s
    logging: *default-logging
    deploy:
      resources:
        limits: { cpus: "1.00", memory: 1G }

  cache:
    image: redis:7.4-alpine
    restart: unless-stopped
    # Treated as a disposable cache: no persistence, bounded memory, LRU eviction.
    # If the app keeps sessions or queues here, switch to noeviction + appendonly
    # yes and add a volume. Password is passed as an argument (not `sh -c`) so the
    # image entrypoint still drops privileges to the redis user.
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:?REDIS_PASSWORD must be set in .env}
      - --save
      - ""
      - --appendonly
      - "no"
      - --maxmemory
      - 128mb
      - --maxmemory-policy
      - allkeys-lru
    environment:
      REDISCLI_AUTH: ${REDIS_PASSWORD:?REDIS_PASSWORD must be set in .env}  # lets redis-cli auth without -a
    networks: [backend]
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    logging: *default-logging
    deploy:
      resources:
        limits: { cpus: "0.50", memory: 192M }

networks:
  edge: {}
  backend:
    # No route to or from the outside world. Only api, db and cache attach here.
    internal: true

volumes:
  pgdata: {}

sonnet-5.5/03-infra-management/Dockerfile

FROM python:3.13-slim-bookworm

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

# Fixed UID/GID so file ownership and `user:` overrides are predictable.
RUN groupadd --system --gid 10001 app \
 && useradd --system --uid 10001 --gid app --no-create-home \
            --home-dir /nonexistent --shell /usr/sbin/nologin app

WORKDIR /app

# Dependencies first: this layer is only rebuilt when requirements.txt changes.
# psycopg2-binary ships its own libpq, so no compiler or -dev packages are needed.
COPY requirements.txt .
RUN pip install -r requirements.txt

# Application code stays root-owned and read-only to the runtime user.
# .dockerignore keeps .env, .git and backups out of this COPY.
COPY . .

# Module:callable that gunicorn serves. Override with APP_MODULE if the app
# is not `app.py` exposing `app`.
ENV APP_MODULE=app:app \
    WEB_CONCURRENCY=2 \
    GUNICORN_CMD_ARGS="--bind 0.0.0.0:8000 --timeout 30 --graceful-timeout 30 --keep-alive 5 --max-requests 1000 --max-requests-jitter 100 --worker-tmp-dir /dev/shm --access-logfile - --error-logfile -"

USER 10001:10001
EXPOSE 8000

# `exec` makes gunicorn PID 1 so it receives SIGTERM directly and drains cleanly.
CMD ["sh", "-c", "exec gunicorn \"$APP_MODULE\""]

sonnet-5.5/03-infra-management/nginx.conf

worker_processes auto;
pid /tmp/nginx.pid;                 # container root fs is read-only; /tmp is tmpfs
error_log /dev/stderr warn;

events {
  worker_connections 1024;
}

http {
  server_tokens off;
  default_type application/json;

  log_format main '$remote_addr "$request" $status $body_bytes_sent '
                  'rt=$request_time urt=$upstream_response_time rid=$request_id';
  access_log /dev/stdout main;

  # Slow-client and body limits. Adjust client_max_body_size to the largest
  # legitimate JSON payload.
  client_max_body_size 1m;
  client_header_timeout 10s;
  client_body_timeout 10s;
  send_timeout 30s;
  keepalive_timeout 30s;

  # Docker's embedded DNS. Re-resolving api:8000 (via the variable below) means a
  # recreated api container is picked up without reloading nginx, and nginx can
  # start even if api is briefly absent.
  resolver 127.0.0.11 valid=10s ipv6=off;

  server {
    listen 80 default_server;
    server_name _;

    set $api_upstream http://api:8000;

    # Set here (not in locations) so the error location inherits them.
    add_header X-Request-ID $request_id always;
    add_header X-Content-Type-Options nosniff always;

    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    # This nginx is the first hop, so overwrite instead of appending a
    # client-supplied X-Forwarded-For (prevents spoofing). If another proxy or
    # load balancer sits in front, switch to the realip module instead.
    proxy_set_header X-Forwarded-For   $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Request-ID      $request_id;

    # Tuned for a JSON API behind gunicorn (--timeout 30): fail fast on connect,
    # and read timeout just above the worker timeout so gunicorn reports its
    # own failure before nginx gives up.
    proxy_connect_timeout 5s;
    proxy_send_timeout    30s;
    proxy_read_timeout    35s;
    proxy_next_upstream   off;      # never replay a possibly non-idempotent request

    error_page 502 503 504 = @upstream_unavailable;

    location = /healthz {
      access_log off;               # probes every few seconds; keep logs useful
      proxy_pass $api_upstream;
    }

    location / {
      proxy_pass $api_upstream;
    }

    location @upstream_unavailable {
      internal;
      default_type application/json;
      return 503 '{"error":"service_unavailable"}\n';
    }
  }
}

sonnet-5.5/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

fable-5.1/03-infra-management/RESPONSE.md

fable-5.1/03-infra-management/RUNBOOK.md

cp .env.example .env            # then set POSTGRES_PASSWORD and REDIS_PASSWORD
chmod 600 .env
docker compose config --quiet   # validates the file; fails if a required variable is empty
API_TAG=$(git rev-parse --short HEAD) docker compose build
API_TAG=$(git rev-parse --short HEAD) docker compose up -d

docker run --rm -v "$PWD/nginx.conf:/etc/nginx/nginx.conf:ro" nginx:1.28-alpine nginx -t
docker compose exec proxy nginx -s reload

docker compose ps                        # every service should show "(healthy)"
curl -fsS "http://localhost:${HTTP_PORT:-80}/healthz"
# {"checks":{"cache":"ok","database":"ok"},"status":"ok"}

mkdir -p backups
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > "backups/app-$(date +%Y%m%dT%H%M%S).dump"

docker compose stop api
docker compose exec -T db sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner' \
  < backups/app-<timestamp>.dump
docker compose start api

docker image ls api                       # find the previous tag
API_TAG=<previous-sha> docker compose up -d --no-build api
curl -fsS "http://localhost:${HTTP_PORT:-80}/healthz"

fable-5.1/03-infra-management/TASK.md

fable-5.1/03-infra-management/.dockerignore

# Keep secrets, VCS data and deployment files out of the image (COPY . .).
.env
.env.*
.git
.gitignore
.dockerignore
Dockerfile
compose.yaml
compose.override.yaml
nginx.conf
*.md
backups/

# Python build artefacts / local environments
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/

fable-5.1/03-infra-management/.env.example

# Copy this file to .env and fill in the blanks. .env is git-ignored and
# docker-ignored: never commit it or bake it into an image.
#
# Generate each secret with something like:
#   openssl rand -hex 24
# Use only letters and digits (or - and _): the values are embedded in
# DATABASE_URL / REDIS_URL, so other characters must be percent-encoded, and
# a literal $ must be written as $$.

# --- Postgres (required) -------------------------------------------------
POSTGRES_USER=app
POSTGRES_PASSWORD=
POSTGRES_DB=app

# --- Redis (required) ----------------------------------------------------
REDIS_PASSWORD=

# --- Proxy ---------------------------------------------------------------
# The only published port. Use e.g. 8080 if 80 is taken locally.
HTTP_PORT=80

# --- API -----------------------------------------------------------------
# Image name/tag for the api service. Deployments set API_TAG to the git SHA
# they built (see RUNBOOK.md) so an earlier image can be rolled back to.
API_IMAGE=api
API_TAG=dev
GUNICORN_WORKERS=2
GUNICORN_THREADS=4
LOG_LEVEL=info

fable-5.1/03-infra-management/.gitignore

# Local secrets and data never go into version control.
.env
.env.*
!.env.example
backups/

__pycache__/
*.py[cod]
.venv/
venv/

fable-5.1/03-infra-management/app.py

"""Minimal WSGI entrypoint for the API container.

The supplied deployment had no application module in this directory. This one
makes the stack self-consistent: gunicorn imports ``app:app`` and the health
checks in the Dockerfile, compose.yaml and nginx.conf hit a real endpoint. If
the real application lives elsewhere, keep its module as the gunicorn target
and give it a ``GET /healthz`` with the same semantics.
"""

import os

import psycopg2
import redis
from flask import Flask, jsonify
from werkzeug.middleware.proxy_fix import ProxyFix

# Fail at import time (clear error in the container logs) rather than on the first request.
DATABASE_URL = os.environ["DATABASE_URL"]
REDIS_URL = os.environ["REDIS_URL"]
CHECK_TIMEOUT_SECONDS = 2

app = Flask(__name__)
# Exactly one trusted proxy (nginx) sits in front of the API.
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1)


@app.get("/")
def index():
    return jsonify(service="api", status="ok")


def _check_database():
    conn = psycopg2.connect(DATABASE_URL, connect_timeout=CHECK_TIMEOUT_SECONDS)
    try:
        with conn.cursor() as cur:
            cur.execute("SELECT 1")
            cur.fetchone()
    finally:
        conn.close()


def _check_cache():
    client = redis.Redis.from_url(
        REDIS_URL,
        socket_connect_timeout=CHECK_TIMEOUT_SECONDS,
        socket_timeout=CHECK_TIMEOUT_SECONDS,
    )
    try:
        client.ping()
    finally:
        client.close()


@app.get("/healthz")
def healthz():
    """Readiness-style check: the process serves requests and its dependencies answer.

    Failure details are logged, not returned, so connection strings never leak.
    """
    checks = {}
    for name, check in (("database", _check_database), ("cache", _check_cache)):
        try:
            check()
            checks[name] = "ok"
        except Exception as exc:  # noqa: BLE001 - any failure must yield 503, never a crash
            app.logger.warning("health check %s failed: %s", name, type(exc).__name__)
            checks[name] = "error"
    healthy = all(state == "ok" for state in checks.values())
    body = jsonify(status="ok" if healthy else "degraded", checks=checks)
    return body, (200 if healthy else 503)

fable-5.1/03-infra-management/compose.yaml

# Small Python API behind nginx, with Postgres and Redis.
#
# Secrets and per-environment values come from ./.env (copy .env.example).
# Variables written as ${VAR:?message} are required: `docker compose config`
# and `docker compose up` fail early with that message instead of starting
# with a default password.
#
# Only the proxy publishes a port. Services talk over two explicit networks:
#   frontend: proxy <-> api
#   backend : api <-> db, cache   (internal: no route to the host or internet)
#
# Restart policies, log rotation and resource limits are the sensible defaults
# a single Compose host can enforce; anything beyond that (rolling deploys,
# multi-node scheduling, secret distribution) is out of scope for Compose.

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  proxy:
    image: nginx:1.28-alpine
    restart: unless-stopped
    ports:
      - "${HTTP_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - frontend
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      # Goes through nginx to the API, so "healthy" means requests are actually served.
      test: ["CMD", "wget", "-q", "--spider", "-T", "5", "http://127.0.0.1/healthz"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 10s
    security_opt:
      - no-new-privileges:true
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 128M
    logging: *default-logging

  api:
    build:
      context: .
    # Tag builds (e.g. with the git SHA) so a previous image can be rolled back to.
    image: ${API_IMAGE:-api}:${API_TAG:-dev}
    restart: unless-stopped
    init: true
    read_only: true
    tmpfs:
      - /tmp
    expose:
      - "8000"
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER:?set POSTGRES_USER in .env}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@db:5432/${POSTGRES_DB:?set POSTGRES_DB in .env}
      REDIS_URL: redis://:${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}@cache:6379/0
      GUNICORN_WORKERS: ${GUNICORN_WORKERS:-2}
      GUNICORN_THREADS: ${GUNICORN_THREADS:-4}
      LOG_LEVEL: ${LOG_LEVEL:-info}
    networks:
      - frontend
      - backend
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    # healthcheck: inherited from the image (HEALTHCHECK in the Dockerfile, GET /healthz).
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s   # matches gunicorn graceful_timeout
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 256M
          pids: 256
    logging: *default-logging

  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB in .env}
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend
    healthcheck:
      # -h forces a TCP check: the entrypoint's temporary init-time server only
      # listens on a unix socket, so this cannot report healthy too early.
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    security_opt:
      - no-new-privileges:true
    shm_size: 256m           # parallel queries; Docker's 64m default is too small
    stop_signal: SIGINT      # postgres "fast" shutdown: clean, does not wait for idle clients
    stop_grace_period: 60s
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
    logging: *default-logging

  cache:
    image: redis:8-alpine
    restart: unless-stopped
    # Used as a cache: bounded memory with LRU eviction and no disk persistence.
    # If it is ever used as a queue/session store, switch the policy to noeviction
    # and enable appendonly with a volume.
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
      - --maxmemory
      - 128mb
      - --maxmemory-policy
      - allkeys-lru
      - --save
      - ""
      - --appendonly
      - "no"
    environment:
      # Read by redis-cli in the healthcheck; avoids putting the password on its command line.
      REDISCLI_AUTH: ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    security_opt:
      - no-new-privileges:true
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 192M       # maxmemory 128mb plus overhead
    logging: *default-logging

networks:
  frontend:
  backend:
    internal: true

volumes:
  db_data:

fable-5.1/03-infra-management/Dockerfile

# syntax=docker/dockerfile:1

# API image: pinned slim base, dependencies installed only from the pinned
# requirements.txt, production WSGI server (gunicorn), unprivileged runtime user.
#
# For fully reproducible builds also pin the base image to a digest:
#   docker buildx imagetools inspect python:3.13-slim     # copy the sha256
#   ARG PYTHON_IMAGE=python:3.13-slim@sha256:<digest>
ARG PYTHON_IMAGE=python:3.13-slim

# ---------------------------------------------------------------------------
# builder: self-contained virtualenv with the pinned dependencies
# ---------------------------------------------------------------------------
FROM ${PYTHON_IMAGE} AS builder

ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=1 \
    PYTHONDONTWRITEBYTECODE=1

RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Only requirements.txt is copied here, so this layer stays cached until the
# pinned dependency set changes. It is the single source of truth for what is
# installed; nothing is installed ad hoc.
WORKDIR /build
COPY requirements.txt ./
RUN pip install --require-virtualenv -r requirements.txt

# ---------------------------------------------------------------------------
# runtime: no build tooling, non-root service account
# ---------------------------------------------------------------------------
FROM ${PYTHON_IMAGE} AS runtime

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH"

# Fixed uid/gid so ownership is predictable if a volume is ever mounted.
RUN groupadd --system --gid 10001 app \
 && useradd --system --uid 10001 --gid app --home-dir /app --no-create-home \
      --shell /usr/sbin/nologin app

WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
# Application code stays root-owned (read-only for the service account).
# .dockerignore keeps .env, .git, docs and the compose/nginx files out of the image.
COPY . .

USER app

EXPOSE 8000

# Same endpoint nginx and Compose rely on; stdlib only, so no curl/wget needed.
# A non-2xx response raises in urlopen and the check exits non-zero.
HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=3 \
  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=4)"]

# Worker count, timeouts and logging are set in gunicorn.conf.py.
CMD ["gunicorn", "--config", "gunicorn.conf.py", "app:app"]

fable-5.1/03-infra-management/gunicorn.conf.py

"""Gunicorn configuration for the API container.

Values can be overridden per environment through the variables read below
(see .env.example); everything else keeps gunicorn's defaults.
"""

import os

bind = "0.0.0.0:8000"

# Threaded workers suit a small I/O-bound JSON API (database and Redis round trips).
worker_class = "gthread"
workers = int(os.environ.get("GUNICORN_WORKERS", "2"))
threads = int(os.environ.get("GUNICORN_THREADS", "4"))

# Request limits. nginx's proxy_read_timeout is aligned with `timeout`.
timeout = int(os.environ.get("GUNICORN_TIMEOUT", "30"))
graceful_timeout = 30
keepalive = 5
max_requests = 1000  # recycle workers periodically to bound slow leaks
max_requests_jitter = 100

# Worker heartbeat files go on tmpfs; the container filesystem is read-only.
worker_tmp_dir = "/dev/shm"

# Log to stdout/stderr so Docker's logging driver collects everything.
accesslog = "-"
errorlog = "-"
loglevel = os.environ.get("LOG_LEVEL", "info")
access_log_format = (
    '%({x-forwarded-for}i)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s '
    '"%(f)s" "%(a)s" %(L)s req_id=%({x-request-id}i)s'
)

# The API port is never published; only the nginx container on the internal
# network can reach it, so its X-Forwarded-* headers are trusted.
forwarded_allow_ips = os.environ.get("FORWARDED_ALLOW_IPS", "*")

fable-5.1/03-infra-management/nginx.conf

# Reverse proxy for the JSON API. Mounted read-only at /etc/nginx/nginx.conf.
# This is the only container that publishes a port.

worker_processes auto;
pid /var/run/nginx.pid;

# The official image links both log files to the container's stdout/stderr.
error_log /var/log/nginx/error.log warn;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                    'rt=$request_time urt=$upstream_response_time req_id=$request_id';
    access_log /var/log/nginx/access.log main;

    sendfile on;
    tcp_nopush on;
    keepalive_timeout 65s;
    server_tokens off;

    # JSON API: bodies are small and clients should not be able to hold
    # connections open slowly. Raise client_max_body_size if uploads are added.
    client_max_body_size 1m;
    client_body_timeout 15s;
    client_header_timeout 15s;
    send_timeout 15s;

    gzip on;
    gzip_types application/json;
    gzip_min_length 1k;

    # Resolve the api service through Docker's embedded DNS at request time (a
    # variable in proxy_pass triggers this). A recreated api container with a
    # new address then keeps working without restarting nginx.
    resolver 127.0.0.11 valid=10s ipv6=off;

    server {
        listen 80 default_server;
        server_name _;

        set $api_upstream http://api:8000;

        # Headers the API needs to see the real client (Flask ProxyFix trusts one hop).
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Request-ID      $request_id;

        # Upstream timeouts aligned with gunicorn's 30s request timeout.
        proxy_connect_timeout 5s;
        proxy_send_timeout    30s;
        proxy_read_timeout    30s;

        add_header X-Content-Type-Options nosniff always;
        add_header X-Request-ID $request_id always;

        # nginx-generated gateway errors answer in JSON like the API does.
        error_page 502 504 @upstream_unavailable;

        location = /healthz {
            access_log off;
            proxy_read_timeout 5s;
            proxy_send_timeout 5s;
            proxy_pass $api_upstream;
        }

        location / {
            proxy_pass $api_upstream;
        }

        location @upstream_unavailable {
            default_type application/json;
            return 503 '{"error":"service unavailable"}';
        }
    }
}

fable-5.1/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

gpt-6.1-sol/03-infra-management/RESPONSE.md

gpt-6.1-sol/03-infra-management/RUNBOOK.md

umask 077
cp .env.example .env
chmod 600 .env
python3 -c 'import secrets; print(secrets.token_hex(32))'
python3 -c 'import secrets; print(secrets.token_hex(32))'

docker compose config --quiet
docker compose up --detach --build --wait --wait-timeout 120

docker compose ps
curl --fail --show-error http://127.0.0.1:8080/health/live
curl --fail --show-error http://127.0.0.1:8080/health/ready
docker compose exec -T proxy nginx -t
docker compose exec -T api id
docker compose logs --tail 100 proxy api db cache

docker inspect --format '{{json .State.Health}}' "$(docker compose ps --quiet api)"

umask 077
mkdir -p backups
backup="backups/app-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose exec -T db sh -ec 'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_dump --host=127.0.0.1 --username="$POSTGRES_USER" --dbname="$POSTGRES_DB" --no-password --format=custom' > "$backup.tmp" && mv "$backup.tmp" "$backup"
docker compose exec -T db pg_restore --list < "$backup"

backup=backups/app-REPLACE_WITH_TIMESTAMP.dump
test -s "$backup" && \
docker compose exec -T db pg_restore --list < "$backup" && \
docker compose stop proxy api cache && \
docker compose exec -T db sh -ec 'export PGPASSWORD="$POSTGRES_PASSWORD"; dropdb --host=127.0.0.1 --username="$POSTGRES_USER" --no-password --if-exists --force "$POSTGRES_DB"; createdb --host=127.0.0.1 --username="$POSTGRES_USER" --no-password --owner="$POSTGRES_USER" --template=template0 "$POSTGRES_DB"' && \
docker compose exec -T db sh -ec 'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_restore --host=127.0.0.1 --username="$POSTGRES_USER" --dbname="$POSTGRES_DB" --no-password --exit-on-error --single-transaction --no-owner --no-privileges' < "$backup"

docker compose up --detach --no-build --wait --wait-timeout 120
curl --fail --show-error http://127.0.0.1:8080/health/ready

docker compose config --quiet
docker compose up --detach --no-build --pull never --wait --wait-timeout 120
curl --fail --show-error http://127.0.0.1:8080/health/ready

gpt-6.1-sol/03-infra-management/TASK.md

gpt-6.1-sol/03-infra-management/.dockerignore

# Allow only the files needed by the API build; secrets/backups never enter it.
**
!Dockerfile
!requirements.txt
!app.py

gpt-6.1-sol/03-infra-management/.env.example

# Copy to .env, chmod 600, and fill both passwords before running Compose.
# Generate each independently with: python3 -c 'import secrets; print(secrets.token_hex(32))'
POSTGRES_USER=app
POSTGRES_PASSWORD=
POSTGRES_DB=app
REDIS_PASSWORD=

# Local HTTP only. See RUNBOOK.md before exposing this beyond the host.
PROXY_BIND=127.0.0.1
HTTP_PORT=8080

# Use a distinct API_IMAGE tag for each release; retain the previous image.
API_IMAGE=small-api:local
# These can also be set to approved repository@sha256:... references.
PYTHON_IMAGE=python:3.13.7-slim-bookworm
NGINX_IMAGE=nginx:1.28.0-alpine
POSTGRES_IMAGE=postgres:17.6-bookworm
REDIS_IMAGE=redis:7.4.5-bookworm

gpt-6.1-sol/03-infra-management/.gitignore

.env
.env.*
!.env.example
backups/
__pycache__/
.venv/

gpt-6.1-sol/03-infra-management/app.py

"""Minimal runnable JSON API; replace/extend routes with the real application."""

import os

import psycopg2
import redis
from flask import Flask, jsonify
from redis.backoff import NoBackoff
from redis.retry import Retry


app = Flask(__name__)
app.config["MAX_CONTENT_LENGTH"] = 1024 * 1024


@app.get("/")
def index():
    return jsonify(service="small-api")


@app.get("/health/live")
def live():
    return jsonify(status="ok")


@app.get("/health/ready")
def ready():
    """Verify authenticated access without writing application data."""
    connection = None
    cache = None
    try:
        connection = psycopg2.connect(
            host=os.environ["POSTGRES_HOST"],
            port=int(os.environ.get("POSTGRES_PORT", "5432")),
            user=os.environ["POSTGRES_USER"],
            password=os.environ["POSTGRES_PASSWORD"],
            dbname=os.environ["POSTGRES_DB"],
            connect_timeout=2,
            options="-c statement_timeout=2000",
        )
        with connection.cursor() as cursor:
            cursor.execute("SELECT 1")
            if cursor.fetchone() != (1,):
                raise RuntimeError("Unexpected database health result")
        cache = redis.Redis(
            host=os.environ["REDIS_HOST"],
            port=int(os.environ.get("REDIS_PORT", "6379")),
            password=os.environ["REDIS_PASSWORD"],
            socket_connect_timeout=1,
            socket_timeout=1,
            retry=Retry(NoBackoff(), 0),
        )
        if not cache.ping():
            raise RuntimeError("Unexpected cache health result")
    except (psycopg2.Error, redis.exceptions.RedisError, KeyError, ValueError, RuntimeError):
        # Do not expose connection strings, credentials, or exception messages.
        return jsonify(status="unavailable"), 503
    finally:
        if connection is not None:
            connection.close()
        if cache is not None:
            cache.close()
    return jsonify(status="ok")

gpt-6.1-sol/03-infra-management/compose.yaml

name: small-api

x-service-defaults: &service-defaults
  restart: unless-stopped
  init: true
  security_opt:
    - no-new-privileges:true
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

services:
  proxy:
    <<: *service-defaults
    image: ${NGINX_IMAGE:-nginx:1.28.0-alpine}
    user: "101:101"
    ports:
      - "${PROXY_BIND:-127.0.0.1}:${HTTP_PORT:-8080}:8080"
    volumes:
      - type: bind
        source: ./nginx.conf
        target: /etc/nginx/nginx.conf
        read_only: true
        bind:
          create_host_path: false
    read_only: true
    tmpfs:
      - /tmp:size=32m,mode=1777
    cap_drop:
      - ALL
    depends_on:
      api:
        condition: service_healthy
    networks:
      - frontend
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health/ready"]
      interval: 15s
      timeout: 8s
      start_period: 10s
      retries: 3
    cpus: "0.50"
    mem_limit: 64m
    pids_limit: 64
    stop_grace_period: 35s

  api:
    <<: *service-defaults
    image: ${API_IMAGE:-small-api:local}
    build:
      context: .
      args:
        PYTHON_IMAGE: ${PYTHON_IMAGE:-python:3.13.7-slim-bookworm}
    environment:
      POSTGRES_HOST: db
      POSTGRES_PORT: "5432"
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:-app}
      REDIS_HOST: cache
      REDIS_PORT: "6379"
      REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}
    expose:
      - "5000"
    read_only: true
    tmpfs:
      - /tmp:size=32m,mode=1777
    cap_drop:
      - ALL
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    networks:
      - frontend
      - backend
    # The readiness healthcheck is defined in the Dockerfile.
    cpus: "1.0"
    mem_limit: 256m
    pids_limit: 128
    stop_grace_period: 35s

  db:
    <<: *service-defaults
    image: ${POSTGRES_IMAGE:-postgres:17.6-bookworm}
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-app}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:-app}
      POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - backend
    healthcheck:
      # TCP plus an authenticated query verifies initialization and credentials.
      test:
        - CMD-SHELL
        - 'PGPASSWORD="$$POSTGRES_PASSWORD" PGCONNECT_TIMEOUT=2 PGOPTIONS="-c statement_timeout=2000" psql --host=127.0.0.1 --username="$$POSTGRES_USER" --dbname="$$POSTGRES_DB" --no-password --no-psqlrc --set=ON_ERROR_STOP=1 --tuples-only --command="SELECT 1" >/dev/null'
      interval: 10s
      timeout: 5s
      start_period: 30s
      retries: 5
    cpus: "1.0"
    mem_limit: 512m
    pids_limit: 256
    shm_size: 128m
    stop_grace_period: 60s

  cache:
    <<: *service-defaults
    image: ${REDIS_IMAGE:-redis:7.4.5-bookworm}
    user: "999:999"
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}
    # Generate a private config instead of putting the password in argv.
    # Hex secrets avoid Redis config quoting ambiguity.
    entrypoint: ["/bin/sh", "-ec"]
    command:
      - |
        case "$$REDIS_PASSWORD" in
          *[!0-9a-fA-F]*) echo 'REDIS_PASSWORD must be hexadecimal' >&2; exit 1 ;;
        esac
        if [ "$${#REDIS_PASSWORD}" -lt 32 ]; then
          echo 'REDIS_PASSWORD must contain at least 32 hexadecimal characters' >&2
          exit 1
        fi
        umask 077
        printf 'requirepass %s\n' "$$REDIS_PASSWORD" > /tmp/redis-auth.conf
        exec redis-server /tmp/redis-auth.conf --bind 0.0.0.0 --protected-mode yes --save '' --appendonly no --maxmemory 128mb --maxmemory-policy allkeys-lru
    read_only: true
    tmpfs:
      - /tmp:size=8m,uid=999,gid=999,mode=0700
      - /data:size=8m,uid=999,gid=999,mode=0700
    cap_drop:
      - ALL
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", 'test "$$(REDISCLI_AUTH="$$REDIS_PASSWORD" redis-cli --host 127.0.0.1 --no-auth-warning ping)" = PONG']
      interval: 10s
      timeout: 3s
      start_period: 5s
      retries: 3
    cpus: "0.50"
    mem_limit: 192m
    pids_limit: 64
    stop_grace_period: 15s

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

volumes:
  postgres_data:

gpt-6.1-sol/03-infra-management/Dockerfile

ARG PYTHON_IMAGE=python:3.13.7-slim-bookworm
FROM ${PYTHON_IMAGE}

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

WORKDIR /app

# Every runtime dependency, including transitive dependencies, is pinned.
# --no-deps prevents the installer from silently adding unlocked packages.
COPY requirements.txt ./requirements.txt
RUN python -m pip install --no-cache-dir --only-binary=:all: --no-deps -r requirements.txt \
    && python -m pip check \
    && groupadd --gid 10001 app \
    && useradd --uid 10001 --gid app --no-create-home --shell /usr/sbin/nologin app

COPY --chown=10001:10001 app.py ./app.py
USER 10001:10001

EXPOSE 5000
HEALTHCHECK --interval=15s --timeout=8s --start-period=20s --retries=3 \
    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:5000/health/ready', timeout=6).close()"]

CMD ["gunicorn", "--bind=0.0.0.0:5000", "--workers=2", "--worker-class=gthread", "--threads=4", "--timeout=30", "--graceful-timeout=30", "--keep-alive=5", "--worker-tmp-dir=/tmp", "--access-logfile=-", "--error-logfile=-", "app:app"]

gpt-6.1-sol/03-infra-management/nginx.conf

# The image runs as uid 101 and listens on an unprivileged port.
worker_processes 1;
pid /tmp/nginx.pid;
error_log /dev/stderr warn;

events {
    worker_connections 512;
}

http {
    default_type application/json;
    server_tokens off;
    access_log /dev/stdout;

    client_body_temp_path /tmp/client_body;
    proxy_temp_path /tmp/proxy;
    client_max_body_size 1m;
    client_header_timeout 10s;
    client_body_timeout 10s;
    send_timeout 30s;
    keepalive_timeout 15s;

    # Docker's DNS: re-resolve after an API container is replaced.
    resolver 127.0.0.11 valid=10s ipv6=off;
    resolver_timeout 3s;

    server {
        listen 8080;
        server_name _;

        location / {
            set $api_upstream api:5000;
            proxy_pass http://$api_upstream;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            proxy_set_header Host $http_host;
            proxy_set_header X-Real-IP $remote_addr;
            # nginx is the directly exposed edge; discard untrusted client headers.
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $http_host;
            proxy_set_header X-Forwarded-Port "";
            proxy_set_header Forwarded "";

            proxy_connect_timeout 3s;
            proxy_send_timeout 30s;
            proxy_read_timeout 30s;
            proxy_request_buffering on;
            proxy_buffering on;
            proxy_next_upstream off;
        }
    }
}

gpt-6.1-sol/03-infra-management/requirements.txt

# Complete runtime dependency set for Python 3.13, installed with --no-deps.
blinker==1.9.0
click==8.2.1
Flask==3.1.2
gunicorn==23.0.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==3.0.2
packaging==25.0
psycopg2-binary==2.9.10
redis==6.4.0
Werkzeug==3.1.3

opus-5.5/03-infra-management/RESPONSE.md

opus-5.5/03-infra-management/RUNBOOK.md

cp .env.example .env && chmod 600 .env
# Replace every change-me value. Use URL-safe secrets:
openssl rand -hex 32            # run once per password

docker compose config -q        # fails if a required secret is missing
docker compose build --pull
docker compose up -d
docker compose ps               # every service should reach "healthy"

docker compose ps                                    # STATUS column shows (healthy)
curl -fsS http://127.0.0.1:8080/nginx-health         # nginx itself
curl -fsS http://127.0.0.1:8080/healthz              # end to end through the proxy to the API
docker compose exec db sh -c 'pg_isready -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"'
docker compose exec cache sh -c 'REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli ping'
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q api)"   # last check output
docker compose logs --tail=100 api proxy

mkdir -p backups
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > "backups/app-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose exec -T db pg_restore --list < backups/<file>.dump > /dev/null && echo OK

docker compose stop proxy api                 # stop writers
docker compose exec -T db sh -c \
  'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner --single-transaction' \
  < backups/<file>.dump
docker compose start api proxy
curl -fsS http://127.0.0.1:8080/healthz

git rev-parse --short HEAD                    # e.g. 1a2b3c4
API_TAG=1a2b3c4 docker compose build api
API_TAG=1a2b3c4 docker compose up -d --no-deps api   # then persist API_TAG in .env
curl -fsS http://127.0.0.1:8080/healthz

opus-5.5/03-infra-management/TASK.md

opus-5.5/03-infra-management/.dockerignore

# Keep secrets, VCS data and deployment files out of the image build context.
.env
.env.*
!.env.example
.git
.gitignore
backups/
*.dump
*.sql
*.sql.gz
compose.yaml
nginx.conf
*.md
Dockerfile
.dockerignore
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/

opus-5.5/03-infra-management/.env.example

# Copy to .env (never commit .env) and replace every "change-me" value:
#   cp .env.example .env && chmod 600 .env
# Generate URL-safe secrets with:  openssl rand -hex 32
# Passwords are embedded in DATABASE_URL/REDIS_URL, so keep them URL-safe
# (hex or [A-Za-z0-9] only).

COMPOSE_PROJECT_NAME=api

# --- Postgres (required) ---
POSTGRES_USER=app
POSTGRES_PASSWORD=change-me
POSTGRES_DB=app

# --- Redis (required) ---
REDIS_PASSWORD=change-me

# --- API ---
# WSGI entry point served by gunicorn, "module:callable".
APP_MODULE=app:app
GUNICORN_WORKERS=2
GUNICORN_THREADS=4
# Image name/tag built and run by compose; set API_TAG to a release (e.g. git SHA) for rollbacks.
API_IMAGE=api
API_TAG=local

# --- Proxy ---
# 127.0.0.1 keeps the stack local-only; use 0.0.0.0 to serve other hosts.
PROXY_BIND_ADDRESS=127.0.0.1
PROXY_PORT=8080

opus-5.5/03-infra-management/.gitignore

.env
backups/

opus-5.5/03-infra-management/compose.yaml

# Single-host deployment: nginx -> gunicorn/Flask API -> Postgres + Redis.
#
# Compose restarts crashed containers and orders startup by health, but it does
# NOT restart containers that turn "unhealthy", reschedule across hosts, or do
# rolling updates. See RUNBOOK.md for the operational procedures.
#
# All credentials come from .env (copy .env.example); `${VAR:?}` makes Compose
# refuse to start if a required secret is missing instead of using a default.

name: ${COMPOSE_PROJECT_NAME:-api}

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "5"

services:
  proxy:
    image: nginx:1.28-alpine
    restart: unless-stopped
    # The only published port. Bound to localhost by default; set
    # PROXY_BIND_ADDRESS=0.0.0.0 (or a specific interface) to expose it.
    ports:
      - "${PROXY_BIND_ADDRESS:-127.0.0.1}:${PROXY_PORT:-8080}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - edge
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/nginx-health || exit 1"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 5s
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 128M
    logging: *default-logging

  api:
    build:
      context: .
    image: ${API_IMAGE:-api}:${API_TAG:-local}
    restart: unless-stopped
    environment:
      APP_MODULE: ${APP_MODULE:-app:app}
      FLASK_DEBUG: "0"
      GUNICORN_WORKERS: ${GUNICORN_WORKERS:-2}
      GUNICORN_THREADS: ${GUNICORN_THREADS:-4}
      # Hostnames are compose service names on the internal "backend" network.
      # Passwords must be URL-safe (see RUNBOOK.md, "Secret handling").
      DATABASE_URL: postgresql://${POSTGRES_USER:?set POSTGRES_USER in .env}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@db:5432/${POSTGRES_DB:?set POSTGRES_DB in .env}
      REDIS_URL: redis://:${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}@cache:6379/0
    # No published ports: only reachable through the proxy.
    expose:
      - "8000"
    networks:
      - edge
      - backend
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      # Liveness of the app process. Requires the app to serve GET /healthz -> 200.
      test:
        - CMD
        - python
        - -c
        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3)"
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 20s
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
          pids: 256
    logging: *default-logging

  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB in .env}
    volumes:
      # postgres:17 keeps data in /var/lib/postgresql/data. postgres:18+ uses
      # /var/lib/postgresql instead -- see RUNBOOK.md before a major upgrade.
      - pgdata:/var/lib/postgresql/data
    networks:
      - backend
    healthcheck:
      # -h 127.0.0.1 so the check fails during first-run init, when the
      # entrypoint's temporary server only listens on the Unix socket.
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    shm_size: 128m
    security_opt:
      - no-new-privileges:true
    stop_grace_period: 60s
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G
    logging: *default-logging

  cache:
    image: redis:7.4-alpine
    restart: unless-stopped
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
    # Run through the image entrypoint so Redis still drops to the "redis" user.
    # Pure cache: no persistence, bounded memory with LRU eviction.
    command:
      - sh
      - -c
      - >-
        exec docker-entrypoint.sh redis-server
        --requirepass "$$REDIS_PASSWORD"
        --maxmemory 200mb
        --maxmemory-policy allkeys-lru
        --save ""
        --appendonly no
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", "REDISCLI_AUTH=\"$${REDIS_PASSWORD}\" redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    security_opt:
      - no-new-privileges:true
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 256M
    logging: *default-logging

networks:
  # Proxy <-> API only.
  edge:
  # API <-> Postgres/Redis. internal: no route to the outside world and no
  # way to publish ports from it.
  backend:
    internal: true

volumes:
  pgdata:

opus-5.5/03-infra-management/Dockerfile

# syntax=docker/dockerfile:1
#
# Production image for the Python (Flask) API.
# - slim, pinned base (bump deliberately; pin by digest in CI for full reproducibility)
# - dependencies installed only from the pinned requirements.txt, in their own layer
# - runs as an unprivileged user under gunicorn (not the Flask dev server)

ARG PYTHON_VERSION=3.13
FROM python:${PYTHON_VERSION}-slim

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

# Fixed UID/GID so volume ownership and security policies are predictable.
RUN groupadd --system --gid 10001 app \
 && useradd --system --uid 10001 --gid app --no-create-home --home-dir /nonexistent --shell /usr/sbin/nologin app

WORKDIR /app

# Install dependencies before copying source so code changes do not bust this layer.
# requirements.txt pins exact versions; psycopg2-binary ships wheels, so no compiler is needed.
COPY requirements.txt .
RUN pip install --no-cache-dir --no-compile -r requirements.txt

# Application code is owned by root and only readable by the app user.
# .dockerignore keeps .env, VCS data and backups out of the build context.
COPY . .

USER app:app

EXPOSE 8000

# Gunicorn settings (bind, workers, timeouts, logging, app module) live in gunicorn.conf.py
# and can be tuned through environment variables without rebuilding.
CMD ["gunicorn", "--config", "/app/gunicorn.conf.py"]

opus-5.5/03-infra-management/gunicorn.conf.py

"""Gunicorn configuration for the API container.

Every value can be overridden with an environment variable so compose/.env can
tune the service without rebuilding the image.
"""
import os

# WSGI entry point, e.g. "app:app" or "myservice.wsgi:application".
wsgi_app = os.environ.get("APP_MODULE", "app:app")

bind = os.environ.get("GUNICORN_BIND", "0.0.0.0:8000")
workers = int(os.environ.get("GUNICORN_WORKERS", "2"))
threads = int(os.environ.get("GUNICORN_THREADS", "4"))
worker_class = "gthread"

# Worker timeout sits just below nginx's proxy_read_timeout (35s) so a stuck
# request is killed by gunicorn and logged here, not silently cut by the proxy.
timeout = int(os.environ.get("GUNICORN_TIMEOUT", "30"))
graceful_timeout = int(os.environ.get("GUNICORN_GRACEFUL_TIMEOUT", "20"))
keepalive = int(os.environ.get("GUNICORN_KEEPALIVE", "65"))  # > nginx upstream keepalive_timeout

# Recycle workers periodically to contain slow memory leaks.
max_requests = int(os.environ.get("GUNICORN_MAX_REQUESTS", "1000"))
max_requests_jitter = int(os.environ.get("GUNICORN_MAX_REQUESTS_JITTER", "100"))

# The container root filesystem is read-only; heartbeat files go to tmpfs.
worker_tmp_dir = "/dev/shm"

# Only the nginx container talks to gunicorn; trust X-Forwarded-Proto from the
# private compose network. Override with a narrower CIDR if you pin subnets.
forwarded_allow_ips = os.environ.get("FORWARDED_ALLOW_IPS", "*")

# Log to stdout/stderr so Docker's logging driver captures everything.
accesslog = "-"
errorlog = "-"
loglevel = os.environ.get("GUNICORN_LOG_LEVEL", "info")

opus-5.5/03-infra-management/nginx.conf

# Reverse proxy for the JSON API. nginx is the edge: it terminates client
# connections and forwards to gunicorn on the private "edge" network.
# TLS is expected to be terminated here or by an upstream load balancer;
# add a 443 server block (and HSTS) when certificates are available.

user nginx;
worker_processes auto;
pid /var/run/nginx.pid;
error_log /dev/stderr warn;

events {
  worker_connections 1024;
}

http {
  include /etc/nginx/mime.types;
  default_type application/json;

  server_tokens off;
  sendfile on;
  tcp_nopush on;

  # Structured access log with request id and upstream timing.
  log_format json_combined escape=json
    '{"time":"$time_iso8601","request_id":"$request_id",'
    '"remote_addr":"$remote_addr","method":"$request_method",'
    '"uri":"$request_uri","status":$status,"bytes_sent":$body_bytes_sent,'
    '"request_time":$request_time,"upstream_status":"$upstream_status",'
    '"upstream_response_time":"$upstream_response_time",'
    '"user_agent":"$http_user_agent"}';
  access_log /dev/stdout json_combined;

  # Client-side limits and timeouts sized for small JSON requests.
  client_max_body_size 1m;
  client_body_buffer_size 64k;
  client_header_timeout 10s;
  client_body_timeout 10s;
  send_timeout 30s;
  keepalive_timeout 30s;

  gzip on;
  gzip_types application/json application/problem+json;
  gzip_min_length 1024;
  gzip_proxied any;
  gzip_vary on;

  # Docker's embedded DNS. Re-resolving "api" means a recreated API container
  # (new IP) is picked up without restarting nginx.
  resolver 127.0.0.11 valid=10s ipv6=off;
  resolver_timeout 5s;

  upstream api_backend {
    zone api_backend 64k;
    server api:8000 resolve;
    keepalive 16;
    keepalive_timeout 60s;
  }

  server {
    listen 80 default_server;
    server_name _;

    # nginx's own liveness endpoint (used by the compose healthcheck).
    location = /nginx-health {
      access_log off;
      return 200 '{"status":"ok"}\n';
    }

    location / {
      proxy_pass http://api_backend;

      # HTTP/1.1 + empty Connection header enables upstream keepalive.
      proxy_http_version 1.1;
      proxy_set_header Connection "";

      proxy_set_header Host $host;
      proxy_set_header X-Request-ID $request_id;
      # nginx is the edge: overwrite (not append) client-supplied values so
      # X-Forwarded-For cannot be spoofed. If another proxy/LB sits in front,
      # configure ngx_http_realip_module and switch to $proxy_add_x_forwarded_for.
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $remote_addr;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host $host;
      proxy_set_header X-Forwarded-Port $server_port;

      # Upstream timeouts. Read timeout is slightly above gunicorn's 30s
      # worker timeout so the app, not the proxy, decides when a request dies.
      proxy_connect_timeout 5s;
      proxy_send_timeout 35s;
      proxy_read_timeout 35s;

      # Do not replay requests (e.g. POSTs) against the single upstream.
      proxy_next_upstream off;

      proxy_buffering on;
      proxy_buffer_size 16k;
      proxy_buffers 8 16k;

      proxy_hide_header X-Powered-By;

      add_header X-Request-ID $request_id always;
      add_header X-Content-Type-Options nosniff always;
      add_header X-Frame-Options DENY always;
      add_header Referrer-Policy no-referrer always;
      add_header Content-Security-Policy "default-src 'none'; frame-ancestors 'none'" always;
    }

    # Return JSON (not nginx HTML) when the API is down or times out.
    # Application-generated 5xx responses pass through unchanged.
    error_page 502 503 504 @upstream_unavailable;
    location @upstream_unavailable {
      default_type application/json;
      add_header X-Request-ID $request_id always;
      return 503 '{"error":"service_unavailable","request_id":"$request_id"}\n';
    }
  }
}

opus-5.5/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

grok-4.7/03-infra-management/RESPONSE.md

grok-4.7/03-infra-management/RUNBOOK.md

cp .env.example .env
chmod 600 .env

docker compose up -d --build
docker compose ps

docker compose pull proxy db cache
docker compose build --pull api
docker compose up -d

docker compose ps
curl -fsS "http://127.0.0.1:8080/nginx-health"
curl -fsS "http://127.0.0.1:8080/healthz"

docker compose ps
docker compose logs --tail=100 db cache api proxy

mkdir -p backups
chmod 700 backups
stamp=$(date +%Y%m%d%H%M%S)
docker compose exec -T db \
  sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_dump -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc --no-owner' \
  > "backups/app-${stamp}.dump"
chmod 600 "backups/app-${stamp}.dump"

docker compose stop proxy api
docker compose exec -T db \
  sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" exec pg_restore -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner --single-transaction' \
  < "backups/app-STAMP.dump"
docker compose up -d

stamp=$(date +%Y%m%d%H%M%S)
docker compose stop db
docker run --rm --entrypoint tar \
  -v app_pgdata:/var/lib/postgresql/data:ro \
  -v "$PWD/backups:/backups" \
  postgres:16-alpine \
  czf "/backups/pgdata-${stamp}.tgz" -C /var/lib/postgresql/data .
docker compose up -d db

docker compose stop db
docker run --rm --entrypoint sh \
  -v app_pgdata:/var/lib/postgresql/data \
  -v "$PWD/backups:/backups:ro" \
  postgres:16-alpine \
  -c 'find /var/lib/postgresql/data -mindepth 1 -delete && tar xzf /backups/pgdata-STAMP.tgz -C /var/lib/postgresql/data'
docker compose up -d

docker compose exec -it db \
  sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

docker compose up -d --force-recreate db api

docker compose up -d --force-recreate cache api

docker tag app-api:local "app-api:$(date +%Y%m%d%H%M%S)"

docker compose up -d --build

APP_IMAGE_TAG=STAMP docker compose up -d --no-build api
docker compose up -d proxy

grok-4.7/03-infra-management/TASK.md

grok-4.7/03-infra-management/.dockerignore

.env
.env.*
.dockerignore
.gitignore
.git
.gitignore
**/.venv
**/__pycache__
**/*.pyc
**/*.pyo
Dockerfile
compose.yaml
compose.yml
nginx.conf
redis-entrypoint.sh
postgres-healthcheck.sh
*.md
**/*.md
*.dump
*.sql
backups

grok-4.7/03-infra-management/.env.example

# Copy to .env and replace every change-me value. Never commit .env.
# Generate URL-safe passwords: openssl rand -hex 24

# Loopback port for the nginx proxy.
HTTP_PORT=8080

# Required. POSTGRES_PASSWORD is stored in the data volume only on first init.
POSTGRES_USER=app
POSTGRES_PASSWORD=change-me
POSTGRES_DB=app

# Required. Redis is a cache; this password is read every time the cache starts.
REDIS_PASSWORD=change-me

# Optional. Tag the API image so a rollback can select an older build.
APP_IMAGE_TAG=local
WEB_CONCURRENCY=2
GUNICORN_TIMEOUT=30
GUNICORN_GRACEFUL_TIMEOUT=20
GUNICORN_APP=app:app
# Containers that can reach unpublished port 5000 are trusted for X-Forwarded-*.
FORWARDED_ALLOW_IPS="*"

grok-4.7/03-infra-management/.gitignore

.env
*.dump
*.sql
backups/

grok-4.7/03-infra-management/compose.yaml

# Single-host Compose stack. Limits and restarts are local Docker settings.
# This file is not a multi-node scheduler, secret store, or rolling-upgrade system.

name: app

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  proxy:
    image: nginx:1.27-alpine
    pull_policy: missing
    restart: unless-stopped
    logging: *default-logging
    depends_on:
      api:
        condition: service_healthy
    ports:
      - "127.0.0.1:${HTTP_PORT:-8080}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - edge
    stop_grace_period: 10s
    healthcheck:
      test: ["CMD", "wget", "-q", "-T", "3", "-O", "/dev/null", "http://127.0.0.1/healthz"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 10s
    deploy:
      resources:
        limits:
          cpus: "0.25"
          memory: 128M

  api:
    build:
      context: .
      dockerfile: Dockerfile
    image: app-api:${APP_IMAGE_TAG:-local}
    pull_policy: missing
    restart: unless-stopped
    logging: *default-logging
    init: true
    environment:
      DATABASE_URL: "postgres://${POSTGRES_USER:?required}:${POSTGRES_PASSWORD:?required}@db:5432/${POSTGRES_DB:?required}"
      REDIS_URL: "redis://:${REDIS_PASSWORD:?required}@cache:6379/0"
      WEB_CONCURRENCY: "${WEB_CONCURRENCY:-2}"
      GUNICORN_TIMEOUT: "${GUNICORN_TIMEOUT:-30}"
      GUNICORN_GRACEFUL_TIMEOUT: "${GUNICORN_GRACEFUL_TIMEOUT:-20}"
      GUNICORN_APP: "${GUNICORN_APP:-app:app}"
      FORWARDED_ALLOW_IPS: "${FORWARDED_ALLOW_IPS:-*}"
    expose:
      - "5000"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    networks:
      - edge
      - data
    stop_grace_period: 25s
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    healthcheck:
      test:
        - CMD
        - python
        - -c
        - "import urllib.request; raise SystemExit(0 if urllib.request.urlopen('http://127.0.0.1:5000/healthz', timeout=3).getcode() == 200 else 1)"
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 20s
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

  db:
    image: postgres:16-alpine
    pull_policy: missing
    restart: unless-stopped
    logging: *default-logging
    environment:
      POSTGRES_USER: "${POSTGRES_USER:?required}"
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?required}"
      POSTGRES_DB: "${POSTGRES_DB:?required}"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./postgres-healthcheck.sh:/usr/local/bin/postgres-healthcheck.sh:ro
    expose:
      - "5432"
    networks:
      - data
    shm_size: 128mb
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "/bin/sh", "/usr/local/bin/postgres-healthcheck.sh"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 40s
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G

  cache:
    image: redis:7-alpine
    pull_policy: missing
    restart: unless-stopped
    logging: *default-logging
    environment:
      REDIS_PASSWORD: "${REDIS_PASSWORD:?required}"
      REDISCLI_AUTH: "${REDIS_PASSWORD:?required}"
    entrypoint: ["/bin/sh", "/usr/local/bin/redis-entrypoint.sh"]
    command: ["run"]
    volumes:
      - ./redis-entrypoint.sh:/usr/local/bin/redis-entrypoint.sh:ro
    expose:
      - "6379"
    networks:
      - data
    stop_grace_period: 10s
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 256M

networks:
  edge:
    driver: bridge
  data:
    driver: bridge
    internal: true

volumes:
  pgdata:
    name: app_pgdata

grok-4.7/03-infra-management/docker-entrypoint.sh

#!/bin/sh
# Run gunicorn as the container user. Runtime secrets stay in the environment.
set -eu

bind="${GUNICORN_BIND:-0.0.0.0:5000}"
workers="${WEB_CONCURRENCY:-2}"
timeout="${GUNICORN_TIMEOUT:-30}"
graceful="${GUNICORN_GRACEFUL_TIMEOUT:-20}"
app="${GUNICORN_APP:-app:app}"
forwarded="${FORWARDED_ALLOW_IPS:-*}"

exec gunicorn \
    --bind "$bind" \
    --workers "$workers" \
    --timeout "$timeout" \
    --graceful-timeout "$graceful" \
    --access-logfile - \
    --error-logfile - \
    --forwarded-allow-ips "$forwarded" \
    "$app"

grok-4.7/03-infra-management/Dockerfile

FROM python:3.13-slim

# Bytecode is disabled so the unprivileged process does not need a writable /app.
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=1 \
    HOME=/home/app \
    WEB_CONCURRENCY=2 \
    GUNICORN_BIND=0.0.0.0:5000 \
    GUNICORN_TIMEOUT=30 \
    GUNICORN_GRACEFUL_TIMEOUT=20 \
    GUNICORN_APP=app:app \
    FORWARDED_ALLOW_IPS=*

WORKDIR /app

RUN groupadd --gid 10001 app \
    && useradd --uid 10001 --gid app --home-dir /home/app --create-home --shell /bin/false app

COPY requirements.txt ./
RUN pip install --no-cache-dir --only-binary=:all: -r requirements.txt

COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod 755 /usr/local/bin/docker-entrypoint.sh

COPY . ./
RUN chown -R root:app /app \
    && find /app -type d -exec chmod 755 {} + \
    && find /app -type f -exec chmod 644 {} +

USER app

EXPOSE 5000

HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=5 \
    CMD ["python", "-c", "import urllib.request; raise SystemExit(0 if urllib.request.urlopen('http://127.0.0.1:5000/healthz', timeout=3).getcode() == 200 else 1)"]

ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

grok-4.7/03-infra-management/nginx.conf

worker_processes 1;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/json;

    server_tokens off;
    sendfile on;
    tcp_nopush on;
    keepalive_timeout 15s;
    keepalive_requests 100;
    reset_timedout_connection on;

    client_max_body_size 1m;
    client_body_timeout 10s;
    client_header_timeout 10s;
    send_timeout 30s;

    gzip on;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_proxied any;
    gzip_types application/json application/problem+json text/plain;
    gzip_vary on;

    map $uri $loggable {
        default 1;
        /healthz 0;
        /nginx-health 0;
    }

    log_format api escape=json '{"ts":"$time_iso8601","remote":"$remote_addr","method":"$request_method","uri":"$request_uri","status":$status,"bytes":$body_bytes_sent,"req_s":$request_time,"upstream_s":"$upstream_response_time","req_id":"$request_id"}';
    access_log /var/log/nginx/access.log api if=$loggable;

    # Docker's embedded DNS. A variable proxy_pass re-resolves the API after recreate.
    resolver 127.0.0.11 valid=10s ipv6=off;
    resolver_timeout 5s;

    server {
        listen 80;
        server_name _;

        add_header X-Content-Type-Options nosniff always;
        add_header X-Frame-Options DENY always;
        add_header Referrer-Policy no-referrer always;

        # =CODE is the client status. Named locations return 200 so error_page does not recurse.
        error_page 413 =413 @body_too_large;
        error_page 502 =502 @upstream_down;
        error_page 504 =504 @upstream_timeout;

        location = /nginx-health {
            access_log off;
            default_type text/plain;
            return 200 "ok\n";
        }

        location / {
            set $api_host api;
            proxy_pass http://$api_host:5000;
            proxy_http_version 1.1;
            proxy_redirect off;
            proxy_next_upstream off;

            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Request-ID $request_id;
            proxy_hide_header X-Powered-By;

            proxy_connect_timeout 5s;
            proxy_send_timeout 30s;
            proxy_read_timeout 30s;

            proxy_buffering on;
            proxy_request_buffering on;
            proxy_buffer_size 8k;
            proxy_buffers 8 16k;
            proxy_busy_buffers_size 32k;
        }

        location @body_too_large {
            default_type application/json;
            return 200 '{"error":"request body exceeds 1m limit"}';
        }

        location @upstream_down {
            default_type application/json;
            return 200 '{"error":"api unavailable"}';
        }

        location @upstream_timeout {
            default_type application/json;
            return 200 '{"error":"api timeout"}';
        }
    }
}

grok-4.7/03-infra-management/postgres-healthcheck.sh

#!/bin/sh
# Prove the database accepts queries with the runtime role and password.
set -eu
export PGPASSWORD="$POSTGRES_PASSWORD"
export PGCONNECT_TIMEOUT=3
# TCP only. The image's first-boot helper does not listen on TCP, so this
# stays failed until the real server is accepting clients.
exec psql -h 127.0.0.1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT 1" >/dev/null

grok-4.7/03-infra-management/redis-entrypoint.sh

#!/bin/sh
# Start Redis as the image's redis user. The password is read from the environment.
set -eu

if [ -z "${REDIS_PASSWORD:-}" ]; then
    echo "REDIS_PASSWORD is required" >&2
    exit 1
fi

umask 077
{
    printf '%s\n' \
        'bind 0.0.0.0' \
        'port 6379' \
        'protected-mode yes' \
        'daemonize no' \
        'maxmemory 192mb' \
        'maxmemory-policy allkeys-lru' \
        'save ""' \
        'appendonly no' \
        'dir /data'
    printf 'requirepass %s\n' "$REDIS_PASSWORD"
} > /tmp/redis.conf
mkdir -p /data
chown redis:redis /tmp/redis.conf /data

if command -v su-exec >/dev/null 2>&1; then
    exec su-exec redis redis-server /tmp/redis.conf
fi
if command -v gosu >/dev/null 2>&1; then
    exec gosu redis redis-server /tmp/redis.conf
fi

echo "refusing to run redis as root: su-exec/gosu not found" >&2
exit 1

grok-4.7/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

mimo/03-infra-management/RESPONSE.md

mimo/03-infra-management/RUNBOOK.md

cp .env.example .env          # never commit .env; fill in real values
chmod 600 .env
$EDITOR .env                  # set POSTGRES_PASSWORD and REDIS_PASSWORD

docker compose config --quiet # renders and validates; fails if a var is unset
docker compose build          # or: docker pull the release tag
docker compose up -d
docker compose ps             # wait for db/cache healthy → api healthy → proxy

docker compose stop                 # keeps containers and data
docker compose down                 # removes containers, KEEPS the pgdata volume
docker compose down -v              # also DELETES the database volume — back up first

docker compose ps --format 'table {{.Service}}\t{{.Status}}'   # all "(healthy)"
docker inspect --format '{{json .State.Health}}' $(docker compose ps -q api) | jq

curl -fsS http://127.0.0.1:8080/nginx-health   # proxy itself: {"status":"ok"}
curl -fsS http://127.0.0.1:8080/healthz        # through the proxy to the API
curl -si  http://127.0.0.1:8080/ | head -20    # check headers + status

docker compose exec db    pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"
docker compose exec cache redis-cli --no-auth-warning -a "$REDIS_PASSWORD" ping

docker compose port db 5432 || echo "db not published (expected)"
nc -z 127.0.0.1 5432 || echo "5432 closed on the host (expected)"
nc -z 127.0.0.1 6379 || echo "6379 closed on the host (expected)"

docker compose logs -f --tail=100 api
docker compose logs --since=15m proxy | jq -c 'select(.status >= 500)'

docker compose exec -T db sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > "backups/app-$(date +%Y%m%dT%H%M%S).dump"

pg_restore --list backups/app-<stamp>.dump | head

docker compose stop api proxy
docker compose exec -T db sh -c \
  'dropdb -U "$POSTGRES_USER" --if-exists "$POSTGRES_DB" \
   && createdb -U "$POSTGRES_USER" "$POSTGRES_DB"'
docker compose exec -T db sh -c \
  'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner' \
  < backups/app-<stamp>.dump
docker compose start api proxy
docker compose ps        # wait for healthy

docker compose stop
docker run --rm -v smallapi_pgdata:/data:ro -v "$PWD/backups:/backups" \
  alpine tar czf /backups/pgdata-$(date +%Y%m%d).tgz -C /data .
docker compose up -d

docker image ls smallapi/api                 # find the last good tag
APP_VERSION=<last-good> docker compose up -d api
docker compose ps && curl -fsS http://127.0.0.1:8080/healthz

docker compose restart proxy     # nginx resolves `api` only at startup

docker compose pull && docker compose up -d      # base image updates
docker compose exec db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"
docker compose exec cache redis-cli --no-auth-warning -a "$REDIS_PASSWORD" info memory
docker stats --no-stream                         # check against the deploy limits
docker system df                                 # disk pressure

mimo/03-infra-management/TASK.md

mimo/03-infra-management/.dockerignore

# Keep the build context small, and keep secrets and host state out of the image.
.env
.env.*
!.env.example
secrets/
backups/

.git
.gitignore
.dockerignore

# Stack/runtime files are not application code.
compose.yaml
compose.*.yaml
nginx.conf
*.md

**/__pycache__/
**/*.py[cod]
**/.pytest_cache/
**/.mypy_cache/
**/.ruff_cache/
.venv/
venv/
*.sqlite3
*.log

mimo/03-infra-management/.env.example

# Copy to .env and fill in real values:  cp .env.example .env
# .env is git-ignored and is the ONLY place credentials live for a local or
# single-host run. `docker compose up` fails fast if a required value is unset.
#
# Generate strong values:
#   POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d '\n/+=' | cut -c1-32)
#   REDIS_PASSWORD=$(openssl rand -base64 32 | tr -d '\n/+=' | cut -c1-32)

# --- Postgres (required) ----------------------------------------------------
POSTGRES_USER=app
POSTGRES_PASSWORD=change-me
POSTGRES_DB=app

# --- Redis (required) -------------------------------------------------------
REDIS_PASSWORD=change-me
REDIS_MAXMEMORY=256mb

# --- Edge ------------------------------------------------------------------
# Loopback by default so a laptop never exposes the stack to the LAN.
# Set to 0.0.0.0 (or a specific host IP) on a server that should serve traffic.
HTTP_BIND_ADDR=127.0.0.1
HTTP_PORT=8080

# --- Application ------------------------------------------------------------
# Image tag built and run by compose. Use a release tag (e.g. 2026.09.23-1) in
# production so `docker compose up -d` can roll back by changing one value.
APP_VERSION=dev
APP_ENV=production
LOG_LEVEL=info
GUNICORN_WORKERS=2
GUNICORN_THREADS=4
GUNICORN_TIMEOUT=30

mimo/03-infra-management/.gitignore

# Real secrets never enter git; .env.example is the template that does.
.env
.env.*
!.env.example
secrets/
backups/*
!backups/.gitkeep
__pycache__/
*.py[cod]
.venv/

mimo/03-infra-management/backups/.gitkeep

mimo/03-infra-management/compose.yaml

# Small single-host deployment: nginx -> gunicorn API -> Postgres + Redis.
#
# Compose is not an orchestrator: there is no rolling update, no rescheduling,
# no multi-host failover and no quorum here. What a single Docker host can
# honestly provide is below - restart policy, health-gated startup, bounded
# logs and bounded resources. Operations live in RUNBOOK.md.

name: smallapi

# ---------------------------------------------------------------------------
# shared fragments
# ---------------------------------------------------------------------------
x-logging: &logging
  driver: json-file
  options:
    max-size: "10m"      # the default is unbounded and eventually fills the disk
    max-file: "5"
    compress: "true"

x-hardening: &hardening
  restart: unless-stopped   # survive host reboot / crash, but respect `compose stop`
  security_opt:
    - no-new-privileges:true
  logging: *logging

services:
  # -------------------------------------------------------------------------
  # Edge proxy - the only service with a published port.
  # -------------------------------------------------------------------------
  proxy:
    <<: *hardening
    # Unprivileged variant: runs as uid 101 and listens on 8080, so there is no
    # root master process and no CAP_NET_BIND_SERVICE. Pin to a digest in prod.
    image: nginxinc/nginx-unprivileged:1.27-alpine
    user: "101:101"
    ports:
      # Loopback by default so a laptop never publishes the stack to the LAN;
      # set HTTP_BIND_ADDR=0.0.0.0 (or a host IP) on a real server.
      - "${HTTP_BIND_ADDR:-127.0.0.1}:${HTTP_PORT:-8080}:8080"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    read_only: true
    tmpfs:
      - /tmp:mode=1777,size=64m     # pid file + proxy temp paths
    cap_drop: [ALL]
    networks:
      # Edge only: the proxy has no route to db or cache at all. Docker's
      # embedded DNS resolves `api` to its address on this shared network.
      - edge
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      # Checks nginx itself, not the upstream: a healthy proxy must not be
      # restarted just because the API is sick - it still serves 502/504 JSON.
      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080/nginx-health || exit 1"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 10s
    stop_grace_period: 20s
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 128M
          pids: 200
        reservations:
          memory: 32M

  # -------------------------------------------------------------------------
  # Application - no published port, reachable only through the proxy.
  # -------------------------------------------------------------------------
  api:
    <<: *hardening
    build:
      context: .
      dockerfile: Dockerfile
    # Tagged image: `APP_VERSION=<previous> docker compose up -d api` is the
    # rollback path (RUNBOOK.md).
    image: smallapi/api:${APP_VERSION:-dev}
    expose:
      - "8000"          # documentation only; no host port is published
    environment:
      # Credentials come from the git-ignored .env, never from this file.
      # `:?` aborts `compose up` instead of starting a half-configured service.
      DATABASE_URL: postgresql://${POSTGRES_USER:?set POSTGRES_USER in .env}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@db:5432/${POSTGRES_DB:?set POSTGRES_DB in .env}
      REDIS_URL: redis://:${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}@cache:6379/0
      APP_PORT: "8000"
      APP_ENV: ${APP_ENV:-production}
      LOG_LEVEL: ${LOG_LEVEL:-info}
      GUNICORN_WORKERS: ${GUNICORN_WORKERS:-2}
      GUNICORN_THREADS: ${GUNICORN_THREADS:-4}
      GUNICORN_TIMEOUT: ${GUNICORN_TIMEOUT:-30}
    read_only: true
    tmpfs:
      - /tmp:mode=1777,size=64m     # gunicorn worker heartbeat files
    cap_drop: [ALL]
    init: true                      # reap zombies if the app shells out
    networks:
      - edge        # accepts connections from the proxy
      - backend     # reaches db and cache
    depends_on:
      db:
        condition: service_healthy
        restart: true               # recreate-safe: follow a restarted database
      cache:
        condition: service_healthy
        restart: true
    healthcheck:
      # /healthz must answer from the process itself. Keep dependency probing on
      # a separate /readyz so a slow database cannot loop-restart the API.
      test: ["CMD", "python", "-c", "import sys, urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=4).status == 200 else 1)"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s
    stop_grace_period: 30s          # >= gunicorn graceful_timeout, so requests drain
    deploy:
      resources:
        limits:
          cpus: "1.50"
          memory: 512M
          pids: 200
        reservations:
          memory: 128M

  # -------------------------------------------------------------------------
  # Postgres - internal network only, data on a named volume.
  # -------------------------------------------------------------------------
  db:
    <<: *hardening
    image: postgres:17-alpine       # pin to a digest in production
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB in .env}
      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256 --auth-local=scram-sha-256"
      PGDATA: /var/lib/postgresql/data/pgdata
    # No `ports:` - 5432 is unreachable from outside the compose network.
    # Use `docker compose exec db psql` or an SSH tunnel for admin access.
    volumes:
      - pgdata:/var/lib/postgresql/data   # survives `down`, unlike the old anonymous volume
      - ./backups:/backups                # pg_dump target, see RUNBOOK.md
    cap_drop: [ALL]
    cap_add:
      # The entrypoint starts as root, fixes data-dir ownership, then drops to
      # the `postgres` user. Dropping these four breaks first-run initdb.
      - CHOWN
      - DAC_OVERRIDE
      - SETGID
      - SETUID
    shm_size: 256mb                 # default 64m is too small for real queries
    networks:
      - backend
    healthcheck:
      # $$ escapes compose interpolation: expanded by the container's shell.
      test: ["CMD-SHELL", "pg_isready -q -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    stop_grace_period: 60s          # allow a clean shutdown checkpoint
    deploy:
      resources:
        limits:
          cpus: "1.50"
          memory: 1G
          pids: 200
        reservations:
          memory: 256M

  # -------------------------------------------------------------------------
  # Redis - used as a cache, therefore deliberately not persisted.
  # -------------------------------------------------------------------------
  cache:
    <<: *hardening
    image: redis:8-alpine           # pin to a digest in production
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
      - --save
      - ""                          # cache contents are disposable: no RDB
      - --appendonly
      - "no"
      - --maxmemory
      - ${REDIS_MAXMEMORY:-256mb}
      - --maxmemory-policy
      - allkeys-lru                 # evict instead of returning OOM errors
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}   # healthcheck only
    # No `ports:` - a reachable unauthenticated Redis is remote code execution.
    cap_drop: [ALL]
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - SETGID
      - SETUID
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", "redis-cli --no-auth-warning -a \"$${REDIS_PASSWORD}\" ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
    stop_grace_period: 10s
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 320M              # maxmemory + process overhead
          pids: 100
        reservations:
          memory: 64M

networks:
  # Published segment: proxy <-> api.
  edge:
    driver: bridge
  # Data segment. `internal: true` removes the default gateway, so db and cache
  # cannot reach (or be reached from) anything off this host.
  backend:
    driver: bridge
    internal: true

volumes:
  pgdata:

mimo/03-infra-management/Dockerfile

# syntax=docker/dockerfile:1

# Pinned minor version keeps rebuilds reproducible; replace with a digest
# (python:3.13-slim@sha256:...) once base images are mirrored internally.
FROM python:3.13-slim AS base

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_ROOT_USER_ACTION=ignore

# ---------------------------------------------------------------------------
# builder: install dependencies once into a self-contained virtualenv, so the
# runtime image carries no pip cache and no build toolchain.
# ---------------------------------------------------------------------------
FROM base AS builder

RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

WORKDIR /app
# Only requirements.txt busts this layer, not application edits.
COPY requirements.txt ./
# Pinned requirements instead of the original `pip install flask psycopg2
# redis`, which floated to whatever was newest on every build and needed a C
# toolchain for psycopg2. `pip check` fails the build on an inconsistent graph.
RUN pip install --no-cache-dir -r requirements.txt \
 && pip check

# ---------------------------------------------------------------------------
# runtime
# ---------------------------------------------------------------------------
FROM base AS runtime

# Fixed high UID/GID: predictable ownership for volumes and host audit rules.
RUN groupadd --gid 10001 app \
 && useradd --uid 10001 --gid 10001 --no-create-home --shell /usr/sbin/nologin app

COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

WORKDIR /app
# Code stays owned by root and is only readable by the service account, so a
# compromised process cannot rewrite its own source.
COPY --chown=root:root . /app

ENV APP_PORT=8000 \
    GUNICORN_WORKERS=2 \
    GUNICORN_THREADS=4 \
    GUNICORN_TIMEOUT=30

USER 10001:10001
EXPOSE 8000

# Shipped with the image so plain `docker run` gets it too; compose tunes the
# interval and start period per environment.
HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
  CMD ["python", "-c", "import os, sys, urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:' + os.environ.get('APP_PORT', '8000') + '/healthz', timeout=4).status == 200 else 1)"]

# Production WSGI server instead of the Flask development server, in exec form
# so gunicorn is PID 1 and SIGTERM drains in-flight requests instead of killing
# a shell. FLASK_ENV=development (debugger + reloader) is gone: it is remote
# code execution if the debug console is ever reachable.
# `wsgi:app` is the entrypoint the original `flask run` discovered implicitly;
# adjust if the application module is named differently.
CMD ["gunicorn", "--config", "/app/gunicorn.conf.py", "wsgi:app"]

mimo/03-infra-management/gunicorn.conf.py

"""Gunicorn settings for the API container.

Every knob is env-overridable so one image runs unchanged in local and
production environments; the defaults suit a small JSON API on one host.
"""

import os


def _int(name: str, default: int) -> int:
    try:
        return int(os.environ[name])
    except (KeyError, ValueError):
        return default


bind = f"0.0.0.0:{os.environ.get('APP_PORT', '8000')}"

# gthread: this API is I/O-bound on Postgres and Redis, and threads keep the
# resident set inside the container memory limit set in compose.yaml.
worker_class = "gthread"
workers = _int("GUNICORN_WORKERS", 2)
threads = _int("GUNICORN_THREADS", 4)

# Keep at or below nginx's proxy_read_timeout (30s) so a stuck request surfaces
# as a clean 504 at the proxy instead of a silently killed worker.
timeout = _int("GUNICORN_TIMEOUT", 30)
graceful_timeout = 30

# Longer than nginx's upstream keepalive_timeout (60s) so gunicorn never closes
# a pooled connection that nginx still considers usable.
keepalive = 75

# Cheap guard against slow leaks; jitter avoids recycling all workers at once.
max_requests = 1000
max_requests_jitter = 100

# The API port is not published and only the proxy shares a network with this
# container, so the single X-Forwarded-* hop is trusted. nginx overwrites those
# headers on every request, so clients cannot forge them.
forwarded_allow_ips = os.environ.get("FORWARDED_ALLOW_IPS", "*")

# Logs to stdout/stderr, collected by the container runtime (bounded json-file
# driver in compose.yaml). JSON access lines carry the proxy's request id.
accesslog = "-"
errorlog = "-"
loglevel = os.environ.get("LOG_LEVEL", "info")
access_log_format = (
    '{"remote":"%({x-forwarded-for}i)s","method":"%(m)s","path":"%(U)s",'
    '"query":"%(q)s","status":"%(s)s","bytes":"%(B)s","duration_ms":"%(M)s",'
    '"request_id":"%({x-request-id}i)s","user_agent":"%(a)s"}'
)

# The container root filesystem is read-only; compose mounts a tmpfs here.
worker_tmp_dir = "/tmp"

mimo/03-infra-management/nginx.conf

# Full main configuration: this file replaces /etc/nginx/nginx.conf, so it must
# declare the main-context directives the stock file provides.
#
# Runs on nginxinc/nginx-unprivileged (uid 101, listens on 8080): no master
# process as root, no CAP_NET_BIND_SERVICE needed, and the container can run
# with a read-only root filesystem.

worker_processes  auto;
pid               /tmp/nginx.pid;
error_log         /dev/stderr  warn;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/json;   # JSON API: sane default for generated bodies

    # Writable locations for an unprivileged user on a read-only rootfs.
    client_body_temp_path  /tmp/nginx-client;
    proxy_temp_path        /tmp/nginx-proxy;
    fastcgi_temp_path      /tmp/nginx-fastcgi;
    uwsgi_temp_path        /tmp/nginx-uwsgi;
    scgi_temp_path         /tmp/nginx-scgi;

    # ---- logging ----------------------------------------------------------
    # Structured access logs to stdout so `docker compose logs` and any log
    # shipper get parseable records; request_id ties proxy and API logs together.
    log_format json_access escape=json
        '{'
        '"time":"$time_iso8601",'
        '"request_id":"$request_id",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"path":"$uri",'
        '"query":"$args",'
        '"status":$status,'
        '"bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_addr":"$upstream_addr",'
        '"upstream_status":"$upstream_status",'
        '"upstream_time":"$upstream_response_time",'
        '"user_agent":"$http_user_agent"'
        '}';
    access_log  /dev/stdout  json_access;

    # ---- general ----------------------------------------------------------
    server_tokens        off;          # do not advertise the nginx version
    sendfile             on;
    tcp_nopush           on;
    tcp_nodelay          on;
    keepalive_timeout    65s;
    keepalive_requests   1000;
    reset_timedout_connection on;

    # A JSON API does not accept uploads; cap the body and the time a client
    # may take to send it (slowloris).
    client_max_body_size    1m;
    client_body_timeout     10s;
    client_header_timeout   10s;
    send_timeout            30s;
    client_body_buffer_size 16k;

    gzip              on;
    gzip_vary         on;
    gzip_proxied      any;
    gzip_min_length   1024;
    gzip_comp_level   5;
    gzip_types        application/json application/problem+json text/plain;

    # ---- abuse limits -----------------------------------------------------
    # Per-client budget, generous enough for normal API use. Tune from real
    # traffic; these are defaults, not a substitute for an edge WAF.
    limit_req_zone   $binary_remote_addr  zone=api_rate:10m  rate=20r/s;
    limit_conn_zone  $binary_remote_addr  zone=api_conn:10m;
    limit_req_status  429;
    limit_conn_status 429;

    # ---- upstream ---------------------------------------------------------
    upstream api_backend {
        # Resolved once at startup. After `docker compose up -d --force-recreate
        # api` the container IP can change, so restart the proxy too (RUNBOOK).
        server api:8000  max_fails=3  fail_timeout=10s;

        # Connection pool to gunicorn; requires HTTP/1.1 + empty Connection
        # header below. gunicorn's keepalive (75s) is deliberately longer.
        keepalive             32;
        keepalive_timeout     60s;
        keepalive_requests    1000;
    }

    server {
        listen       8080;
        server_name  _;

        # Baseline response headers for an API (no cookies, no framing).
        add_header X-Content-Type-Options  "nosniff"        always;
        add_header X-Frame-Options         "DENY"           always;
        add_header Referrer-Policy         "no-referrer"    always;
        add_header X-Request-Id            $request_id      always;

        # Proxy behaviour shared by every proxied location.
        proxy_http_version 1.1;
        proxy_set_header Connection        "";
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        # Overwritten, not appended: with no trusted L7 hop in front of nginx,
        # a client-supplied X-Forwarded-For chain would be forgeable. If a real
        # load balancer is added, configure set_real_ip_from/real_ip_header and
        # switch this to $proxy_add_x_forwarded_for.
        proxy_set_header X-Forwarded-For   $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Port  $server_port;
        proxy_set_header X-Request-Id      $request_id;

        # Small JSON payloads: fail fast on connect, allow a normal request to
        # finish, and stay under gunicorn's 30s worker timeout so a stuck
        # request surfaces as a 504 here rather than a killed worker there.
        proxy_connect_timeout  5s;
        proxy_send_timeout     30s;
        proxy_read_timeout     30s;

        # Retry only when the request was provably not processed.
        proxy_next_upstream          error timeout http_502 http_503 http_504;
        proxy_next_upstream_tries    2;
        proxy_next_upstream_timeout  10s;

        proxy_buffering          on;
        proxy_buffers            8 16k;
        proxy_buffer_size        16k;
        proxy_busy_buffers_size  32k;
        proxy_redirect           off;

        # nginx's own liveness, answered without touching the API. Used by the
        # proxy container healthcheck.
        location = /nginx-health {
            access_log off;
            return 200 '{"status":"ok","component":"proxy"}';
        }

        # Application health: proxied, but never rate limited or logged so a
        # probe loop cannot exhaust the client budget or flood the logs.
        location = /healthz {
            access_log off;
            proxy_pass http://api_backend;
        }

        location / {
            limit_req   zone=api_rate burst=40 nodelay;
            limit_conn  api_conn 32;
            proxy_pass  http://api_backend;
        }

        # Always answer with JSON, including nginx-generated errors.
        error_page 429 = @rate_limited;
        error_page 502 = @upstream_error;
        error_page 503 = @upstream_unavailable;
        error_page 504 = @upstream_timeout;

        location @rate_limited {
            return 429 '{"error":"rate_limited","request_id":"$request_id"}';
        }
        location @upstream_error {
            return 502 '{"error":"bad_gateway","request_id":"$request_id"}';
        }
        location @upstream_unavailable {
            return 503 '{"error":"service_unavailable","request_id":"$request_id"}';
        }
        location @upstream_timeout {
            return 504 '{"error":"gateway_timeout","request_id":"$request_id"}';
        }
    }
}

mimo/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

mimo/03-infra-management/verify_config.py

"""Structural verification for this stack. Starts no containers.

Usage:  python3 verify_config.py   (exit 0 = all checks pass)
"""
import json, os, re, subprocess, sys

fails = []
def check(name, cond, detail=""):
    print(("PASS  " if cond else "FAIL  ") + name + (("   -- " + str(detail)) if not cond else ""))
    if not cond:
        fails.append(name)

def strip_comments(text):
    return re.sub(r'(?m)#[^\n]*', '', text)

# ---------- Dockerfile ----------
df_raw = open("Dockerfile").read()
df = strip_comments(df_raw)
exec_forms = re.findall(r'^(?:CMD|HEALTHCHECK[^\n]*?\n\s*CMD)\s+(\[.*\])\s*$', df_raw, re.M)
ok_json = True
for e in exec_forms:
    try: json.loads(e)
    except Exception: ok_json = False
check("Dockerfile: exec-form CMD/HEALTHCHECK are valid JSON arrays", ok_json and len(exec_forms) == 2, exec_forms)
check("Dockerfile: no Flask dev server / FLASK_ENV=development", "flask run" not in df and "FLASK_ENV" not in df)
check("Dockerfile: gunicorn is the process", "gunicorn" in df)
check("Dockerfile: unpinned `pip install <pkgs>` is gone", re.search(r'pip install (?!--)(?!-r)\S', df) is None)
check("Dockerfile: installs from pinned requirements.txt", "-r requirements.txt" in df)
check("Dockerfile: slim base image", "python:3.13-slim" in df)
check("Dockerfile: multi-stage (builder + runtime)", len(re.findall(r'(?m)^FROM ', df)) >= 3)
check("Dockerfile: runs as a non-root UID", re.search(r'(?m)^USER 10001:10001$', df) is not None)
check("Dockerfile: USER precedes CMD", df.index("USER 10001") < df.rindex("CMD ["))
stages = set(re.findall(r'(?m)^FROM \S+ AS (\S+)', df))
refs = set(re.findall(r'--from=(\S+)', df))
check("Dockerfile: every --from= names a defined stage", refs <= stages, f"{refs} vs {stages}")
check("Dockerfile: image-level HEALTHCHECK present", "HEALTHCHECK" in df)

# ---------- gunicorn.conf.py ----------
g = open("gunicorn.conf.py").read()
ns = {}
os.environ.pop("APP_PORT", None)
exec(compile(g, "gunicorn.conf.py", "exec"), ns)
check("gunicorn.conf.py: imports and evaluates", True)
check("gunicorn.conf.py: default bind 0.0.0.0:8000", ns["bind"] == "0.0.0.0:8000", ns["bind"])
check("gunicorn.conf.py: keepalive(75s) > nginx upstream keepalive_timeout(60s)", ns["keepalive"] > 60, ns["keepalive"])
check("gunicorn.conf.py: timeout(30s) <= nginx proxy_read_timeout(30s)", ns["timeout"] <= 30, ns["timeout"])
check("gunicorn.conf.py: graceful_timeout <= compose stop_grace_period(30s)", ns["graceful_timeout"] <= 30, ns["graceful_timeout"])
check("gunicorn.conf.py: worker_tmp_dir on the tmpfs", ns["worker_tmp_dir"] == "/tmp", ns["worker_tmp_dir"])
check("gunicorn.conf.py: logs to stdout/stderr", ns["accesslog"] == "-" and ns["errorlog"] == "-")

# ---------- nginx.conf (structural parse) ----------
nx = open("nginx.conf").read()
body = strip_comments(nx)
depth, buf, quote, errors = 0, "", None, []
for ch in body:
    if quote:
        buf += ch
        if ch == quote: quote = None
        continue
    if ch in "'\"":
        quote = ch; buf += ch; continue
    if ch == ";":
        buf = ""
    elif ch == "{":
        depth += 1; buf = ""
    elif ch == "}":
        if buf.strip(): errors.append("unterminated directive before '}': " + buf.strip()[:60])
        depth -= 1; buf = ""
        if depth < 0: errors.append("unbalanced closing brace")
    else:
        buf += ch
check("nginx.conf: blocks balanced and every directive terminated", depth == 0 and not errors and not buf.strip(),
      errors or f"depth={depth} trailing={buf.strip()[:60]!r}")
named = set(re.findall(r'location (@\w+)', nx))
referenced = set(re.findall(r'error_page [^;]*?=\s*(@\w+);', nx))
check("nginx.conf: every error_page target has a named location", referenced <= named and referenced, referenced - named)
check("nginx.conf: pid/temp paths under /tmp (unprivileged + read-only rootfs)",
      "/tmp/nginx.pid" in nx and nx.count("_temp_path      /tmp") + nx.count("_temp_path  /tmp") + nx.count("_temp_path        /tmp") >= 1)
check("nginx.conf: listens on 8080 (no privileged port)", re.search(r'listen\s+8080;', nx) is not None and not re.search(r'listen\s+80;', nx))
for token, label in [("proxy_connect_timeout", "connect timeout"), ("proxy_read_timeout", "read timeout"),
                     ("proxy_send_timeout", "send timeout"), ("client_max_body_size", "body size cap"),
                     ("client_body_timeout", "slow-body timeout"), ("limit_req_zone", "rate limit"),
                     ("limit_conn_zone", "connection limit"), ("server_tokens", "version hiding"),
                     ("proxy_http_version", "HTTP/1.1 upstream"), ("X-Forwarded-Proto", "proto header"),
                     ("X-Real-IP", "real ip header"), ("X-Request-Id", "request id"),
                     ("X-Content-Type-Options", "nosniff")]:
    check(f"nginx.conf: {label} configured ({token})", token in nx)
check("nginx.conf: keepalive upstream pool needs empty Connection header",
      re.search(r'keepalive\s+32;', nx) is not None and re.search(r'proxy_set_header Connection\s+"";', nx) is not None)
check("nginx.conf: X-Forwarded-For is overwritten, not appended (no client spoofing)",
      "proxy_set_header X-Forwarded-For   $remote_addr;" in nx and "$proxy_add_x_forwarded_for" not in strip_comments(nx))
check("nginx.conf: health endpoints are not rate limited",
      re.search(r'location = /healthz \{[^}]*access_log off;[^}]*\}', nx, re.S) is not None)

# ---------- compose ----------
env = dict(os.environ, POSTGRES_USER="app", POSTGRES_PASSWORD="validate-only",
           POSTGRES_DB="app", REDIS_PASSWORD="validate-only")
out = subprocess.run(["docker", "compose", "config", "--format", "json"], capture_output=True, text=True, env=env)
check("compose: `docker compose config` renders without error", out.returncode == 0, out.stderr.strip()[:300])
missing = subprocess.run(["docker", "compose", "config", "--quiet"], capture_output=True, text=True,
                         env={k: v for k, v in os.environ.items() if not k.startswith(("POSTGRES_", "REDIS_"))})
check("compose: missing credentials abort the run (fail fast)", missing.returncode != 0, missing.stdout[:200])
cfg = json.loads(out.stdout); svcs = cfg["services"]
check("compose: same four services, nothing added", set(svcs) == {"proxy", "api", "db", "cache"}, set(svcs))
pub = {n: [p.get("published") for p in s.get("ports", [])] for n, s in svcs.items()}
check("compose: only the proxy publishes a host port", [n for n, p in pub.items() if p] == ["proxy"], pub)
check("compose: proxy binds loopback by default", svcs["proxy"]["ports"][0]["host_ip"] == "127.0.0.1", svcs["proxy"]["ports"])
check("compose: Postgres 5432 not published", not svcs["db"].get("ports"))
check("compose: Redis 6379 not published", not svcs["cache"].get("ports"))
check("compose: all four services have healthchecks", all("healthcheck" in s for s in svcs.values()))
check("compose: api starts only when db and cache are healthy",
      all(svcs["api"]["depends_on"][d]["condition"] == "service_healthy" for d in ("db", "cache")))
check("compose: proxy starts only when api is healthy", svcs["proxy"]["depends_on"]["api"]["condition"] == "service_healthy")
check("compose: restart policy on every service", all(s.get("restart") == "unless-stopped" for s in svcs.values()))
check("compose: log rotation on every service", all(s["logging"]["options"]["max-size"] == "10m" for s in svcs.values()))
check("compose: cpu/memory/pids limits on every service",
      all({"cpus", "memory", "pids"} <= set(s["deploy"]["resources"]["limits"]) for s in svcs.values()))
check("compose: no-new-privileges on every service", all("no-new-privileges:true" in s.get("security_opt", []) for s in svcs.values()))
check("compose: capabilities dropped on every service", all(s.get("cap_drop") == ["ALL"] for s in svcs.values()))
check("compose: Postgres data on the named volume `pgdata`",
      any(v.get("source") == "pgdata" and v["target"].startswith("/var/lib/postgresql") for v in svcs["db"]["volumes"])
      and "pgdata" in cfg.get("volumes", {}))
check("compose: data network is `internal: true`", cfg["networks"]["backend"]["internal"] is True)
check("compose: proxy has no route to db/cache", set(svcs["proxy"]["networks"]) == {"edge"}, list(svcs["proxy"]["networks"]))
check("compose: db and cache are on the data network only",
      set(svcs["db"]["networks"]) == {"backend"} and set(svcs["cache"]["networks"]) == {"backend"})
check("compose: api is the only bridge between segments", set(svcs["api"]["networks"]) == {"edge", "backend"})
check("compose: api and proxy filesystems are read-only", svcs["api"]["read_only"] and svcs["proxy"]["read_only"])
check("compose: nginx.conf is mounted read-only", all(v.get("read_only") for v in svcs["proxy"]["volumes"]))
check("compose: api drain window >= gunicorn graceful_timeout", svcs["api"]["stop_grace_period"] in ("30s", "0m30s"), svcs["api"]["stop_grace_period"])
check("compose: redis requires a password and evicts instead of OOM",
      "--requirepass" in " ".join(svcs["cache"]["command"]) and "allkeys-lru" in " ".join(svcs["cache"]["command"]))

# ---------- secret hygiene ----------
src = open("compose.yaml").read()
check("source: no credential literals in compose.yaml",
      "admin:password" not in src and "POSTGRES_PASSWORD: password" not in src and "@db:5432" in src)
check("source: every credential is a ${...} reference with a fail-fast default",
      src.count("POSTGRES_PASSWORD:?") >= 2 and src.count("REDIS_PASSWORD:?") >= 2)
check("rendered: .env value flows into DATABASE_URL", "validate-only@db:5432" in out.stdout)
gi, di = open(".gitignore").read(), open(".dockerignore").read()
check(".gitignore excludes .env and secrets", ".env" in gi and "secrets/" in gi and "!.env.example" in gi)
check(".dockerignore excludes .env, .git, secrets, backups",
      all(x in di for x in (".env", ".git", "secrets/", "backups/")))
check(".env.example documents every required variable",
      all(k in open(".env.example").read() for k in ("POSTGRES_USER", "POSTGRES_PASSWORD", "POSTGRES_DB", "REDIS_PASSWORD", "HTTP_BIND_ADDR", "APP_VERSION")))
check("no .env checked in beside the example", not os.path.exists(".env"))

print("FAILURES: %d" % len(fails))
for f in fails: print("  -", f)
sys.exit(1 if fails else 0)

mcode-m3.1-flash/03-infra-management/RESPONSE.md

mcode-m3.1-flash/03-infra-management/RUNBOOK.md

cp .env.example .env
# Generate real passwords, do not use the placeholders:
#   openssl rand -base64 32
$EDITOR .env          # set POSTGRES_PASSWORD and REDIS_PASSWORD

docker compose config --quiet    # validate; fails if a required secret is missing
docker compose up -d --build
docker compose ps                # wait for all four to read "healthy"

docker compose logs -f api      # follow the application
docker compose logs -f proxy    # JSON access log, one object per line

# 1. Data stores are up and reachable
docker compose ps                                   # every service: healthy
docker compose exec db sh -c 'pg_isready -q -U "$POSTGRES_USER" -d "$POSTGRES_DB"' && echo "db ready"

# 2. API liveness, straight to the container
docker compose exec api python -c "import urllib.request as u; print(u.urlopen('http://127.0.0.1:8000/health').read())"

# 3. API readiness - reports each dependency separately
docker compose exec api python -c "import urllib.request as u; print(u.urlopen('http://127.0.0.1:8000/ready').read())"

# 4. End to end, through the only published port
curl -i http://127.0.0.1:8080/healthz    # proxy liveness
curl -i http://127.0.0.1:8080/health     # proxied to the API

docker inspect --format '{{.Name}} {{.State.Health.Status}}' $(docker compose ps -q)

# Backup: logical dump in plain SQL format. Contains real rows -> gitignored.
mkdir -p backups
docker compose exec -T db sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' \
  > backups/app-$(date +%F-%H%M).sql

# Verify the dump - a 0-byte or truncated file is a failed backup
ls -lh backups/
head -20 backups/app-2026-01-01-0000.sql      # must show the pg_dump header

docker compose stop api                      # stop writers first
docker compose exec -T db sh -c \
  'psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
  < backups/app-2026-01-01-0000.sql
docker compose start api
curl -fsS http://127.0.0.1:8080/ready && echo restored

git status                        # what changed
git log --oneline -5
git checkout <last-good-sha> -- compose.yaml Dockerfile nginx.conf requirements.txt
docker compose config --quiet
docker compose up -d --build

docker compose up -d --build api   # rebuild from the restored source

mcode-m3.1-flash/03-infra-management/TASK.md

mcode-m3.1-flash/03-infra-management/.dockerignore

# Keep the build context minimal and secret-free. Anything not excluded here
# is uploaded to the daemon and, if the Dockerfile said `COPY . .`, baked into
# an image layer - where it survives even if you later delete the file.

# Secrets and local state
.env
.env.*
!.env.example
*.pem
*.key
secrets/

# Backups: dumps are data, not source
backups/
*.sql
*.sql.gz
*.dump

# Version control and local tooling
.git
.gitignore
.dockerignore
.venv
venv/
__pycache__/
*.py[cod]
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
htmlcov/

# Docs and editor noise for the image
*.md
!app.py
.idea/
.vscode/
.DS_Store

mcode-m3.1-flash/03-infra-management/.env.example

# Copy to .env and edit. `cp .env.example .env`
# .env holds real secrets: it is gitignored, excluded from the Docker build
# context, and never committed. Compose reads it for both interpolation of the
# ${...} placeholders in compose.yaml and the values passed to containers.
#
# Generate real passwords, do not type them by hand:
#   openssl rand -base64 32
# Avoid '@', ':' and '/' issues by keeping passwords in the discrete
# POSTGRES_PASSWORD / REDIS_PASSWORD variables rather than building a
# postgres:// or redis:// URL by hand.

# ---- Postgres (required) --------------------------------------------------
POSTGRES_USER=app
POSTGRES_PASSWORD=CHANGE_ME_generate_with_openssl_rand_base64_32
POSTGRES_DB=app

# ---- Redis (required) -----------------------------------------------------
# Cache only. Losing it costs a cold cache, not data, so rotate it freely.
REDIS_PASSWORD=CHANGE_ME_generate_with_openssl_rand_base64_32

# ---- Edge (optional) ------------------------------------------------------
# Where the published proxy port binds on the host.
# Use 127.0.0.1 for a laptop so the stack is not exposed to the local network.
HTTP_BIND=127.0.0.1
HTTP_PORT=8080

# ---- API capacity (optional) ---------------------------------------------
# gunicorn workers x threads = concurrent request handlers. Keep
# (workers x threads) comfortably below the db max_connections of 100.
API_WORKERS=2
API_THREADS=4

# ---- Production overrides (optional) -------------------------------------
# HTTP_BIND=0.0.0.0
# HTTP_PORT=80
# API_WORKERS=4
# API_THREADS=8

mcode-m3.1-flash/03-infra-management/.gitignore

# Real secrets never belong in version control.
.env
.env.*
!.env.example
secrets/

# Dumps contain live data (and often rows of real users).
backups/
*.sql
*.sql.gz
*.dump

__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
.ruff_cache/
.DS_Store

mcode-m3.1-flash/03-infra-management/app.py

"""Minimal JSON API for the deployment.

This module exists so the health checks in compose.yaml probe something real
instead of a guess. It is deliberately small:

  GET /health  liveness  - "the process is up and serving". No dependency
                          calls, so a database outage never triggers a
                          restart loop.
  GET /ready   readiness - "dependencies are usable". Backs the proxy's
                          `depends_on: condition: service_healthy`, so nginx
                          is only declared healthy once the API can actually
                          serve traffic.

Replace the `/` body with the real application; keep the two health
endpoints and their semantics (liveness cheap, readiness checks deps).
"""

import os
import time

# Only the web framework is imported at startup. The database and cache
# drivers are imported inside the readiness checks, so a broken or missing
# driver shows up as /ready returning 503 rather than the process failing to
# boot - which is what keeps /health honest as a liveness signal.
from flask import Flask, jsonify
from werkzeug.middleware.proxy_fix import ProxyFix

app = Flask(__name__)

# Trust exactly one reverse proxy hop (nginx), so request.remote_addr and
# url_scheme are the real client values instead of the proxy's. The X-Forwarded-*
# headers nginx sets are only honoured from that hop.
app.wsgi_app = ProxyFix(
    app.wsgi_app,
    x_for=1,
    x_proto=1,
    x_host=1,
    x_port=0,
    x_prefix=0,
)

# Seconds. Kept short so a hung dependency fails the probe instead of
# stalling it; the probe is retried by the healthcheck interval.
DEPENDENCY_TIMEOUT = float(os.environ.get("DEPENDENCY_TIMEOUT", "2"))


def _database_url() -> str:
    """Build a DSN from discrete parts, so passwords need no URL escaping.

    A password containing '@', ':' or '/' breaks a hand-written
    postgres:// URL; libpq keyword arguments do not have that failure mode.
    An explicit DATABASE_URL still wins if it is set.
    """
    url = os.environ.get("DATABASE_URL")
    if url:
        return url
    return " ".join(
        [
            f"host={os.environ.get('POSTGRES_HOST', 'db')}",
            f"port={os.environ.get('POSTGRES_PORT', '5432')}",
            f"user={os.environ.get('POSTGRES_USER', 'app')}",
            f"password={os.environ.get('POSTGRES_PASSWORD', '')}",
            f"dbname={os.environ.get('POSTGRES_DB', 'app')}",
            "connect_timeout=3",
        ]
    )


def _redis_url() -> str:
    url = os.environ.get("REDIS_URL")
    if url:
        return url
    host = os.environ.get("REDIS_HOST", "cache")
    port = os.environ.get("REDIS_PORT", "6379")
    password = os.environ.get("REDIS_PASSWORD", "")
    auth = f":{password}@" if password else ""
    return f"redis://{auth}{host}:{port}/0"


def check_postgres() -> tuple[bool, str]:
    started = time.monotonic()
    conn = None
    try:
        import psycopg2

        conn = psycopg2.connect(_database_url(), connect_timeout=3)
        with conn.cursor() as cur:
            cur.execute("SELECT 1")
            cur.fetchone()
        return True, f"{(time.monotonic() - started) * 1000:.1f}ms"
    except Exception as exc:  # noqa: BLE001 - reported, never fatal to serving
        return False, type(exc).__name__
    finally:
        # psycopg2's connection context manager only ends the transaction, it
        # does not close the socket, so closing is explicit.
        if conn is not None:
            conn.close()


def check_redis() -> tuple[bool, str]:
    started = time.monotonic()
    client = None
    try:
        import redis

        client = redis.Redis.from_url(
            _redis_url(),
            socket_timeout=DEPENDENCY_TIMEOUT,
            socket_connect_timeout=DEPENDENCY_TIMEOUT,
        )
        client.ping()
        return True, f"{(time.monotonic() - started) * 1000:.1f}ms"
    except Exception as exc:  # noqa: BLE001
        return False, type(exc).__name__
    finally:
        # The client owns a connection pool; release it per probe so a
        # frequent probe cannot accumulate idle sockets in the worker.
        if client is not None:
            client.close()


@app.get("/health")
def health():
    """Liveness: process is up. Must not touch dependencies."""
    return jsonify(status="ok"), 200


@app.get("/ready")
def ready():
    """Readiness: dependencies are usable."""
    db_ok, db_detail = check_postgres()
    cache_ok, cache_detail = check_redis()
    healthy = db_ok and cache_ok
    return (
        jsonify(
            status="ok" if healthy else "degraded",
            checks={"postgres": db_ok, "redis": cache_ok},
            details={"postgres": db_detail, "redis": cache_detail},
        ),
        200 if healthy else 503,
    )


@app.get("/")
def index():
    return jsonify(service=os.environ.get("SERVICE_NAME", "api"), status="ok"), 200


if __name__ == "__main__":
    # Local debugging only. Compose runs gunicorn (see Dockerfile CMD).
    app.run(host="127.0.0.1", port=8000, debug=False)

mcode-m3.1-flash/03-infra-management/compose.yaml

# Deployment for a small JSON API behind nginx, with Postgres and Redis.
#
# Scope note: this is plain Docker Compose, not an orchestrator. It gives you
# health-gated startup, restart policies, log rotation, resource ceilings and
# two network tiers - which is what a single-host deployment needs. It does NOT
# give you multi-host failover, rolling updates, secret rotation or
# autoscaling. Those need a real orchestrator; see RUNBOOK.md "Limits".
#
# Required setup:  cp .env.example .env   (then edit the passwords)
# Validate:       docker compose config --quiet
# Start:          docker compose up -d --build
#
# Every ${VAR} below is read from .env by Compose before the stack starts, so
# no credential is ever committed here. Nothing in this file publishes a
# database or cache port to the host.

name: small-api

# Uniform log rotation. Without this the json-file driver grows without bound
# and fills the disk - the default Docker behaviour is a real outage cause.
x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  # ---------------------------------------------------------------- edge ----
  proxy:
    image: nginx:stable-alpine
    # Only the edge is reachable from outside. Bound via .env so a laptop can
    # use 127.0.0.1:8080 while a real host listens on 0.0.0.0:80.
    ports:
      - "${HTTP_BIND:-0.0.0.0}:${HTTP_PORT:-80}:80"
    volumes:
      # Read-only: nginx must never be able to rewrite its own config.
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      api:
        # Wait for the API to pass readiness, not merely to be started.
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1/healthz >/dev/null 2>&1 || exit 1"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 5s
    networks:
      - frontend
    restart: unless-stopped
    stop_grace_period: 10s
    logging: *default-logging
    security_opt:
      - no-new-privileges:true
    # A ceiling, not a reservation. Compose enforces these for a single
    # container; `deploy.resources` would be ignored outside Swarm.
    mem_limit: 256m
    cpus: 1.0
    pids_limit: 100

  # ---------------------------------------------------------------- api ----
  api:
    build:
      context: .
      dockerfile: Dockerfile
    # No `ports:`. The API is reachable only from the proxy, over `frontend`.
    environment:
      SERVICE_NAME: api
      # Discrete parts rather than a postgres:// URL: a password containing
      # '@', ':' or '/' would need percent-encoding inside a URL and would
      # fail to parse. app.py builds a libpq DSN from these.
      POSTGRES_HOST: db
      POSTGRES_PORT: "5432"
      POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB in .env}
      REDIS_HOST: cache
      REDIS_PORT: "6379"
      REDIS_PASSWORD: ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
      # Capacity tuning, appended to the gunicorn args baked into the image.
      GUNICORN_CMD_ARGS: >-
        --workers=${API_WORKERS:-2}
        --threads=${API_THREADS:-4}
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      # Readiness, not liveness: nginx should not be marked healthy while the
      # API cannot reach its dependencies. A failing probe does not restart
      # the container (restart is driven by the restart policy), so a database
      # outage cannot turn into a restart loop.
      test:
        - CMD
        - python
        - -c
        - |
          import sys, urllib.request
          try:
              sys.exit(0 if urllib.request.urlopen("http://127.0.0.1:8000/ready", timeout=3).status == 200 else 1)
          except Exception:
              sys.exit(1)
      interval: 15s
      timeout: 5s
      retries: 4
      start_period: 20s
    networks:
      - frontend
      - backend
    restart: unless-stopped
    # Long enough for gunicorn to finish in-flight requests on SIGTERM.
    stop_grace_period: 35s
    read_only: true
    # read_only blocks the only path gunicorn needs for temp files.
    tmpfs:
      - /tmp:size=64m,mode=1777
    logging: *default-logging
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.5
    pids_limit: 200

  # ----------------------------------------------------------------- db ----
  db:
    # Major version pinned; ':latest' means a major upgrade can land silently
    # on the next `up` and can refuse to start against an existing data dir.
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB in .env}
      # Deterministic collation regardless of the host's locale.
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    # No published port. The only client is the api container, over `backend`.
    # To inspect from a laptop, use `docker compose exec db psql -U $POSTGRES_USER app`.
    volumes:
      - pgdata:/var/lib/postgresql/data
    # Postgres wants more shared memory than Docker's 64MB default for
    # parallel queries and large sorts.
    shm_size: 256mb
    command:
      - postgres
      # Fewer than the default 100 connections: gunicorn workers x threads all
      # connect here, and a connection ceiling is cheap protection against one
      # bad client exhausting the server's slots.
      - -c
      - max_connections=100
    healthcheck:
      # $$ escapes so the value is expanded by the shell INSIDE the container
      # from its own environment, rather than being baked in by Compose.
      test: ["CMD-SHELL", "pg_isready -q -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks:
      - backend
    restart: unless-stopped
    # Long enough for a clean shutdown checkpoint, instead of a kill mid-write.
    stop_grace_period: 30s
    logging: *default-logging
    security_opt:
      - no-new-privileges:true
    mem_limit: 1g
    cpus: 2.0
    pids_limit: 200

  # -------------------------------------------------------------- cache ----
  cache:
    image: redis:7-alpine
    # Must be present: the command below and the healthcheck both read it from
    # the container's own environment. Without it redis would start with an
    # empty requirepass and the healthcheck could never pass, which would block
    # the api from ever starting (it waits on service_healthy).
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
    # No published port, and no volume: this is a cache, and a lost cache must
    # be cheap. Persistence is off, so a restart does not block on an RDB load.
    command:
      - sh
      - -c
      - >
        exec redis-server
        --requirepass "$$REDIS_PASSWORD"
        --appendonly no
        --save ""
        --maxmemory 256mb
        --maxmemory-policy allkeys-lru
    healthcheck:
      # REDISCLI_AUTH keeps the password out of the command line, so it does
      # not show up in `ps` inside the container.
      test: ["CMD-SHELL", "REDISCLI_AUTH=\"$$REDIS_PASSWORD\" redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    networks:
      - backend
    restart: unless-stopped
    stop_grace_period: 10s
    logging: *default-logging
    security_opt:
      - no-new-privileges:true
    mem_limit: 384m
    cpus: 1.0
    pids_limit: 100

# ---------------------------------------------------------------- networks --
networks:
  # Edge tier: the proxy, and the API's inbound side.
  frontend:
    driver: bridge
  # Data tier: API, db, cache. `internal: true` means these containers have no
  # route to the outside world - a compromised database cannot call home, and
  # the data stores are not exposed on the host's networks at all. The API is
  # on both tiers so it can still reach the internet if it ever needs to.
  backend:
    driver: bridge
    internal: true

volumes:
  # Named volume, not a bind mount: a bind mount inherits host directory
  # ownership and is easy to back up or destroy by accident.
  pgdata:

mcode-m3.1-flash/03-infra-management/Dockerfile

# syntax=docker/dockerfile:1.7
#
# Image for the small JSON API. Priorities, in order:
#   1. no secrets in the image or in the build context
#   2. run as a non-root user
#   3. production WSGI server, not the Flask dev server
#   4. reproducible installs (pinned requirements, resolved once, at build time)
#
# Build from this directory:  docker compose build api
FROM python:3.13-slim-bookworm

# PYTHONDONTWRITEBYTECODE: no stray .pyc files in the image layer.
# PYTHONUNBUFFERED: logs reach `docker compose logs` immediately.
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=1 \
    VIRTUAL_ENV=/opt/venv \
    PATH=/opt/venv/bin:$PATH

# Fixed uid/gid so bind-mounted files have predictable ownership.
RUN groupadd --system --gid 10001 app \
 && useradd  --system --uid 10001 --gid app --home-dir /app --shell /usr/sbin/nologin app

WORKDIR /app

# Dependencies first: this layer is only invalidated when requirements.txt
# changes, so ordinary code edits do not re-run pip.
COPY requirements.txt ./

# psycopg2-binary ships wheels, so no compiler toolchain is needed in the
# final image. --no-compile keeps image size down. `pip install -r` uses the
# exact == pins, so the resolved dependency set is reproducible.
# (For a stronger guarantee add --require-hashes with a generated
#  requirements.lock; that needs a network resolve and is out of scope here.)
RUN python -m venv "$VIRTUAL_ENV" \
 && pip install --no-cache-dir --upgrade pip \
 && pip install --no-cache-dir --no-compile -r requirements.txt

# Copy only the application source. Never `COPY . .`: the build context
# contains .env, which must stay out of the image (see .dockerignore).
COPY --chown=app:app app.py ./

# Drop to the unprivileged user for the rest of the build and for runtime.
USER 10001:10001

# Not published to the host: nginx reaches the API over the internal network.
EXPOSE 8000

# Runtime tuning lives in two places on purpose:
#   * safety-relevant defaults are pinned below, so the image is correct on its
#     own (e.g. when run with `docker run` or by a different orchestrator);
#   * capacity knobs (workers/threads) are overridden in compose.yaml through
#     GUNICORN_CMD_ARGS, which gunicorn appends to this list, so tuning does
#     not require editing the image or duplicating flags in two places.
# --forwarded-allow-ips must cover the nginx container IP: gunicorn ignores
# X-Forwarded-* from any source outside this list, and ProxyFix is how the app
# learns the real client address and scheme. `*` is acceptable here because the
# API port is never published to the host, so only a container on the internal
# network can reach it. Narrow it to a fixed proxy IP if that changes.
STOPSIGNAL SIGTERM
CMD ["gunicorn", \
     "--bind=0.0.0.0:8000", \
     "--worker-class=gthread", \
     "--timeout=30", \
     "--graceful-timeout=30", \
     "--keep-alive=5", \
     "--max-requests=1000", \
     "--max-requests-jitter=100", \
     "--access-logfile=-", \
     "--error-logfile=-", \
     "--capture-output", \
     "--forwarded-allow-ips=*", \
     "app:app"]

mcode-m3.1-flash/03-infra-management/nginx.conf

# Full nginx config for the edge of the small API. Mounted read-only at
# /etc/nginx/nginx.conf (see compose.yaml), replacing the image's default.
#
# Tuned for a JSON API: small bodies, fast responses, no HTML, no
# long-polling. If you add file uploads or SSE, revisit client_max_body_size
# and proxy_read_timeout - they are the two settings that will bite you.

user  nginx;
# One worker per CPU, bounded by Docker's cpus limit for this container.
worker_processes  auto;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/json;

    # Do not advertise the nginx version in responses and in the Server header.
    server_tokens off;

    # ---- logging ---------------------------------------------------------
    # JSON lines, so log shipping does not need a grok pattern. request_time
    # and upstream_response_time make slow requests obvious; upstream_connect
    # separates "API was slow" from "API was unreachable".
    log_format json_combined escape=json
      '{'
        '"time":"$time_iso8601",'
        '"request_id":"$request_id",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$uri",'
        '"status":$status,'
        '"bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_addr":"$upstream_addr",'
        '"upstream_status":"$upstream_status",'
        '"upstream_connect_time":"$upstream_connect_time",'
        '"upstream_response_time":"$upstream_response_time",'
        '"user_agent":"$http_user_agent"'
      '}';

    access_log  /var/log/nginx/access.log  json_combined buffer=32k  flush=5s;

    # ---- transport -------------------------------------------------------
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    server_names_hash_bucket_size 128;

    keepalive_timeout  65;
    # A JSON API request should not take a minute to arrive.
    client_body_timeout   15s;
    client_header_timeout 15s;
    send_timeout          30s;
    # Free the client's connection when it is too slow to send a body, rather
    # than holding it open.
    reset_timedout_connection on;

    # 1 MB is generous for a JSON body. Raise deliberately if you add uploads.
    client_max_body_size 1m;
    client_body_buffer_size 16k;

    # ---- compression -----------------------------------------------------
    gzip              on;
    gzip_vary         on;
    gzip_proxied      any;
    gzip_comp_level   5;
    gzip_min_length   1024;
    gzip_types        application/json application/javascript text/plain text/css;

    # ---- upstream DNS ----------------------------------------------------
    # Docker's embedded DNS server. With `proxy_pass http://api:8000` nginx
    # resolves "api" once at startup and caches it forever, so after the api
    # container is recreated with a new IP every request fails with 502 until
    # nginx is reloaded. Using a variable in proxy_pass makes nginx re-resolve
    # per request using the TTL below.
    resolver  127.0.0.11 ipv6=off valid=10s;
    resolver_timeout 5s;

    server {
        listen      80 default_server;
        listen      [::]:80 default_server;
        server_name _;

        # Rejecting unexpected Host headers is worth doing on a real
        # deployment, by setting server_name to the real name and adding a
        # catch-all server that returns 444. Left permissive here so that
        # localhost, 127.0.0.1 and container IPs all work out of the box.

        # Proxy's own liveness, used by the container healthcheck. Probing
        # nginx rather than the API is intentional: nginx being healthy must
        # not depend on the API, or a database outage would mark the edge
        # unhealthy and trigger a pointless restart loop. The api -> proxy
        # dependency is health-gated in compose.yaml instead.
        location = /healthz {
            access_log off;
            default_type text/plain;
            return 200 "ok\n";
        }

        location / {
            set $api_upstream api:8000;

            # Variable form: enables resolver-based re-resolution (see above).
            # No URI part, so the original request URI is passed through
            # unchanged.
            proxy_pass http://$api_upstream;

            proxy_http_version 1.1;
            # Empty Connection header keeps the upstream connection alive for
            # reuse; without it nginx sends "Connection: close".
            proxy_set_header Connection        "";

            # ---- forwarded headers ----
            # gunicorn + ProxyFix rebuild the client address and scheme from
            # these, so a missing one shows up as wrong IPs and http:// URLs in
            # logs and redirects.
            proxy_set_header Host              $host;
            proxy_set_header X-Real-IP         $remote_addr;
            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host  $host;
            proxy_set_header X-Forwarded-Port  $server_port;
            # Correlate proxy and application logs; also pass through one the
            # client supplied.
            proxy_set_header X-Request-ID      $request_id;

            # ---- timeouts ----
            # Fail fast when the API is down instead of pinning a worker
            # indefinitely. proxy_read_timeout must exceed the API's own
            # gunicorn --timeout (30s) or nginx will cut off slow-but-fine
            # requests.
            proxy_connect_timeout 5s;
            proxy_send_timeout    35s;
            proxy_read_timeout    35s;

            # Small responses; do not buffer a large temp file to disk.
            proxy_buffering       on;
            proxy_buffer_size     8k;
            proxy_buffers         8 8k;
            proxy_busy_buffers_size 16k;

            # Return the API's own error body rather than an HTML error page:
            # clients of a JSON API should always get JSON back, including for
            # gateway errors.
            proxy_intercept_errors off;
        }
    }
}

mcode-m3.1-flash/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

muse/03-infra-management/RESPONSE.md

muse/03-infra-management/RUNBOOK.md

muse/03-infra-management/TASK.md

muse/03-infra-management/.dockerignore

# Keep secrets, VCS metadata, and deploy files out of the image.
.env
.git
.gitignore
__pycache__/
*.pyc
.venv/
compose.yaml
nginx.conf
*.md

muse/03-infra-management/.env.example

# Copy to .env and set real secrets before first start:
#   cp .env.example .env
# Never commit .env (see RUNBOOK.md).

POSTGRES_USER=app
POSTGRES_PASSWORD=change-me-before-first-run
POSTGRES_DB=app

# Host port mapped to nginx:80. Container ports stay fixed.
NGINX_HTTP_PORT=80

# Redis has no password and is reachable only on the internal backend
# network. If you need auth, set REDIS_PASSWORD here AND update the
# cache command/healthcheck and the api REDIS_URL in compose.yaml.
# REDIS_PASSWORD=change-me-too

muse/03-infra-management/compose.yaml

# Shared logging profile: bounded local log files so a chatty service
# cannot fill the host disk.
x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  proxy:
    image: nginx:1.27-alpine
    ports:
      - "${NGINX_HTTP_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      api:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - frontend
    logging: *default-logging
    deploy:
      resources:
        limits:
          cpus: "0.25"
          memory: 128M
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1/nginx-health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  api:
    build:
      context: .
    environment:
      DATABASE_URL: "postgresql://${POSTGRES_USER:?Set POSTGRES_USER in .env}:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@db:5432/${POSTGRES_DB:?Set POSTGRES_DB in .env}"
      REDIS_URL: "redis://cache:6379/0"
    expose:
      - "5000"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - frontend
      - backend
    logging: *default-logging
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
    healthcheck:
      # Requires the API to serve GET /healthz with HTTP 200.
      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:5000/healthz', timeout=4)\""]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

  db:
    image: postgres:16-bookworm
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?Set POSTGRES_USER in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:?Set POSTGRES_DB in .env}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - backend
    logging: *default-logging
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

  cache:
    image: redis:7-alpine
    restart: unless-stopped
    networks:
      - backend
    logging: *default-logging
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 256M
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

volumes:
  pgdata:

networks:
  frontend:
  backend:
    internal: true

muse/03-infra-management/Dockerfile

FROM python:3.13-slim

# Minor-version pin balances reproducibility with security updates.
# For immutable builds, pin this image by digest as well.

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

WORKDIR /app

RUN groupadd -r appuser && useradd -r -g appuser appuser

# Install dependencies first for layer caching; requirements.txt is
# version-pinned so installs are reproducible.
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser . .

USER appuser

EXPOSE 5000

# The API must expose GET /healthz returning 200 (see RUNBOOK.md).
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:5000/healthz', timeout=4)"

# Production WSGI server. Assumes app.py exposes Flask object `app`;
# adjust the module if the real entrypoint differs.
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "2", "--timeout", "30", "app:app"]

muse/03-infra-management/nginx.conf

worker_processes auto;

events {
  worker_connections 1024;
}

http {
  include /etc/nginx/mime.types;
  default_type application/octet-stream;

  access_log /var/log/nginx/access.log;
  error_log /var/log/nginx/error.log warn;

  server_tokens off;

  # Sensible limits for a JSON API: reject oversized bodies early,
  # don't hold slow clients forever.
  client_max_body_size 1m;
  client_body_timeout 10s;
  client_header_timeout 10s;
  keepalive_timeout 65s;
  send_timeout 30s;

  gzip on;
  gzip_types application/json;
  gzip_min_length 256;

  upstream api {
    server api:5000 max_fails=3 fail_timeout=10s;
  }

  server {
    listen 80;
    server_name _;

    # Liveness probe for the proxy itself (used by Compose healthcheck).
    location = /nginx-health {
      access_log off;
      add_header Content-Type text/plain;
      return 200 'ok';
    }

    location / {
      proxy_pass http://api;
      proxy_http_version 1.1;
      proxy_set_header Connection "";

      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;

      proxy_connect_timeout 5s;
      proxy_read_timeout 30s;
      proxy_send_timeout 30s;

      proxy_next_upstream error timeout;
    }
  }
}

muse/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0

gpt-6-luna/03-infra-management/RESPONSE.md

gpt-6-luna/03-infra-management/RUNBOOK.md

umask 077
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > /secure/backups/backup-$(date +%F).dump

docker compose stop api
docker compose exec -T db sh -c 'pg_restore --clean --if-exists --no-owner -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < /secure/backups/backup-YYYY-MM-DD.dump
docker compose up -d api proxy
docker compose ps

gpt-6-luna/03-infra-management/TASK.md

gpt-6-luna/03-infra-management/.dockerignore

.env
.env.*
.git
.gitignore
__pycache__/
*.py[cod]
.venv/
venv/
*.log
backup*.dump

gpt-6-luna/03-infra-management/.env.example

# Copy to .env and replace the password before starting the stack.
# A hexadecimal secret is URL-safe in DATABASE_URL; generate one with:
#   openssl rand -hex 32
POSTGRES_USER=app
POSTGRES_PASSWORD=REPLACE_WITH_RANDOM_HEX_SECRET
POSTGRES_DB=app

# Host port for nginx. Postgres, Redis, and the API are not published.
HTTP_PORT=8080

# Python WSGI module, in Gunicorn's module:variable form.
APP_MODULE=app:app

gpt-6-luna/03-infra-management/.gitignore

.env
backup*.dump

gpt-6-luna/03-infra-management/compose.yaml

services:
  proxy:
    image: nginx:1.29-alpine
    ports:
      - "${HTTP_PORT:-8080}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      api:
        condition: service_healthy
    networks:
      - edge
    restart: unless-stopped
    stop_grace_period: 10s
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/_nginx_health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    cpus: 0.25
    mem_limit: 128m
    pids_limit: 100

  api:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      APP_MODULE: "${APP_MODULE:-app:app}"
      DATABASE_URL: "postgresql://${POSTGRES_USER:?Set POSTGRES_USER in .env}:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@db:5432/${POSTGRES_DB:?Set POSTGRES_DB in .env}"
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    networks:
      - edge
      - backend
    init: true
    restart: unless-stopped
    stop_grace_period: 30s
    healthcheck:
      test:
        - CMD
        - python
        - -c
        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=2).read()"
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    cpus: 0.50
    mem_limit: 512m
    pids_limit: 100

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: "${POSTGRES_USER:?Set POSTGRES_USER in .env}"
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}"
      POSTGRES_DB: "${POSTGRES_DB:?Set POSTGRES_DB in .env}"
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - backend
    restart: unless-stopped
    stop_grace_period: 1m
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    cpus: 1.0
    mem_limit: 1g
    pids_limit: 200

  cache:
    image: redis:7-alpine
    command: ["redis-server", "--save", "", "--appendonly", "no"]
    networks:
      - backend
    restart: unless-stopped
    stop_grace_period: 10s
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    cpus: 0.25
    mem_limit: 256m
    pids_limit: 100

networks:
  edge:
    driver: bridge
  backend:
    driver: bridge
    internal: true

volumes:
  pgdata:

gpt-6-luna/03-infra-management/Dockerfile

FROM python:3.13-slim-bookworm

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

WORKDIR /app

RUN addgroup --system --gid 10001 app \
    && adduser --system --uid 10001 --ingroup app --home /app app

COPY requirements.txt ./
RUN python -m pip install --no-cache-dir --requirement requirements.txt

COPY --chown=app:app . .

USER 10001:10001
EXPOSE 8000

CMD ["sh", "-c", "exec gunicorn --bind 0.0.0.0:8000 --workers 2 --threads 2 --timeout 60 --access-logfile - --error-logfile - \"${APP_MODULE:-app:app}\""]

gpt-6-luna/03-infra-management/nginx.conf

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    server_tokens off;
    resolver 127.0.0.11 valid=10s ipv6=off;

    server {
        listen 80;
        client_max_body_size 1m;

        location = /_nginx_health {
            access_log off;
            default_type text/plain;
            return 200 "ok\n";
        }

        location / {
            set $api_backend api:8000;
            proxy_pass http://$api_backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";

            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;

            proxy_connect_timeout 5s;
            proxy_send_timeout 30s;
            proxy_read_timeout 60s;
        }
    }
}

gpt-6-luna/03-infra-management/requirements.txt

blinker==1.9.0
click==8.2.1
Flask==3.1.2
gunicorn==23.0.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==3.0.2
packaging==25.0
psycopg2-binary==2.9.10
redis==6.4.0
Werkzeug==3.1.3

mcode-m3/03-infra-management/RESPONSE.md

mcode-m3/03-infra-management/RUNBOOK.md

cp .env.example .env
# edit .env — set POSTGRES_PASSWORD, DATABASE_URL, REDIS_URL, etc.
chmod 600 .env

docker compose pull            # fetch pinned images (nginx, postgres, redis)
docker compose build api       # build the API image
docker compose up -d           # start everything in the background
docker compose ps              # confirm services are Up + healthy

docker compose restart api     # restart just the API
docker compose up -d           # idempotent: starts only what is not running
docker compose down            # stop and remove containers, KEEP volumes
docker compose down --volumes  # DESTRUCTIVE — also removes pgdata/redisdata

docker compose build api
docker compose up -d api

docker compose ps

# From the Docker host:
curl -fsS http://127.0.0.1:8080/healthz        # nginx-level liveness
curl -fsS http://127.0.0.1:8080/api/healthz   # proxied through to the API
# Add -i if you want to inspect headers (X-Forwarded-* etc.)

docker compose logs -f --tail=200            # all services, follow
docker compose logs -f api                   # one service
docker compose logs --since=15m api          # last 15 minutes

docker compose exec api env | sort           # view rendered environment
docker compose exec db pg_isready            # one-off readiness probe
docker compose exec cache redis-cli ping

# Logical backup (recommended — portable across Postgres versions):
docker compose exec -T db pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
  | gzip > backups/pg_$(date -u +%Y%m%dT%H%M%SZ).sql.gz

gunzip -c backups/pg_<timestamp>.sql.gz \
  | docker compose exec -T db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"

docker compose exec cache sh -c 'cp /data/dump.rdb /tmp/snapshot.rdb'
docker compose cp cache:/tmp/snapshot.rdb backups/redis_$(date -u +%Y%m%dT%H%M%SZ).rdb

docker compose pull api        # if you keep images in a registry
docker compose down api
docker compose up -d api

docker compose build api                      # rebuilds small-api/api:latest
docker tag small-api/api:latest small-api/api:previous

docker compose down api
docker compose up -d api                     # re-pin via image: small-api/api:previous

docker compose exec proxy nginx -s reload

docker compose stop api proxy
# restore pgdata or redisdata
docker compose up -d

mcode-m3/03-infra-management/TASK.md

mcode-m3/03-infra-management/.env.example

# Copy to .env (same directory) and replace each value.
# DO NOT commit .env. Keep secrets out of source control.

# --- Postgres ---
POSTGRES_USER=app
POSTGRES_PASSWORD=change-me
POSTGRES_DB=app

# --- App-side connection strings (used by the api container) ---
# These mirror the values above. Build them like:
#   DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
# but substitute them inline so they are usable in compose.yaml without bash.
DATABASE_URL=postgres://app:change-me@db:5432/app
REDIS_URL=redis://cache:6379/0

# --- Optional runtime tuning (read by the api container) ---
GUNICORN_WORKERS=2
GUNICORN_TIMEOUT=30

mcode-m3/03-infra-management/compose.yaml

# Compose v2 (the deployed `docker compose` CLI), not v1 `docker-compose`.
# Intended for a small single-host deployment, NOT a full orchestrator.

name: small-api

services:

  # ---------- reverse proxy / TLS terminator ----------
  proxy:
    image: nginx:1.27-alpine
    container_name: small-api-proxy
    restart: unless-stopped
    ports:
      # Only the proxy is reachable from the host
      - "127.0.0.1:8080:80"
      # Uncomment for TLS if you put certs in ./nginx/certs
      # - "127.0.0.1:8443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      # - ./nginx/certs:/etc/nginx/certs:ro
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1/healthz || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    deploy:
      resources:
        limits:
          memory: 128M
    networks:
      - frontend

  # ---------- Python API (private — only proxy can reach it) ----------
  api:
    build:
      context: .
      dockerfile: Dockerfile
    image: small-api/api:latest
    container_name: small-api-api
    restart: unless-stopped
    environment:
      # Injected from .env / host env — never hard-code secrets
      DATABASE_URL: ${DATABASE_URL}
      REDIS_URL: ${REDIS_URL}
      FLASK_ENV: production
      PYTHONUNBUFFERED: "1"
    # No host port mapping — the api is internal-only.
    expose:
      - "8000"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      # Replace /healthz with your real health endpoint.
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8000/healthz || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 20s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
    networks:
      - frontend
      - backend

  # ---------- PostgreSQL ----------
  db:
    image: postgres:16-alpine
    container_name: small-api-db
    restart: unless-stopped
    env_file:
      - .env
    # No host port mapping — db is internal-only.
    expose:
      - "5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
      # Optional: bootstrap SQL on first run only
      # - ./db/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    deploy:
      resources:
        limits:
          memory: 1G
    networks:
      - backend

  # ---------- Redis ----------
  cache:
    image: redis:7-alpine
    container_name: small-api-cache
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--save", "60", "1"]
    # No host port mapping — cache is internal-only.
    expose:
      - "6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    deploy:
      resources:
        limits:
          memory: 256M
    networks:
      - backend


# ---------- named volumes (persistent) ----------
volumes:
  pgdata:
    name: small-api-pgdata
  redisdata:
    name: small-api-redisdata


# ---------- explicit networks ----------
networks:
  frontend:
    name: small-api-frontend
  backend:
    name: small-api-backend
    internal: true   # no internet egress from the data tier

mcode-m3/03-infra-management/Dockerfile

# syntax=docker/dockerfile:1.7
# ---- builder stage: compile deps into a clean wheel layer ----
FROM python:3.12-slim AS builder

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

WORKDIR /build

# OS-level deps for psycopg2-binary build (kept in builder only)
RUN apt-get update \
    && apt-get install --no-install-recommends -y build-essential libpq-dev \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt ./
RUN pip install --prefix=/install -r requirements.txt


# ---- runtime stage: slim image, non-root user, production server ----
FROM python:3.12-slim AS runtime

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    # Defaults; override via compose env
    GUNICORN_WORKERS=2 \
    GUNICORN_TIMEOUT=30 \
    PORT=8000

# Runtime-only OS libs for psycopg2 / healthcheck
RUN apt-get update \
    && apt-get install --no-install-recommends -y libpq5 curl tini \
    && rm -rf /var/lib/apt/lists/* \
    && groupadd --system --gid 1001 app \
    && useradd  --system --uid 1001 --gid app --home-dir /app --shell /usr/sbin/nologin app

WORKDIR /app

# Bring in installed packages from the builder
COPY --from=builder /install /usr/local

# Application source only — no .env, .git, tests, etc.
COPY --chown=app:app app/ ./app/

USER app

EXPOSE 8000

# Use tini as PID 1 so signals and zombies are handled correctly
ENTRYPOINT ["/usr/bin/tini", "--"]

# Production WSGI server (gunicorn), not flask dev server
CMD ["sh", "-c", "exec gunicorn --bind 0.0.0.0:${PORT} \
                  --workers ${GUNICORN_WORKERS} \
                  --timeout ${GUNICORN_TIMEOUT} \
                  --access-logfile - \
                  --error-logfile - \
                  app.wsgi:app"]

mcode-m3/03-infra-management/nginx.conf

# Minimal but production-ish nginx config for a small JSON API.
# Place inside the proxy container at /etc/nginx/nginx.conf (read-only).

user  nginx;
worker_processes  auto;
worker_rlimit_nofile 8192;

error_log  /var/log/nginx/error.log warn;
pid        /tmp/nginx.pid;

events {
    worker_connections  1024;
    multi_accept        on;
}

http {
    # ---- basics ----
    include       /etc/nginx/mime.types;
    default_type  application/json;
    sendfile      on;
    tcp_nopush    on;
    tcp_nodelay   on;
    server_tokens off;

    # JSON-friendly payload limits (override per-route if needed)
    client_max_body_size      1m;
    client_body_buffer_size   16k;
    client_header_buffer_size 1k;
    large_client_header_buffers 4 8k;

    # ---- timeouts (tight, JSON-API tuned) ----
    client_body_timeout    10s;
    client_header_timeout  10s;
    send_timeout           30s;
    keepalive_timeout      30s;
    keepalive_requests     100;

    # ---- compression ----
    gzip              on;
    gzip_vary         on;
    gzip_min_length   256;
    gzip_proxied      any;
    gzip_comp_level   5;
    gzip_types
        application/json
        application/javascript
        text/css
        text/plain
        text/xml;

    # ---- access log (stdout-friendly json for compose log drivers) ----
    log_format  json escape=json
        '{'
            '"time":"$time_iso8601",'
            '"remote_addr":"$remote_addr",'
            '"request":"$request",'
            '"status":$status,'
            '"body_bytes_sent":$body_bytes_sent,'
            '"req_time":"$request_time",'
            '"upstream_time":"$upstream_response_time",'
            '"upstream_status":"$upstream_status",'
            '"host":"$host",'
            '"uri":"$uri",'
            '"server_name":"$server_name"'
        '}';

    access_log /var/log/nginx/access.log json;

    # ---- upstream pool w/ keepalive ----
    upstream app_upstream {
        # Resolve the API container by Compose service name.
        server api:8000 max_fails=3 fail_timeout=10s;
        keepalive 16;
    }

    # ---- public server ----
    server {
        listen      80 default_server;
        server_name _;

        # Liveness — used by `docker compose ps` / `wget` healthchecks.
        location = /healthz {
            access_log off;
            add_header Content-Type application/json;
            return 200 '{"status":"ok"}';
        }

        # Everything else proxies to the API.
        location / {
            proxy_http_version 1.1;
            proxy_set_header Connection          "";
            proxy_set_header Host                $host;
            proxy_set_header X-Real-IP           $remote_addr;
            proxy_set_header X-Forwarded-For     $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto   $scheme;
            proxy_set_header X-Forwarded-Host    $host;
            proxy_set_header X-Forwarded-Port    $server_port;

            # Hide backend identity from clients.
            proxy_hide_header X-Powered-By;
            proxy_hide_header Server;

            # Timeouts: long enough for slow endpoints, short enough
            # that a wedged upstream doesn't pile up clients.
            proxy_connect_timeout 5s;
            proxy_send_timeout    30s;
            proxy_read_timeout    30s;
            proxy_next_upstream   off;
            proxy_buffering       on;

            # Match the body limit set above.
            client_max_body_size 1m;

            proxy_pass http://app_upstream;
        }
    }
}

mcode-m3/03-infra-management/requirements.txt

Flask==3.1.2
gunicorn==23.0.0
psycopg2-binary==2.9.10
redis==6.4.0