Skip to main content

When to Use uc build

Learn when to build images separately from deployment and when to let uc deploy handle it automatically.

The Default: uc deploy​

For most users, uc deploy is all you need:

uc deploy

This automatically:

  1. Builds images for services with build sections
  2. Pushes images to cluster machines
  3. Deploys containers

Use this when:

  • You're iterating quickly during development
  • You want the simplest workflow
  • You're deploying from your local machine

When to Use uc build​

Use uc build separately when you need more control over the build process.

1. Test Builds Without Deploying​

Verify your build works before deploying:

# Test the build
uc build

# If successful, deploy later
uc deploy --no-build

Use case: You changed your Dockerfile and want to ensure it builds successfully without affecting running services.

2. Build Once, Deploy Multiple Times​

Build the image once and deploy to different environments:

# Build the image
uc build

# Deploy to staging
uc deploy --no-build -m staging1

# Deploy to production (same image)
uc deploy --no-build -m prod1,prod2

Use case: Ensures staging and production run identical images.

3. CI/CD Pipelines​

Separate build and deploy stages in your pipeline:

# .github/workflows/deploy.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build images
        run: uc build --build-arg VERSION=${{ github.sha }}

      - name: Run tests
        run: docker run myapp:latest pytest

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: uc deploy --no-build --yes

Use case: Run tests on built images before deploying.

4. Build Specific Services​

Build only services that changed:

# Only rebuild the frontend
uc build frontend

# Deploy both frontend and API (API reuses cached image)
uc deploy frontend api --no-build

Use case: Multi-service apps where only some services changed.

5. Debug Build Issues​

Troubleshoot build problems in isolation:

# Build with verbose output
uc build --no-cache

# Check the built image
docker images

# Test the image locally
docker run -p 8000:8000 myapp:latest

Use case: Build is failing and you need to debug without affecting deployments.

6. Push to External Registry​

Build and push to Docker Hub or other registries:

# Build image
uc build

# Push to Docker Hub
uc build --push-registry

# Deploy from registry
uc deploy --no-build

Use case: Share images across teams or clusters.

7. Pre-warm Cluster with Images​

Push images to cluster machines without deploying:

# Build and push to all machines
uc build --push

# Deploy later (images already available)
uc deploy --no-build

Use case: Large images where you want to distribute them in advance.

Comparison Table​

ScenarioCommandWhy
Quick iterationuc deploySimplest workflow
Test builduc buildVerify build without deploying
CI/CD build stageuc buildSeparate build from deploy
Run tests on imageuc build then testTest before deploy
Deploy to multiple envsuc build then uc deploy per envSame image everywhere
Build specific servicesuc build serviceGranular control
Push to registryuc build --push-registryShare images externally

Build and Deploy Workflows​

Workflow 1: Integrated (Default)​

uc deploy

Flow:

Code → Build → Push → Deploy

Best for: Development, single deployments

Workflow 2: Separated​

uc build
uc deploy --no-build

Flow:

Code → Build
       ↓
       Push → Deploy

Best for: Testing builds, multiple deployments

Workflow 3: CI/CD​

# CI stage
uc build --build-arg VERSION=$CI_COMMIT

# Test stage
docker run myapp:latest npm test

# Deploy stage
uc build --push
uc deploy --no-build --yes

Flow:

Code → Build → Test → Push → Deploy

Best for: Production deployments, automated pipelines

Workflow 4: Registry-based​

# Build locally or in CI
uc build

# Push to registry
uc build --push-registry

# Deploy from registry (on any machine)
uc deploy --no-build

Flow:

Code → Build → Registry → Deploy

Best for: Team workflows, multiple clusters

What About --no-build?​

The --no-build flag tells uc deploy to skip the build step:

uc deploy --no-build

Use when:

  • Images were built separately with uc build
  • Using pre-built images only (no build sections)
  • Images were built externally

Behavior:

  • Deploys using existing images
  • Fails if images don't exist on cluster machines
  • Faster deployment (no build time)

What Gets Built?​

By default, uc build and uc deploy build all services with build sections:

services:
  frontend:
    build: ./frontend  # Built

  api:
    build: ./api  # Built

  db:
    image: postgres:16  # Not built (no build section)

Build specific services:

uc build frontend

Build with dependencies:

uc build api --deps

Common Patterns​

Pattern 1: Development Loop​

# Edit code
vim src/app.py

# Quick deploy (build included)
uc deploy

Pattern 2: Pre-deployment Testing​

# Build first
uc build

# Test locally
docker run myapp:latest npm test

# If tests pass, deploy
uc deploy --no-build

Pattern 3: Multi-environment​

# Build once
uc build --build-arg ENV=production

# Push to all machines
uc build --push

# Deploy to staging
uc deploy --no-build -m staging1

# Later, deploy to production
uc deploy --no-build -m prod1,prod2

Pattern 4: Selective Rebuilds​

# Only frontend changed
uc build frontend

# Deploy both (API reuses old image)
uc deploy --no-build

Decision Tree​

Need to deploy?
├─ Yes
│  ├─ Images built recently? → uc deploy --no-build
│  └─ Need fresh build? → uc deploy
└─ No (testing/CI)
   ├─ Just testing build? → uc build
   ├─ Running tests? → uc build → test → uc deploy --no-build
   └─ Pushing to registry? → uc build --push-registry

Next Steps​