Skip to main content
Build container images for services defined in a Docker Compose file using your local Docker. Built images can optionally be pushed to cluster machines or external registries.

​
Usage

uc build [FLAGS] [SERVICE...]

​
Arguments

​
SERVICE
string[]
Names of specific services to build. If not specified, all services with a build section are built.

​
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
​
--check
Check the build configuration for services without building them.
​
--deps
Also build services declared as dependencies of the selected services.
​
-f, --file
string[]
One or more Compose files to build. Default: compose.yaml
​
-m, --machine
string[]
Machine names or IDs to push the built images to (requires --push). Can be specified multiple times or as a comma-separated list. Default is all machines or x-machines specified in the Compose file.
​
--no-cache
Do not use cache when building images.
​
-p, --profile
string[]
One or more Compose profiles to enable.
​
--pull
Always attempt to pull newer versions of base images before building.
​
--push
Upload the built images to cluster machines after building. Use --machine to specify which machines. Default is all machines.
​
--push-registry
Upload the built images to external registries (for example, Docker Hub) after building.

​
Examples

​
Build all services

uc build

​
Build specific services

uc build web api

​
Build and push to cluster

Push to all machines: 
uc build --push
Push to specific machines: 
uc build --push -m machine1,machine2

​
Build and push to external registry

uc build --push-registry

​
Build with build arguments

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

​
Build without cache

uc build --no-cache

​
Build with newer base images

uc build --pull

​
Build with dependencies

Build service and its dependencies: 
uc build web --deps

​
Check build configuration

Verify Dockerfiles without building: 
uc build --check

​
Compose File Example

A service with a build configuration: 
services:
  web:
    build:
      context: ./web
      dockerfile: Dockerfile
      args:
        NODE_VERSION: 20
    image: myapp-web:latest
Build this service: 
uc build web

​
Build Arguments

Pass build arguments to Dockerfiles: Dockerfile: 
ARG NODE_VERSION=18
FROM node:${NODE_VERSION}
Build command: 
uc build --build-arg NODE_VERSION=20

​
Pushing Images

​
Push to Cluster

After building, push images to cluster machines: 
uc build --push
This is useful before deploying: 
uc build --push
uc deploy

​
Push to Specific Machines

Push only to machines that will run the service: 
uc build --push -m web-server,api-server

​
Push to External Registry

Push to Docker Hub or other registries: 
uc build --push-registry
Make sure you’re logged in: 
docker login
uc build --push-registry

​
Build vs Deploy

  • uc build - Only builds images
  • uc deploy - Builds images AND deploys services
Use uc build when you want to build without deploying: 
uc build  # Build and test locally
# Test the images...
uc deploy # Deploy when ready
Use uc deploy for the full workflow: 
uc deploy  # Builds and deploys in one command

​
Build Output

Building services
[+] Building 12.3s
 => [web] building web
 => [api] building api
✓ Built image myapp-web:latest for service web
✓ Built image myapp-api:latest for service api
With --push: 
Building services
✓ Built image myapp-web:latest for service web

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

​
No Services to Build

If no services have a build section: 
uc build
Output: 
No services to build.
  • uc deploy - Build and deploy in one command
  • uc images - List images on cluster machines
  • uc run - Run a service from a pre-built image

Build docs developers (and LLMs) love

Get started for freeTalk to us