Docker Compose · Lesson 9 of 10 · 3 min read
Production use, Kubernetes migration and troubleshooting
Is Compose OK in production?
Reasonable for small, single-host applications: internal tools, a small VPS app, edge devices. Make it production-worthy with pinned image tags (or digests), restart: unless-stopped, health checks, resource limits, log rotation, backups of volumes, a reverse proxy with TLS, monitoring, and deployment through CI (docker compose pull && up -d over SSM/SSH).
Its limits: one host means no high availability, no rolling updates across nodes, no autoscaling, no self-healing across machine failure. Beyond that, move to Swarm (compose-format stacks, simple) or — the usual answer — Kubernetes/ECS.
Mapping Compose to Kubernetes
| Compose | Kubernetes |
|---|---|
| service | Deployment (or StatefulSet) + Service |
ports |
Service (ClusterIP/LoadBalancer) + Ingress |
| service-name DNS | Service DNS (api.namespace.svc.cluster.local) |
environment / env_file |
ConfigMap / env |
secrets |
Secret (or External Secrets) |
| named volume | PersistentVolumeClaim |
healthcheck |
liveness/readiness/startup probes |
depends_on |
No equivalent — readiness probes, init containers, retries |
deploy.resources |
requests/limits |
profiles |
Separate manifests / Kustomize overlays |
Kompose converts compose files to manifests as a starting point; in practice you'd hand-tune them into Kustomize bases and overlays or a Helm chart.
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
API can't connect to localhost:5432 |
Use the service name db |
| API crashes on startup, DB fine a minute later | Readiness race — add a DB healthcheck + condition: service_healthy, add retries |
| Changed code, nothing changes | Image not rebuilt — up --build; or the bind mount isn't where you think (docker compose config) |
| Changed seed SQL, DB unchanged | Volume already initialised — down -v to reseed |
| Wrong variable value | docker compose config to see interpolation; check shell env overriding .env |
port is already allocated |
Another project/process on that host port — change it or stop the other; parameterise host ports per developer |
| Containers from an old project still running | Different project name; docker compose -p old down |
| Two teammates' stacks collide on a shared host | Different project names / host ports |
network ... not found |
External network not created yet |
| Slow file sync on Mac | Bind mount over the VM boundary — compose watch or synchronized shares |