Deploy Docker Compose Projects

The cpln stack command deploys Docker Compose projects directly to Control Plane, automatically converting services, volumes, secrets, and networks to their Control Plane equivalents.

When to use this

Migrate from Docker Compose

Move existing Compose projects to Control Plane without rewriting configuration

Local-to-cloud workflow

Develop locally with Compose, deploy to Control Plane for production

Multi-service apps

Deploy interconnected services as a cohesive stack

Preview deployments

Generate and inspect Control Plane manifests before deploying

Prerequisites

CLI installed

Install the Control Plane CLI. See Installation.

Docker Compose project

You need a docker-compose.yml or compose.yaml file.

Required permissions

You need permissions to create workloads, secrets, volumesets, identities, and push images.

Deploy a project

cpln stack deploy

This reads your Compose file and deploys all services to Control Plane. See the stack deploy command reference for all options.

Delete a project

Remove all resources created by a Compose deployment:

cpln stack rm

See the stack rm command reference for details.

Preview the generated manifests

Generate Control Plane specs without deploying:

cpln stack manifest

This outputs the converted YAML so you can inspect or modify it before deployment.

Customize workloads with x-cpln

Add an x-cpln block to any service to override the generated workload spec. Each top-level key in x-cpln replaces the corresponding section in the workload spec:

docker-compose.yml

services:
  api:
    image: ghcr.io/example/api:1.2.3
    ports:
      - '8080:8080'

    x-cpln:
      type: standard                    # Override workload type
      containers:                        # Replace entire containers array
        - name: api
          cpu: 250m
          memory: 256Mi
      defaultOptions:                    # Replace defaultOptions
        capacityAI: false
        autoscaling:
          minScale: 0
          maxScale: 3
          metric: concurrency
          target: 50
      firewallConfig:                    # Replace firewallConfig
        external:
          inboundAllowCIDR:
            - 0.0.0.0/0
        internal:
          inboundAllowType: same-gvc

The x-cpln block replaces entire spec sections, and doesn’t merge them. If you override containers, you must include all container configuration.

Available overrides

Key	Description
`type`	Workload type: `serverless`, `standard`, `stateful`
`containers`	Complete container specifications
`defaultOptions`	Autoscaling, capacity AI, timeouts, suspend
`firewallConfig`	External and internal firewall rules
`identityLink`	Link to a specific identity
`supportDynamicTags`	Enable dynamic image tag detection
`loadBalancer`	Load balancer configuration
`rolloutOptions`	Deployment rollout strategy
`securityOptions`	Security context settings
`localOptions`	Location-specific overrides

Service-to-service communication

Update service URLs to use the Control Plane local syntax:

- http://service2:8080
+ http://service2.{GVC}.cpln.local:8080

Replace {GVC} with your actual GVC name.

See the Service-to-Service guide for the full endpoint syntax.

How workload type is determined

The converter analyzes your service definition to select the appropriate workload type:

Condition	Workload Type
Service has volumes attached	`stateful`
No volumes attached	`standard`

Use x-cpln to override the automatically determined type if needed.

Translation reference

Compose Feature	Control Plane Resource
Services	Single-container workloads
Networks	Internal firewall configuration
Named volumes	Volumesets (10GB, ext4, general-purpose-ssd)
Secrets	Opaque secrets + policies + identities
Configs	Opaque secrets (treated identically to secrets)
File bind mounts	Opaque secrets

Resource mapping

Compose Field	Control Plane Equivalent
`deploy.resources.limits.cpus`	Container CPU (multiplied by 1000 for millicores)
`deploy.resources.limits.memory`	Container memory
`deploy.replicas`	`minScale` and `maxScale` (set to same value)
`healthcheck`	Readiness probe
`ports` / `expose`	Container ports
`environment` / `env_file`	Environment variables (`environment` processed first; `env_file` entries added only for keys not already defined)
`working_dir`	Container working directory
`command`	Container args
`entrypoint`	Container command

Port protocol

Specify the protocol directly in the port string:

ports:
  - "8080:80/http"      # HTTP protocol
  - "50051:50051/grpc"  # gRPC protocol
  - "9000:9000/http2"   # HTTP/2 protocol
  - "5432:5432/tcp"     # TCP protocol
  - "3000:3000"         # No protocol set if not specified

Defaults

Property	Default Value
CPU	`42m`
Memory	`128Mi`
External inbound	Allowed if `ports` defined or `network_mode: host`
External outbound	Allowed (unless `network_mode: none`)
Capacity AI	Enabled only if: reservations < limits, no GPU, and not stateful

Secrets and configs

Both secrets and configs are converted to Control Plane secrets:

services:
  api:
    image: myapp:latest
    secrets:
      - db_password           # Simple reference
      - source: api_key       # With custom target path
        target: /app/api.key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    file: ./secrets/api_key.txt

Default mount path: /run/secrets/{name} (if no absolute path specified)
Identities and policies are automatically created for workloads using secrets

Healthcheck conversion

Docker healthchecks are converted to readiness probes:

Compose Field	Control Plane Field
`test`	`exec.command`
`interval`	`periodSeconds`
`timeout`	`timeoutSeconds`
`start_period`	`initialDelaySeconds`
`retries`	`failureThreshold`

Supported test formats:

String: "curl http://localhost/health" → /bin/sh -c wrapper
CMD: ['CMD', 'curl', 'http://localhost'] → direct execution
CMD-SHELL: ['CMD-SHELL', 'curl http://localhost'] → /bin/sh -c wrapper
NONE: Disables the readiness probe

Network modes

Mode	Behavior
Default (no networks)	All services can reach each other
Named networks	Only services in the same network can communicate
`network_mode: host`	External inbound traffic allowed
`network_mode: none`	No outbound traffic allowed
`network_mode: service:other`	Shares network with another service

GPU support

Services with GPU devices are automatically configured:

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ['gpu']
          count: 1

GPU workloads receive:

NVIDIA T4 GPU
Minimum CPU: 2000m (overrides default)
Minimum Memory: 7168Mi (overrides default)
Capacity AI: Disabled

Service inheritance

Extend services from the same or different compose files:

services:
  api:
    extends:
      service: base
      file: base-compose.yml
    environment:
      - API_KEY=secret  # Overrides parent

Child values take precedence over parent values.

Limitations

The following Docker Compose features are not supported:

Feature	Status	Alternative
Directory bind mounts	Not supported	Use named volumes or file bind mounts
`depends_on` ordering	Ignored	Services start independently; use health checks
`links`	Ignored	Use network-based service discovery
Dynamic GPU model/quantity	Limited	Hardcoded to NVIDIA T4, quantity 1
Multiple containers per service	Not supported	Create separate services
`privileged` mode	Not supported	Use `securityOptions` via x-cpln

Troubleshooting

Service-to-service connection fails

Update hostnames to use the Control Plane local syntax:

http://service-name.{GVC}.cpln.local:{port}

Ensure both services are in the same network or no networks are defined (global network).

Ports not accessible

Ensure all ports are explicitly listed in ports or expose in your Compose file. Only services with ports defined get external inbound access.

Secret not found

Secrets referenced in Compose are converted to Control Plane secrets. The converter automatically creates identities and policies. Check that:

The secret file exists at the specified path
You have permissions to create secrets, identities, and policies

Directory bind mount error

Directory bind mounts are not supported. Convert to either:

Named volumes (for persistent data)
File bind mounts (for configuration files → converted to secrets)

Both image and build specified

A service cannot have both image and build specified. Use one or the other:

image: Pull from a registry
build: Build and push to Control Plane registry

Services can't communicate

By default, all services can reach each other. If you’re using named networks, ensure communicating services are in the same network.

Next steps

Apply YAML Manifests

Deploy resources from YAML files

Service-to-Service

Configure internal networking

Workload Reference

Understand workload configuration

Stack Command Reference

Full stack command reference

​When to use this

Migrate from Docker Compose

Local-to-cloud workflow

Multi-service apps

Preview deployments

​Prerequisites

​Deploy a project

​Delete a project

​Preview the generated manifests

​Customize workloads with x-cpln

​Available overrides

​Service-to-service communication

​How workload type is determined

​Translation reference

​Resource mapping

​Port protocol

​Defaults

​Secrets and configs

​Healthcheck conversion

​Network modes

​GPU support

​Service inheritance

​Limitations

​Troubleshooting

​Next steps

Apply YAML Manifests

Service-to-Service

Workload Reference

Stack Command Reference

When to use this

Prerequisites

Deploy a project

Delete a project

Preview the generated manifests

Customize workloads with x-cpln

Available overrides

Service-to-service communication

How workload type is determined

Translation reference

Resource mapping

Port protocol

Defaults

Secrets and configs

Healthcheck conversion

Network modes

GPU support

Service inheritance

Limitations

Troubleshooting

Next steps