Docker Compose to production K8s migration path

Teams run Docker Compose on a single VPS because it works—until they need zero-downtime deploys, multiple environments, or an investor asks about Kubernetes in due diligence. Migration is not docker-compose up on a cluster; it is a sequence of boundaries you move one at a time.

DarDevOps uses this path on OVH and similar VPS-hosted stacks common in Tunisia and MENA before jumping to managed Kubernetes when traffic justifies cost.

When Compose is still enough

Stay on Compose if you have one environment, one operator, acceptable brief deploy blips, and no compliance requirement for pod-level isolation. Migrate when you need reproducible staging, horizontal scale of stateless tiers, or standardized secrets and ingress across services.

Phase 1 — Containerize correctly

1. Multi-stage Dockerfiles with pinned base images
2. Health checks matching real readiness, not just process up
3. Config via environment variables—no baked secrets
4. Compose file documents every service dependency explicitly

Phase 2 — Translate to Kubernetes primitives

Each Compose service becomes Deployment + Service. Volumes map to PersistentVolumeClaims with backup plan. depends_on becomes readiness probes and init containers—not sleep hacks.

1. Stateless first

   Move API and workers before Postgres unless you have DBA support for managed DB.

2. Ingress and TLS

   Replace host nginx patterns with Ingress + cert-manager or equivalent.

3. Secrets

   Migrate.env files to SealedSecrets or cloud secret manager—never ConfigMaps for passwords.

4. Observability

   Add metrics and logs before cutover so regressions are visible.

Phase 3 — Cutover without heroics

Blue/green or parallel run: DNS weighted shift, database migration strategy decided upfront (dump/restore vs logical replication). Rollback plan documented before switch—not improvised at 2 a.m.

Common TN scale-up mistakes

• Lift-and-shift without fixing health checks
• Running cluster on same VPS with no resource limits—OOM kills Postgres
• Skipping staging because we are small
• Giving CI cluster-admin to save time

DarDevLab teaches Kubernetes fundamentals before client migrations; DarDev Services executes migrations under statement-of-work with explicit rollback criteria.

Networking and storage decisions

Compose networks map to Kubernetes NetworkPolicies only when you need them—start permissive in staging, tighten after services are stable. Persistent data on VPS often means local-path or NFS provisioners; understand who backs up PVCs before you delete a Compose volume name.

Tunisia bandwidth to European registries is usually fine for image pulls; still mirror critical bases or pin digests so Docker Hub outages do not block deploys during business hours.

CI/CD alignment

GitLab CI jobs that ran docker compose on the VPS should become kubectl apply or helm upgrade with environment-specific values files. Keep the same promotion gates: feature branch to staging, tag or manual gate to production.

Resource requests and limits belong in manifests from day one—especially for Java and Node services that spike memory on cold start. Without limits, one OOM can evict Postgres on a small cluster.

When to stop and stay on Compose

If migration estimates exceed six months and traffic fits one machine, invest in Compose hygiene instead: watchtower or scripted pulls, proper backup sidecars, and a second VPS for staging. Not every Tunisian startup needs a control plane.

Investors sometimes ask about Kubernetes as maturity signal—you can answer with documented deploy process, tested backups, and staging parity without running etcd.

Document every service port, env var, and cron job before migration. Discovery spreadsheets prevent the classic lost sidecar script that only ran on the old host.

Post-migration operating model

Assign on-call rotation before cutover—not after first outage. kubectl access via RBAC groups mirroring who had SSH before. Break-glass cluster-admin stays with two seniors only.

Cost watch: managed control plane plus worker nodes can exceed two VPS instances; track monthly bill against revenue stage. Downgrade path back to Compose remains valid if product-market fit stalls.

DarDevLab students often implement migration checklists as capstone projects—supervised by Services mentors on real anonymized manifests.

Related reading: managed-vs-self-hosted-k8s-mena and gitlab-ci-kubernetes-pipeline when your Compose stack already has CI and you are ready for cluster promotion gates.

Migration success is measured in boring deploys—not demo day cluster dashboards.

Run load tests on staging cluster before DNS cutover; Compose on one CPU masked contention that appears only when scheduling multiple replicas.

Keep Compose compose.yml in repo as disaster recovery reference even after Kubernetes prod—operators revert faster with documented parallel path.

Tunisia and Maghreb teams often share one DevOps generalist; prioritize automation that reduces weekly toil over exotic service mesh features unused for years.

Schedule a migration readiness review with DarDev Services before purchasing cluster hardware or managed control plane contracts.

Version-pin every manifest in git tags matching application releases so rollback means redeploying a known YAML set, not improvising from memory.

Treat namespace per environment as mandatory—shared default namespace guarantees eventual production mistake.

Label every Deployment with app version and git sha for support tickets that actually resolve.