Backend Option C: Docker + AWS ECS Fargate

What you'll build

The same Notes API — this time as a containerized service on AWS ECS Fargate. You package the app in a Docker image, push it to ECR, and run it as a long-lived container behind a load balancer. This is the path for a "real server" app — a framework like NestJS, Express, or FastAPI, with persistent connections, background workers, Redis, or Kafka — that isn't a natural fit for per-request Lambda.

Lambda vs. containers — when to pick this

• Reach for Fargate (this part) for a long-running framework app, persistent connections (WebSockets, Kafka consumers, DB pools), heavy dependencies, or "one image that runs anywhere."
• Reach for Lambda (Part 5) for spiky or low-traffic request/response APIs where scale-to-zero and zero ops matter more.

The pieces

The project structure

Start minimal, then let it grow into the shape below. The container-native twist: one image, two entrypoints (web + worker), and everything about infra lives in the repo as reviewable code:

notes-api/
├─ Dockerfile                     # multi-stage build → small runtime image
├─ .dockerignore
├─ docker-compose.yml             # app + postgres + redis, wired for local dev
├─ src/
│  ├─ main.ts                     # web entrypoint (HTTP server)
│  ├─ worker.ts                   # worker entrypoint (SQS consumer) — SAME image
│  ├─ notes/                      # a module: controller → service → repository
│  ├─ common/                     # guards (auth), pipes (validation), filters (errors)
│  └─ db.ts                       # the pool — one per container
├─ deploy/
│  ├─ task-def.web.json           # ECS task: the web service
│  └─ task-def.worker.json        # ECS task: the worker (same image, diff command)
├─ infra/                         # Terraform: cluster, services, ALB, RDS, IAM
└─ .github/workflows/
   └─ backend-pipeline.yml        # build → push ECR → migrate → update ECS

Containerize with a Dockerfile

A multi-stage build keeps the final image small — build with the full toolchain, ship only what runs:

# Build stage
FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:24-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/src/main"]

# Build stage — install deps into a venv
FROM python:3.13-slim AS builder
WORKDIR /app
RUN python -m venv /venv
ENV PATH="/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Production stage — copy only the venv + app
FROM python:3.13-slim
WORKDIR /app
COPY --from=builder /venv /venv
ENV PATH="/venv/bin:$PATH"
COPY . .
EXPOSE 3000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "3000"]

Run the whole stack locally

Docker Compose mirrors production dependencies (database, cache) on your machine:

docker compose up          # app + postgres + redis, wired together
# app now on http://localhost:3000

Push the image to ECR

aws ecr create-repository --repository-name notes-api

aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin <acct>.dkr.ecr.us-east-1.amazonaws.com

docker build -t notes-api .
docker tag notes-api:latest <acct>.dkr.ecr.us-east-1.amazonaws.com/notes-api:latest
docker push <acct>.dkr.ecr.us-east-1.amazonaws.com/notes-api:latest

Define the Fargate task & service

The task definition says what to run; the service keeps N copies alive behind the load balancer:

// task-definition.json (trimmed)
{
  "family": "notes-api",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "512", "memory": "1024",
  "containerDefinitions": [{
    "name": "notes-api",
    "image": "<acct>.dkr.ecr.us-east-1.amazonaws.com/notes-api:latest",
    "portMappings": [{ "containerPort": 3000 }],
    "environment": [
      { "name": "DATABASE_HOST", "value": "...rds.amazonaws.com" },
      { "name": "REDIS_HOST",    "value": "...cache.amazonaws.com" }
    ],
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": { "awslogs-group": "/ecs/notes-api", "awslogs-region": "us-east-1", "awslogs-stream-prefix": "ecs" }
    }
  }]
}

aws ecs register-task-definition --cli-input-json file://task-definition.json
# then create/update an ECS service (Fargate) attached to your ALB target group

Deploy from CI

A GitHub Actions pipeline builds the image, pushes it to ECR, and rolls the ECS service to the new image on every merge — exactly what jnet-transport-backend does:

# .github/workflows/backend-pipeline.yml (essence)
- run: |
    docker build -t $ECR_URI:$SHA .
    docker push $ECR_URI:$SHA
- run: |
    aws ecs update-service --cluster jnet --service notes-api \
      --force-new-deployment

The database connection

Unlike a per-request Lambda, a container is a long-lived process — so a normal connection pool, created once at startup and reused for the container's whole life, is exactly right. The thing to watch shifts from "reconnecting per request" to total connections across all tasks.

// src/db.ts — one pool per container, created at startup, reused for its lifetime
import { Pool } from 'pg';

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,                      // per container
});

# app/db.py — one engine/pool per container, created at import, reused for its life
import os
from sqlalchemy import create_engine

engine = create_engine(
    os.environ["DATABASE_URL"],
    pool_size=10,          # per container
    pool_pre_ping=True,
)

Secrets & config

The same image ships to every environment, so configuration comes from outside the image at run time. ECS injects it two ways in the task definition — environment for plain values, secrets for anything sensitive:

// task-def.web.json (container definition, trimmed)
"environment": [
  { "name": "NODE_ENV",   "value": "production" },
  { "name": "REDIS_HOST", "value": "...cache.amazonaws.com" }
],
"secrets": [
  { "name": "DATABASE_URL",
    "valueFrom": "arn:aws:secretsmanager:us-east-1:<acct>:secret:notes/db_url" },
  { "name": "JWT_SECRET",
    "valueFrom": "arn:aws:ssm:us-east-1:<acct>:parameter/notes/jwt_secret" }
]

• secrets[].valueFrom pulls from Secrets Manager or SSM Parameter Store and injects the value as an env var at container start — the plaintext never lives in the image, the task def, or your logs.
• The execution role needs secretsmanager:GetSecretValue / ssm:GetParameters for exactly those ARNs — least privilege, not a wildcard.
• Never bake secrets into the image or a committed .env — anyone who pulls the image would have them.

The request's user & organization context

Every request belongs to a signed-in user in an organization, and one org must never see another's data. Verify the token and resolve identity in one place — a NestJS guard (or Express middleware) — then scope every query by orgId. Never trust an id from the body.

// src/common/auth.guard.ts — verify the JWT, attach { userId, orgId }
@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(ctx: ExecutionContext) {
    const req = ctx.switchToHttp().getRequest();
    const token = req.headers.authorization?.replace('Bearer ', '');
    const claims = verifyJwt(token);            // throws 401 if invalid
    req.ctx = { userId: claims.sub, orgId: claims.org_id };
    return true;
  }
}

# app/deps.py — verify the JWT, return { user_id, org_id }
from fastapi import Header, HTTPException

def require_context(authorization: str = Header(default="")):
    token = authorization.removeprefix("Bearer ")
    try:
        claims = verify_jwt(token)              # raises on a bad token
    except Exception:
        raise HTTPException(status_code=401)
    return {"user_id": claims["sub"], "org_id": claims["org_id"]}

// notes.service.ts — scope by the resolved org, never anything from the body
listNotes(orgId: string) {
  return pool.query('select id, text from notes where org_id = $1', [orgId]);
}

# notes_service.py — scope by the resolved org, never anything from the body
def list_notes(org_id: str):
    with engine.connect() as conn:
        rows = conn.execute(
            text("select id, text from notes where org_id = :org"), {"org": org_id})
        return [dict(r._mapping) for r in rows]

A worker from the same image

A container shines at work Lambda finds awkward: long jobs, queue consumers, scheduled tasks. The pattern is one image, two entrypoints — the web service runs the HTTP server; a worker service runs the same image with a different command, consuming a queue. No second repo.

// src/worker.ts — long-running SQS consumer (its own ECS service)
import { pool } from './db';
const sqs = new SQSClient({});

while (true) {
  const { Messages } = await sqs.send(new ReceiveMessageCommand({
    QueueUrl: process.env.QUEUE_URL, WaitTimeSeconds: 20, MaxNumberOfMessages: 10,
  }));
  for (const m of Messages ?? []) {
    await handle(JSON.parse(m.Body));                 // idempotent
    await sqs.send(new DeleteMessageCommand({
      QueueUrl: process.env.QUEUE_URL, ReceiptHandle: m.ReceiptHandle }));
  }
}

# app/worker.py — long-running SQS consumer (its own ECS service)
import os, json, boto3
sqs = boto3.client("sqs")
QUEUE = os.environ["QUEUE_URL"]

while True:
    resp = sqs.receive_message(
        QueueUrl=QUEUE, WaitTimeSeconds=20, MaxNumberOfMessages=10)
    for m in resp.get("Messages", []):
        handle(json.loads(m["Body"]))                 # idempotent
        sqs.delete_message(
            QueueUrl=QUEUE, ReceiptHandle=m["ReceiptHandle"])

// task-def.worker.json — SAME image, different command
"image": "<acct>.dkr.ecr.../notes-api:latest",
"command": ["node", "dist/src/worker"]        // web uses dist/src/main

// task-def.worker.json — SAME image, different command
"image": "<acct>.dkr.ecr.../notes-api:latest",
"command": ["python", "-m", "app.worker"]     // web uses uvicorn app.main:app

A CLAUDE.md for the container service

# CLAUDE.md

## What this is
Containerized API (NestJS) on AWS ECS Fargate. Postgres (RDS) + Redis (ElastiCache).
One image, two entrypoints: web (dist/src/main) and worker (dist/src/worker).

## Structure
src/main.ts             # web entrypoint (HTTP)
src/worker.ts           # worker entrypoint (SQS consumer) — same image
src/<module>/           # controller → service → repository (data access here)
src/common/             # guards (auth), pipes (validation), filters (errors)
src/db.ts               # one pool per container
deploy/task-def.*.json  # ECS tasks (web + worker)   ·   infra/  # Terraform

## Commands
- Local:  docker compose up            (app+db+redis on :3000)
- Build:  docker build -t notes-api .
- Deploy: push to main → GitHub Actions builds, pushes ECR, migrates, updates ECS.

## Conventions
- Multi-stage Dockerfile; final image runs `node dist/src/main`, EXPOSE 3000. Region us-east-1.
- Infra (cluster, services, ALB, RDS, Redis) in Terraform — no console clicks.
- Controllers thin; data access in the repository/service; nothing bypasses it.

## Auth & multi-tenancy
- A guard verifies the JWT and attaches { userId, orgId }; never trust ids from the body.
- Scope every query by orgId — no route may leak another tenant's data.

## Database
- One pool per container (created at startup, reused). Keep max modest: used ≈ max × tasks.
- RDS Proxy / PgBouncer once task count grows. Migrations run in the pipeline, not at boot.

## Secrets & config
- environment[] for plain config; secrets[].valueFrom for Secrets Manager / SSM (injected at start).
- Never bake secrets into the image or commit .env. Execution role: GetSecretValue on those ARNs only.

## Background work
- Worker = same image, different command, its own ECS service; consumes SQS, autoscales on depth.
- Enqueue / publish (EventBridge) from web and return; worker retries. Handlers idempotent.

## Do not
- Don't run migrations at container boot (tasks race) or one-off prod tasks by hand.
- Don't commit .env or AWS keys.

## Verify
docker compose up and curl :3000; after deploy, check the ECS service + CloudWatch logs.

Adding the next service — same shape

Growth here has three moves, in increasing order of separation — reach for the lightest one that fits:

# 1. a new MODULE in the same image (most features)
src/orders/
  orders.controller.ts   // thin — delegates to the service
  orders.service.ts      // business logic
  orders.repository.ts   // data access, org-scoped

# 2. a new ECS SERVICE from the SAME image (a worker / cron)
task-def.orders-worker.json   "command": ["node","dist/src/orders-worker"]

# 3. a new MICROSERVICE (own repo, image, task-def) — same module shape

• New module = controller → service → repository — thin controller, reuse the auth guard and the shared pool. Nothing existing changes.
• Same image, different command for a worker or scheduled task — one build, many roles.
• Shared infra by reference (SSM), a least-privilege task role, and a health check per service.

Ask for a feature the way an engineer would

For a container service, a good prompt says what runs where — which container or service owns the work — pushes config to env/SSM, treats infra as reviewable IaC with least-privilege, and ends with a local run before any deploy:

> Add an email-sending background worker to this service:
  - It consumes jobs from an SQS queue — one message = one email.
    Don't poll the database.
  - Run it as its own ECS service from the SAME image with a
    different command (worker vs web), not a new repo.
  - Config via env vars / SSM — no secrets baked into the image.
  - Terraform: the queue, the worker service, autoscaling on queue
    depth, and a least-privilege IAM role that reads only that queue.
  - Add a container healthcheck and sensible CPU/memory limits.
  - Don't change the web service. Let me run web + worker + a local
    SQS with docker compose to test, then show the Terraform plan.

• Say what runs where — "its own ECS service from the same image, worker vs web command" is the container-native pattern, not a second codebase.
• Config via env/SSM — never bake secrets or endpoints into the image; the same image ships to every environment.
• Infra as reviewable IaC — the queue, service, autoscaling, and IAM role in Terraform, so the change is a diff you can read.
• Least-privilege by default — "reads only that queue" keeps the task role tight instead of wildcard permissions.
• Run it locally first — docker compose up the whole stack, then terraform plan — verify before you touch the cluster.

Let Claude Code help

Ask for the container Skills by name — and the AWS Agent Toolkit gives Claude Code live access to your AWS account:

> Containerize this NestJS app with a multi-stage Dockerfile, add a
  docker-compose for local postgres + redis, and give me a Terraform
  module for an ECS Fargate service behind an ALB, plus a GitHub
  Actions workflow that builds, pushes to ECR, and updates the service.