Infrastructure

Service Map #

PostgreSQL 15 #

Primary persistence layer. Stores all run state, stage state, artifacts, approvals, and project registrations. migrations/sql/V1__projects.sql through migrations/sql/V6__indexes.sql define the complete schema.

Configuration #

postgres:
  image: postgres:15-alpine
  restart: unless-stopped
  environment:
    POSTGRES_DB:            ${POSTGRES_DB:-amtp}
    POSTGRES_USER:          ${POSTGRES_USER:-amtp}
    POSTGRES_PASSWORD:      ${POSTGRES_PASSWORD:-amtp}
    POSTGRES_INITDB_ARGS:   "--auth-host=scram-sha-256 --auth-local=scram-sha-256"
  command:
    - "postgres"
    - "-c" - "password_encryption=scram-sha-256"
    - "-c" - "max_connections=200"
    - "-c" - "shared_buffers=256MB"
    - "-c" - "work_mem=16MB"
    - "-c" - "log_min_duration_statement=500"
  volumes:
    - amtp_pgdata:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-amtp} -d ${POSTGRES_DB:-amtp}"]
    interval: 5s
    timeout:  3s
    retries:  20

Tuning notes #

• scram-sha-256 enforced for both host and local auth.
• max_connections = 200 — applications connect via PgBouncer (not directly) to stay well below this ceiling.
• shared_buffers = 256 MB, work_mem = 16 MB — dev-tuned values; increase for production.
• Queries slower than 500 ms are logged. Reference: infra/postgres/postgresql.conf.

PgBouncer 1.22 #

Connection pooler in transaction mode. Applications connect to pgbouncer:5432 (internal) or localhost:6432 (override). PgBouncer multiplexes up to 500 client connections onto a default pool of 25 server connections.

Key parameters #

Note on prepared statements. Transaction-mode pooling is incompatible with session-persistent prepared statements. Applications must use named-prepare-per-transaction patterns or rely on the MAX_PREPARED_STATEMENTS caching mechanism.

Flyway 10 (Migration Runner) #

Schema migrations are managed by Flyway. The service is defined under the opt-in migrate Compose profile; it does not start automatically with docker compose up. See the Deployment Runbook for explicit invocation instructions.

Configuration #

flyway.url=jdbc:postgresql://postgres:5432/amtp
flyway.user=amtp
flyway.schemas=public
flyway.locations=filesystem:/flyway/sql
flyway.baselineOnMigrate=true
flyway.validateOnMigrate=true
flyway.cleanDisabled=true

• cleanDisabled=true — flyway clean is permanently disabled to prevent accidental schema destruction in any environment.
• validateOnMigrate=true — checksums of previously applied migrations are verified on every run.
• baselineOnMigrate=true — allows Flyway to baseline an existing schema on first run.
• V6__indexes.sql.conf sets executeInTransaction=false because CREATE INDEX statements cannot run inside a transaction block in Postgres.

Valkey 8.0 (Cache & Rate-Limit Layer) #

Single-node Valkey instance serving three purposes: MCP API response caching, per-repo concurrency control, and sliding-window user rate limiting. It is the core token-accounting infrastructure.

valkey:
  image: valkey/valkey:8.0
  command:
    - "valkey-server"
    - "--save"         - ""           # disable RDB snapshots
    - "--appendonly"   - "no"         # disable AOF persistence
    - "--requirepass"  - "${VALKEY_PASSWORD}"
    - "--maxmemory"    - "512mb"      # hard memory cap
    - "--maxmemory-policy" - "allkeys-lru"  # evict LRU keys when cap is reached

OOM command not allowed when used memory > 'maxmemory'

const now    = Date.now();
const cutoff = now - 3_600_000;
const key    = `amtp:rl:user:${userId}:runs`;

const results = await client
  .multi()
  .zremrangebyscore(key, 0, cutoff)   // evict entries older than 1 h
  .zadd(key, now, runId)              // score = epoch ms; member = run id
  .zcard(key)                         // count of runs in current window
  .expire(key, 3600)                  // safety TTL
  .exec();

const count = results[2][1]; // [err, value] pairs; index 2 = ZCARD

Healthcheck Service (Node.js / Express / ioredis) #

Lightweight Express service that probes Valkey availability and exposes the result as a structured JSON response. Used by load-balancers and monitoring pipelines to gate on cache availability. Source: apps/healthcheck/src/server.js and apps/healthcheck/src/valkey.js.

Endpoint #

GET /health

const PROBE_KEY = "_amtp_health_ping";

app.get("/health", async (req, res) => {
  const start = performance.now();
  try {
    const timeout = new Promise((_, reject) =>
      setTimeout(() => reject(new Error("Timeout")), 500)
    );

    await Promise.race([
      (async () => {
        await client.ping();                              // step 1: liveness
        await client.set(PROBE_KEY, "1", "EX", 1);      // step 2: write (no NX)
        const echo = await client.get(PROBE_KEY);        // step 3: read
        if (echo !== "1") throw new Error("probe read mismatch");
      })(),
      timeout,
    ]);

    const latency_ms = Number.parseFloat((performance.now() - start).toFixed(2));
    return res.status(200).json({ status: "ok", valkey: "up", latency_ms });
  } catch (err) {
    const latency_ms = Number.parseFloat((performance.now() - start).toFixed(2));
    return res.status(503).json({
      status: "degraded", valkey: "down",
      error: err.message, latency_ms,
    });
  }
});

FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev

FROM node:20-alpine
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
COPY src/ ./src/
USER node
EXPOSE 8080
CMD ["node", "src/server.js"]

GitHub MCP Server (amtp-github-mcp) #

A stateless Streamable-HTTP MCP server that exposes two tools — repo.tree and repo.read_file — over a GitHub App installation. It connects to Valkey for caching (see namespaces above) and to the OTel Collector for traces and metrics.

Docs Service (nginx) #

Static documentation server based on nginx:1.27-alpine. Serves the compiled docs/AMTP_Docs_Website/ directory over HTTP. Host port is parameterized via DOCS_HOST_PORT (default 80). Configuration: infra/nginx/default.conf.

nginx configuration highlights #

• gzip enabled for text/html, text/css, application/javascript, application/json, and image/svg+xml.
• Security headers: X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin.
• /healthz returns 200 OK with body ok. Used by docker-compose.yml healthcheck and CI smoke tests.
• DAC requirement: all files under docs/AMTP_Docs_Website/ and infra/nginx/ must be readable by the nginx worker (chmod -R a+rX applied in CI before serving).

Garage S3 (Artifact Storage) #

Garage is an S3-compatible object store provisioned for AMTP test bundle storage. It is a lightweight, self-hosted alternative to AWS S3.

Network & Volumes #

amtp_net

Bridge network. All services communicate by service name (Docker internal DNS). No service is exposed to the host by default except via the override file.

Network pinning. The network name is amtp_net — fixed by COMPOSE_PROJECT_NAME=amtp in .env. Changing the project name changes the network name and breaks all cross-stack service discovery. The observability stack in docker-compose.observability.yml declares amtp_net: external: true and attaches to this exact name. The main stack must be brought up at least once before the observability stack deploys. See Observability → Network Dependency.

amtp_pgdata

Named volume for Postgres data directory (/var/lib/postgresql/data). Persists across container restarts. Must be explicitly removed with docker compose down -v to reset.