Skip to content

AWS ECS Runtime Inventory

Purpose

This document records the current Docker Compose runtime in a form that can be translated into ECS task definitions and service discovery later.

It is intentionally descriptive, not prescriptive. The goal is to capture what exists today so we can migrate one service at a time without losing track of:

  • runtime dependencies
  • exposed ports
  • persistent state
  • service startup ordering
  • configuration sources
  • ECS-specific risks

Scope

This inventory is based on:

  • compose.yml
  • Terraform ECS definitions

Root Web Stack

Development Stack

Service Purpose Ports Depends On Mounts Notes
frontend-dev React frontend in dev mode 3100:3000 dev ./tracker-frontend:/app, ./openapi.json:/app/openapi.json:ro Uses tracker-frontend/.env.example and runs as root
dev FastAPI app in dev mode 8100:8000, 5678:5678 db, dragonfly .:/app Reads PostgreSQL, Redis, and JWT config from env vars
admin-dev Admin panel in dev mode 3000:3000 dev ./tracker-admin:/app Uses tracker-admin/.env and runs as root
redoc Regenerates ReDoc site none none .:/app One-off docs build container
docs MkDocs site 8001:3000 none .:/docs Documentation server
db PostgreSQL with extensions 5432, 5433 none postgres_data:/var/lib/postgresql/data Current local database
pgbouncer Connection pooler 6432 db ./pgbouncer/userlist.txt:/etc/pgbouncer/userlist.txt Local pooler only
dragonfly Redis-compatible cache/queue 6379 none dragonfly_data:/data Requires REDIS_PASSWORD

Production Stack

Production is modeled in Terraform and ECS task definitions rather than Compose.

Worker Stack

Development Stack

Service Purpose Ports Depends On Mounts Notes
tracker-fetcher-2-dev Tracker fetcher API in dev mode 8080:8080 none ./data:/data, ../..:/app, ../data/account.json:/data/account.json:rw Includes live reload
tracker-fetcher-2-worker-dev Tracker fetcher worker none none same as above Background worker
unified-geofence-dev Unified geofence API in dev mode 8082:8082 none same as above Includes live reload
unified-geofence-worker-dev Unified geofence worker none none same as above Background worker
notification-service-dev Notification listener none unified-geofence-dev same as above Listens for DB notifications
materialized-view-service-dev Materialized view refresher none none same as above No special port exposure

Production Stack

Production worker services are defined in Terraform and ECS, not Compose.

Shared Dependencies

Application Configuration

These services currently rely on environment variables rather than hard-coded config:

  • POSTGRES_SERVER
  • POSTGRES_PORT
  • POSTGRES_DB
  • POSTGRES_USER
  • POSTGRES_PASSWORD
  • SECRET_KEY
  • REDIS_HOST
  • REDIS_PORT
  • REDIS_USERNAME
  • REDIS_PASSWORD
  • REDIS_CLUSTER_MODE
  • REDIS_CACHE_TTL
  • REDIS_TLS_ENABLED
  • REDIS_TLS_CERT_REQS
  • REDIS_TLS_CA_CERTS_FILE
  • REDIS_TLS_CERTFILE
  • REDIS_TLS_KEYFILE
  • REDIS_CACHE_DB
  • REDIS_TASKS_DB
  • REDIS_HEALTH_DB
  • REDIS_NOTIFICATIONS_DB

Service-Specific Configuration

  • EXTERNAL_BASE_URL for the API
  • API_URL for the admin panel
  • DEBUG_WAIT_FOR_CLIENT for the dev API
  • ANISETTE_SERVER for the TaskiQ services
  • FETCH_INTERVAL and MAX_KEYS_PER_BATCH for tracker fetching
  • LOCATION_REPORT_POLLING_INTERVAL
  • GEOFENCE_PROCESSING_INTERVAL
  • GEOCODING_BATCH_SIZE
  • GEOCODING_MAX_API_CALLS
  • GEOCODING_MAX_TOTAL_LOCATIONS
  • MATERIALIZED_VIEW_REFRESH_HOURS
  • MAX_MATERIALIZED_VIEW_AGE_HOURS

Persistent State

  • postgres_data volume stores the local database
  • dragonfly_data volume stores local cache/queue state
  • services/data/account.json is a mounted credential file for the worker stack

Runtime Relationships

Current Docker DNS Names

The application currently uses Docker service names as runtime endpoints:

  • db
  • dragonfly
  • dev
  • api
  • admin
  • frontend

These names matter because the app is configured by environment variables that default to them. In ECS, these will likely become:

  • ECS Service Connect names
  • Cloud Map DNS names
  • ALB DNS names for externally exposed services

Localhost Coupling

Some containers currently rely on localhost only within a single task/container boundary. In ECS that only works if containers are in the same task definition. Otherwise, the target must become a DNS name or load balancer address.

ECS Migration Notes

Lowest-Risk Migration Order

  1. API
  2. Frontend/Admin
  3. Worker services
  4. Documentation and utility containers
  5. Shared infrastructure replacement

Immediate ECS Questions

  • Should API and frontend stay in separate ECS services or be grouped into one task?
  • Should the worker stack use one task per service or a shared task definition for related services?
  • Should the database move to RDS before or after the application migration?
  • Should Redis move to ElastiCache before or after the application migration?
  • Do we keep docs and redoc in ECS, or generate them in CI and publish statically?

Known ECS Risks

  • Local bind mounts do not translate directly to ECS.
  • The services/data/account.json mount needs a secure replacement.
  • The extra_hosts compatibility shim on api is Docker-specific and should be removed for ECS.
  • Replica support in Compose does not apply; ECS scaling is defined in Terraform.

Next Reference Documents