Skip to main content
Deploy services from a Docker Compose file to your cluster. This command builds images (if needed), pushes them to cluster machines, and deploys or updates services with zero downtime.

​
Usage

uc deploy [FLAGS] [SERVICE...]

​
Arguments

​
SERVICE
string[]
Names of specific services to deploy. If not specified, all services in the Compose file are deployed. Dependencies are automatically included.

​
Flags

​
--build-arg
string[]
Set a build-time variable for services. Used in Dockerfiles that declare the variable with ARG. Can be specified multiple times.Format: --build-arg VAR=VALUE
​
--build-pull
Always attempt to pull newer versions of base images before building service images.
​
-f, --file
string[]
One or more Compose files to deploy services from. Default: compose.yaml
​
--no-build
Do not build new images before deploying services.
​
--no-cache
Do not use cache when building images.
​
-p, --profile
string[]
One or more Compose profiles to enable.
​
--recreate
Recreate containers even if their configuration and image haven’t changed.
​
--skip-health
Skip the monitoring period and health checks after starting new containers. Useful for faster emergency deployments.Warning: This may cause downtime if new containers fail to start properly.
​
-y, --yes
Auto-confirm deployment plan. Should be explicitly set when running non-interactively, for example, in CI/CD pipelines.Can also be set with the UNCLOUD_AUTO_CONFIRM environment variable.

​
Examples

​
Deploy all services

uc deploy

​
Deploy specific services

uc deploy web api

​
Deploy with a custom Compose file

uc deploy -f docker-compose.prod.yaml

​
Deploy with multiple Compose files

uc deploy -f compose.yaml -f compose.override.yaml

​
Deploy with build arguments

uc deploy --build-arg NODE_VERSION=20 --build-arg ENV=production

​
Deploy without using build cache

uc deploy --no-cache

​
Deploy with auto-confirm (for CI/CD)

uc deploy -y

​
Deploy and recreate all containers

uc deploy --recreate

​
Workflow

  1. Load Compose file - Parses compose.yaml (or specified file)
  2. Build images - Builds images for services with build configuration
  3. Push images - Pushes built images to cluster machines
  4. Create deployment plan - Analyzes what needs to change
  5. Show plan - Displays the deployment plan for review
  6. Confirm - Asks for confirmation (unless --yes is used)
  7. Execute deployment - Performs rolling updates with zero downtime

​
Deployment Plan

Before deploying, you’ll see a plan showing what will change: 
Deployment plan
- Deploy service [name=web]
  + Create container on machine vps1
  ~ Update container on machine vps2
    - image: myapp:v1
    + image: myapp:v2
- Deploy service [name=api]
  = Service is up to date

Do you want to continue? (y/N)
Symbols:
  • + Create new resource
  • ~ Update existing resource
  • - Remove resource
  • = No changes

​
Output

Building services
✓ Built image myapp:latest for service web

Pushing image myapp:latest to cluster
✓ Pushed to machine vps1
✓ Pushed to machine vps2

Deployment plan
- Deploy service [name=web]
  ~ Update container on machine vps1
    - image: myapp:v1
    + image: myapp:v2
  ~ Update container on machine vps2
    - image: myapp:v1
    + image: myapp:v2

Do you want to continue? (y/N) y

Deploying services
✓ web deployment complete

​
Compose File Extensions

Uncloud supports these Docker Compose extensions:

​
x-machines

Limit service to specific machines: 
services:
  web:
    image: nginx
    x-machines:
      - machine1
      - machine2

​
Deploy Configuration

Control service deployment: 
services:
  web:
    image: nginx
    deploy:
      mode: replicated
      replicas: 3
      resources:
        limits:
          cpus: '2'
          memory: 4G

​
Zero-Downtime Deployments

By default, Uncloud performs rolling updates:
  1. Starts new containers with the new version
  2. Waits for health checks to pass
  3. Updates load balancer to route to new containers
  4. Stops old containers
This ensures your service stays available during deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us