Skip to main content
Uncloud supports Docker Compose for deploying multi-container applications across your cluster. You can use familiar Docker Compose syntax with Uncloud-specific extensions for cluster features.

​
How it works

When you run uc deploy with a compose.yaml file, Uncloud:
  1. Parses your compose.yaml file
  2. Converts service definitions to Uncloud service specifications
  3. Plans volume creation and service deployments
  4. Executes the deployment plan across your cluster
# Deploy from compose.yaml in current directory
uc deploy

# Deploy from specific file
uc deploy -f myapp.yaml

# Force recreate all containers
uc deploy --force-recreate

​
Key differences from standard Docker Compose

While Uncloud aims for Docker Compose compatibility, there are important differences:

​
Cluster-wide deployment

Uncloud deploys services across multiple machines in your cluster, not just a single host. Services can scale across machines, and Uncloud handles placement automatically.

​
Networking

Uncloud uses a single cluster-wide network instead of project-specific networks. All containers can communicate directly using service names.
The networks section in compose.yaml is ignored. All services share the cluster network and can discover each other by name.

​
Service discovery

Services are automatically discoverable at <service-name> within the cluster. Uncloud runs a built-in DNS server that resolves service names to container IPs.

​
Volume placement

Volumes are machine-local in Uncloud. When you use named volumes, Uncloud ensures containers using the same volume run on the same machine.
For replicated services with volumes, all replicas will be placed on the same machine to access the shared volume.

​
Rolling updates

By default, uc deploy performs zero-downtime rolling updates. Uncloud compares your compose.yaml with the current deployment and only updates services that changed.

​
HTTPS ingress

Uncloud provides automatic HTTPS via Caddy reverse proxy using the x-ports extension. Standard Compose ports are limited to host mode.

​
Complete example

Here’s a complete compose.yaml showing common patterns: 
services:
  web:
    image: nginx:alpine
    x-ports:
      - myapp.example.com:80/https
    volumes:
      - web-data:/data
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    environment:
      - BACKEND_URL=http://api:8080
    deploy:
      replicas: 3
      update_config:
        order: start-first

  api:
    build: ./api
    environment:
      - DATABASE_URL=postgres://db:5432/myapp
    volumes:
      - api-logs:/var/log
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=secret
    # Database only runs on one machine
    deploy:
      replicas: 1

volumes:
  web-data:
  api-logs:
  db-data:

​
What’s supported

Uncloud supports most common Docker Compose features:
  • Service definitions (image, build, command, entrypoint)
  • Environment variables and env files
  • Volumes (named, bind mounts, tmpfs)
  • Configs (file-based and inline)
  • Resource limits (CPU, memory)
  • Health checks
  • Placement constraints via x-machines
  • Rolling updates configuration
For a complete support matrix, see the Support Matrix.

​
What’s not supported

Some Docker Compose features don’t apply to Uncloud’s cluster model:
  • Custom networks (all services use cluster network)
  • Container links (use service names instead)
  • Depends_on conditions (startup order only)
  • Secrets (use configs or environment variables)

​
Uncloud extensions

Uncloud adds several x- extensions for cluster-specific features:

​
x-ports

Publish HTTP/HTTPS services via Caddy or bind TCP/UDP ports to hosts: 
services:
  web:
    image: nginx
    x-ports:
      - example.com:80/https
      - 8080:80/http
      - 5432:5432/tcp@host
See Services - Ports for details.

​
x-caddy

Custom Caddy configuration for advanced routing: 
services:
  app:
    image: myapp
    x-caddy: |
      app.example.com {
        reverse_proxy {{ upstreams 8080 }}
      }

​
x-machines

Constrain where services can run: 
services:
  gpu-worker:
    image: ml-worker
    x-machines:
      - gpu-machine-1
      - gpu-machine-2
    deploy:
      replicas: 2
See Deploy - Placement for details.

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us