Migrating from Docker Compose to Codiac

Move from Docker Compose (great for development) to Codiac (production-ready Kubernetes) without learning Kubernetes internals. Codiac is built for platform teams who want production infrastructure to be repeatable and boring—so they can focus on architecture, security, and scale.

Developers deploy with guided CLI commands or Web UI clicks. No YAML. No kubectl. No Kubernetes training required. Platform teams still have full access when needed—but no longer have to use it for day-to-day operations.

Interactive CLI

The Codiac CLI guides you through each command interactively. You don't need to memorize flags—just run the command and answer the prompts.

Why Migrate from Docker Compose?

Docker Compose limitations Codiac solves:

• Single-server limitation: Compose runs on one machine. Codiac distributes across cluster.
• No high availability: If server crashes, everything goes down. Codiac provides multi-node HA.
• Manual scaling: Can't auto-scale based on traffic. Codiac offers horizontal pod autoscaling.
• No load balancing: Compose has basic networking. Codiac includes production load balancers.
• No rolling updates: Compose requires downtime for updates. Codiac enables zero-downtime deployments.
• Limited secrets management: Compose uses .env files. Codiac integrates with cloud secret stores.

When to migrate:

• ✅ You're outgrowing a single server
• ✅ You need high availability (99.9%+ uptime)
• ✅ You want auto-scaling based on traffic
• ✅ You need zero-downtime deployments
• ✅ You're ready for production-grade infrastructure

When to stick with Compose:

• ❌ Local development only (Compose is perfect for this!)
• ❌ Simple hobby projects
• ❌ Single-server is sufficient for your needs

Note: Many teams use both - Compose for local dev, Codiac for production.

---

Key Differences

Feature	Docker Compose	Codiac (Kubernetes)
Deployment target	Single server	Multi-node cluster
High availability	No (single point of failure)	Yes (multiple replicas, nodes)
Auto-scaling	Manual only	Automatic (HPA)
Load balancing	Basic Docker networking	Production load balancers + ingress
Rolling updates	Requires downtime	Zero-downtime rolling updates
Health checks	Basic restart policies	Advanced probes (liveness, readiness, startup)
Secrets	.env files	Cloud secret stores (AWS, Azure, GCP)
SSL/TLS	Manual (nginx reverse proxy)	Automatic (Let's Encrypt)
Networking	Docker bridge network	Kubernetes service mesh

---

Prerequisites (Get These Ready First)

Before you start, make sure you have:

Credential	Why You Need It
Cloud provider admin access	Create clusters, assign IPs, configure networking
Container registry credentials	Pull images (ACR, ECR, Docker Hub, etc.)
DNS control	Point subdomain to cluster ingress

With these ready, you eliminate the back-and-forth that typically delays migrations.

---

Migration Process

Step 1: Analyze Docker Compose Setup (15 minutes)

Example docker-compose.yml:

version: '3.8'

services:
  web:
    image: myregistry/my-web-app:1.0.0
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://db:5432/myapp
      REDIS_URL: redis://redis:6379
      LOG_LEVEL: info
    depends_on:
      - db
      - redis
    restart: always

  db:
    image: postgres:14
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: always

  redis:
    image: redis:7-alpine
    restart: always

volumes:
  postgres_data:

Map services to Codiac assets:

• web service → my-web-app asset
• db service → postgres asset
• redis service → redis asset

---

Step 2: Setup Codiac (30 minutes)

1. Install Codiac CLI:

# Requires Node.js v20.13.1+
npm install -g @codiac.io/codiac-cli

# Authenticate to Codiac
codiac login

# Authenticate to your cloud provider
codiac csp login

2. Connect to Kubernetes cluster:

Option A: Capture existing cluster

codiac cluster capture
# CLI guides you through provider, credentials, and cluster selection

Option B: Create new cluster

codiac cluster create
# CLI guides you through provider, region, and cluster configuration

3. Create cabinet (namespace):

codiac cabinet create
# CLI prompts for cabinet name and environment

---

Step 3: Migrate Services (5 min/service)

For each service in your docker-compose.yml, create a Codiac asset:

1. Create assets for each service:

codiac asset create
# CLI guides you through:
# - Container registry selection
# - Image name and tag
# - Port configuration
# - Ingress settings

Run this for each service: postgres, redis, my-web-app.

2. Configure each asset:

codiac config set
# CLI prompts for:
# - Scope (cabinet or asset level)
# - Configuration key
# - Value

For secrets (like database passwords):

Store secrets in your cloud provider's secret manager (AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager). Then reference them in your application using the cloud provider's SDK or Kubernetes CSI Secrets Store Driver.

3. Deploy your assets:

codiac asset deploy
# CLI prompts for asset, version, and target cabinet

4. Map your domain:

codiac host map
# CLI guides you through domain configuration (automatic HTTPS)

What you get:

• ✅ High availability (multiple replicas)
• ✅ Automatic load balancing
• ✅ SSL certificate (Let's Encrypt)
• ✅ Persistent database storage
• ✅ Secrets in cloud provider (not .env files)

---

Step 4: Enable Production Features (15-30 minutes)

1. Add health checks:

Configure probes in the Codiac web UI at app.codiac.io:

1. Navigate to your asset
2. Click the Probes tab
3. Add liveness, readiness, or startup probes
4. Configure HTTP path, port, and timing

2. Enable autoscaling:

Configure autoscaling in the Codiac web UI:

1. Navigate to your asset
2. Click the Scaling tab
3. Enable autoscaling and set:
   • Min replicas: 3
   • Max replicas: 20
   • CPU target: 70%

What this does:

• Automatically scales from 3 to 20 replicas based on CPU
• Handles traffic spikes without manual intervention
• Scales down during low traffic to save costs

---

Migrating Common Docker Compose Patterns

Pattern 1: Service Dependencies (depends_on)

Docker Compose:

services:
  web:
    depends_on:
      - db

Codiac:

# Deploy database first
codiac asset deploy
# Select postgres asset and prod-app cabinet

# Then deploy web app
codiac asset deploy
# Select my-web-app asset and prod-app cabinet

Pattern 2: Environment Variables

Docker Compose:

environment:
  DATABASE_URL: postgres://db:5432/myapp
  API_KEY: ${API_KEY}

Codiac:

# Non-secret config
codiac config set
# Select cabinet scope → prod-app → DATABASE_URL → postgres://postgres:5432/myapp

# Secrets: Store in AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager
# Then reference in your application using cloud provider SDK or CSI driver

Pattern 3: Volumes

Docker Compose:

volumes:
  - postgres_data:/var/lib/postgresql/data

Codiac:

Configure persistent volumes in the Codiac web UI at app.codiac.io:

1. Navigate to your asset (postgres)
2. Click the Volumes tab
3. Add a volume mount:
   • Path: /var/lib/postgresql/data
   • Size: 500Gi
   • Storage class: ssd

Pattern 4: Port Mapping

Docker Compose:

ports:
  - "8080:8080"

Codiac:

# Configure port during asset creation
codiac asset create
# Select image, then configure port 8080 when prompted

# Expose externally with hostname mapping
codiac host map
# CLI prompts for hostname and target asset

Pattern 5: Restart Policies

Docker Compose:

restart: always

Codiac:

• Automatic (Kubernetes restarts failed pods by default)
• Enhanced with health checks (probes)

---

Development vs Production

Best practice: Use both Docker Compose and Codiac

Local development (Docker Compose):

# docker-compose.dev.yml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - .:/app  # Live code reload
    environment:
      DATABASE_URL: postgres://db:5432/myapp
    depends_on:
      - db

  db:
    image: postgres:14
    environment:
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"  # Exposed for debugging

Production (Codiac):

# Deploy to production cluster
codiac asset deploy
# Select my-web-app and prod-app cabinet

Workflow:

1. Develop locally with docker-compose up
2. Build and push image
3. Deploy to Codiac with codiac asset deploy

---

Comparison: Before & After

Before (Docker Compose on single server)

# Deploy
docker-compose up -d

# Update (downtime required)
docker-compose pull
docker-compose down
docker-compose up -d

# Scaling (manual, limited by server)
docker-compose up -d --scale web=3

# If server crashes → Everything down

Limitations:

• ❌ Single point of failure
• ❌ Manual scaling
• ❌ Downtime during updates
• ❌ No load balancing
• ❌ No auto-scaling

After (Codiac on Kubernetes cluster)

# Deploy
codiac asset deploy
# CLI prompts for asset, version, and cabinet

# Update (zero downtime)
codiac asset deploy
# Select new version when prompted

# Auto-scaling: Configure in web UI at app.codiac.io
# Set min: 3, max: 20, CPU target: 70%

# If node crashes → Pods reschedule automatically

Benefits:

• ✅ High availability (multi-node)
• ✅ Automatic scaling
• ✅ Zero-downtime updates
• ✅ Built-in load balancing
• ✅ Self-healing (automatic recovery)

---

Real-World Migration Timeline

Most platform migrations take months. Codiac is different. With Docker Compose, you already have your services defined—migration is straightforward.

Sample Timeline: 5-Service Application

Step	Activity	Time
1	Install CLI & connect cluster	30 min
2	Create cabinet	5 min
3	Create assets (one per Compose service)	5 min/service
4	Configure environment variables	10-30 min
5	Set up ingress	10 min
6	Deploy & validate	15 min

Total for 5 services: ~2 hours

Migration by Application Size

Application Size	Timeline	Notes
3-5 services	2-4 hours	Single session
10-15 services	1 day	Includes testing
20+ services	2-3 days	Phased rollout recommended

Compare this to typical Kubernetes migrations that take 3-12 months.

Use Cluster Export for Existing K8s

If your Docker Compose app is already running on Kubernetes, use codiac cluster export to auto-generate asset definitions from your running workloads in 5 minutes.

---

Common Migration Questions

Q: Can I keep using docker-compose.yml for local development?

A: Absolutely! Many teams use Compose locally and Codiac for production. Best of both worlds.

Q: Do I need to learn Kubernetes?

A: No. Codiac abstracts Kubernetes complexity. You focus on applications, not infrastructure.

Q: What about docker-compose.override.yml?

A: Codiac's configuration hierarchy replaces overrides:

# Base config (enterprise level)
codiac config set
# Select enterprise scope → KEY → value

# Environment override
codiac config set
# Select environment scope → prod → KEY → override

Q: How do I handle build: . in docker-compose.yml?

A: Build images in CI/CD, push to registry, then deploy via Codiac:

# CI/CD builds and pushes
docker build -t myregistry/my-app:1.0.0 .
docker push myregistry/my-app:1.0.0

# Codiac deploys
codiac asset deploy
# CLI prompts for asset and version (1.0.0)

Q: What about Docker networks?

A: Codiac (Kubernetes) handles networking automatically. Services communicate by name:

# DATABASE_URL: postgres://postgres:5432/myapp
#                       ↑ service name (asset name)

---

Getting Help

• Contact Support for Docker Compose migration assistance
• Visit codiac.io to schedule hands-on workshop
• Join Discord for community help

---

Related Documentation

• Asset Management Guide
• Configuration Management
• File Stores & Volumes
• Probes (Health Checks)
• Autoscaling

---

Last updated: 2026-01-23