Opscraft
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 diagramserviceDeployment + ServiceportsService + Ingressnamed volumePersistentVolumeClaimhealthcheckliveness and readiness probesdepends_onno equivalent: readiness + retries
Figure 1. Moving from Compose to Kubernetes: most ideas have a direct equivalent; depends_on does not.
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