DocumentationForgeryExtensionsCLIChangelogRoadmapBlog

Build, Deploy, and Infrastructure Commands

Build applications, deploy to environments, manage infrastructure, and use Forge Cloud

Build, Deploy, and Infrastructure Commands

Forge provides a full suite of commands for building applications, deploying them to various platforms, generating infrastructure configuration, and managing Forge Cloud. These commands introspect your project automatically — discovering apps, detecting ports, and generating production-ready Dockerfiles, Compose files, and Kubernetes manifests.

Build Commands

forge build

Build applications for production or development.

forge build                         # Build all apps
forge build -a api-gateway          # Build specific app
forge build --platform=linux/amd64  # Cross-platform build
forge build --production            # Production build
forge build -o ./dist               # Custom output

Flags:

  • -a, --app — App to build (empty = all)
  • -p, --platform — Target platform (os/arch)
  • --production — Production build with optimizations
  • -o, --output — Output directory (default: ./bin)

Build Configuration in .forge.yaml:

build:
  output_dir: ./bin
  auto_discover: true        # Scan cmd/ for buildable apps
  ldflags: "-s -w"           # Strip debug info for smaller binaries
  tags:
    - production
  platforms:
    - os: linux
      arch: amd64
    - os: linux
      arch: arm64
    - os: darwin
      arch: arm64
  apps:                      # Optional: explicit app list
    - name: api-gateway
      cmd: ./cmd/api-gateway
      output: api-gateway
      dockerfile: docker/Dockerfile.api

Deploy Commands

forge deploy

Deploy an application — builds a Docker image, pushes to a registry, and deploys to Kubernetes.

forge deploy -a api-gateway -e staging -t v1.2.3
forge deploy -a auth-service -e production --tag=latest

Flags:

  • -a, --app — App to deploy (required)
  • -e, --env — Target environment (default: dev)
  • -t, --tag — Docker image tag (default: latest)

Workflow:

  1. Build Docker image → <registry>/<app>:<tag>
  2. Push to configured registry
  3. Deploy to Kubernetes using environment config

forge deploy docker

Build and push a Docker image without deploying.

forge deploy docker -a api-gateway -t v1.0.0
forge deploy docker -a auth-service --tag=latest

Flags:

  • -a, --app — App to build (required)
  • -t, --tag — Image tag (default: latest)

The image is tagged using the registry from your .forge.yaml:

deploy:
  registry: ghcr.io/myorg       # Docker registry prefix

Example Output:

Building Docker image for api-gateway...
  Image: ghcr.io/myorg/api-gateway:v1.0.0
  ✓ Image built
Pushing Docker image...
  Pushing: ghcr.io/myorg/api-gateway:v1.0.0
  ✓ Image pushed
✓ Docker image built and pushed!

forge deploy k8s (aliases: kubernetes)

Deploy to Kubernetes using manifests from deployments/kubernetes/overlays/<env>.

forge deploy k8s -e staging
forge deploy k8s -e production --namespace=prod
forge deploy kubernetes -e dev

Flags:

  • -e, --env — Environment (default: dev)
  • -n, --namespace — Kubernetes namespace (falls back to environment config, then default)

forge deploy status

Show deployment status for all apps.

forge deploy status
forge deploy status --env=production

Flags:

  • -e, --env — Environment (default: dev)

Example Output:

Deployment status for staging environment:

 App              Status      Replicas  Version  Updated
 api-gateway      ✓ Running   3/3       v1.2.3   2 hours ago
 auth-service     ✓ Running   2/2       v1.1.0   1 day ago
 worker-service   ⚠ Degraded  1/2       v0.9.0   3 days ago

Deploy Configuration

Configure deployment environments and platform-specific settings in .forge.yaml:

deploy:
  registry: ghcr.io/myorg

  environments:
    - name: dev
      namespace: dev
      variables:
        LOG_LEVEL: debug
    - name: staging
      namespace: staging
      cluster: staging-cluster
      variables:
        LOG_LEVEL: info
    - name: production
      namespace: prod
      cluster: prod-cluster
      region: us-east-1
      variables:
        LOG_LEVEL: warn

  # Platform-specific configs (used by forge infra)
  docker:
    build_context: .
    dockerfile: Dockerfile
    compose_file: docker-compose.yml
    network: forge-network
    volumes:
      pg-data: /var/lib/postgresql/data

  kubernetes:
    manifests: ./deployments/k8s
    namespace: default
    context: my-cluster
    registry: ghcr.io/myorg

  digitalocean:
    region: nyc1
    git_repo: myorg/myrepo
    git_branch: main
    deploy_on_push: true

  render:
    region: oregon
    git_repo: myorg/myrepo
    git_branch: main

Infrastructure Commands

The forge infra command generates and deploys infrastructure configuration for Docker, Kubernetes, DigitalOcean, and Render. It auto-introspects your project — discovering apps, detecting ports, and resolving database/cache dependencies.

Command Overview

forge infra <provider> <command> [flags]
ProviderAliasDescription
docker—Docker Compose infrastructure
k8skubernetesKubernetes with Kustomize
dodigitaloceanDigitalOcean App Platform
render—Render.com

Each provider supports two subcommands:

  • export — Generate config files to the deployments/<provider>/ directory.
  • deploy — Build and deploy (uses exported config if available, otherwise generates on-the-fly).

forge infra docker export

Export Docker Compose configuration, Dockerfiles, and environment files.

forge infra docker export                     # Export to deployments/docker/
forge infra docker export -o ./my-docker      # Custom output directory
forge infra docker export --force             # Overwrite existing files

Flags:

  • -o, --output — Output directory (default: deployments/docker/)
  • -f, --force — Overwrite existing files

Generated Files:

deployments/docker/
├── docker-compose.yml          # Base Compose config
├── docker-compose.dev.yml      # Dev environment overrides
├── docker-compose.prod.yml     # Prod environment overrides (3 replicas)
├── .env.example                # Environment variable template
├── Dockerfile.api-gateway      # Multi-stage Dockerfile per app
├── Dockerfile.auth-service
└── Dockerfile.worker

Generated docker-compose.yml example:

version: '3.8'

services:
  api-gateway:
    build:
      context: .
      dockerfile: Dockerfile.api-gateway
    ports:
      - "${API_GATEWAY_PORT:-8080}:8080"
    environment:
      - ENV=base
      - LOG_LEVEL=${LOG_LEVEL:-info}
    networks:
      - forge-network
    restart: unless-stopped

  auth-service:
    build:
      context: .
      dockerfile: Dockerfile.auth-service
    ports:
      - "${AUTH_SERVICE_PORT:-8080}:8080"
    environment:
      - ENV=base
      - LOG_LEVEL=${LOG_LEVEL:-info}
    networks:
      - forge-network
    restart: unless-stopped

networks:
  forge-network:
    driver: bridge

Generated Dockerfile.<app> example (multi-stage):

# Build stage
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main ./cmd/api-gateway

# Runtime stage
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/main .
EXPOSE 8080
CMD ["./main"]

Generated .env.example:

# Docker Compose Environment Variables
ENV=dev
LOG_LEVEL=info

# Service Ports
API_GATEWAY_PORT=8080
AUTH_SERVICE_PORT=8080

# Database (if needed)
DATABASE_URL=postgres://user:password@postgres:5432/dbname

# Redis (if needed)
REDIS_URL=redis://redis:6379

forge infra docker deploy

Build and deploy services using Docker Compose.

forge infra docker deploy                     # Deploy all services
forge infra docker deploy -s api-gateway      # Deploy specific service
forge infra docker deploy --env=prod          # Use prod overrides
forge infra docker deploy --build             # Force rebuild images

Flags:

  • -s, --service — Service to deploy (default: all)
  • -e, --env — Environment (default: dev)
  • -b, --build — Force rebuild images

Behavior:

  • If deployments/docker/ exists (from a previous export), those files are used directly.
  • Otherwise, configuration is generated on-the-fly in a temporary directory.
  • Dockerfiles are copied to the project root temporarily for correct build context, then cleaned up.

forge infra k8s export (aliases: kubernetes)

Export Kubernetes manifests using Kustomize overlays.

forge infra k8s export                        # Export to deployments/k8s/
forge infra k8s export -o ./k8s-manifests     # Custom output
forge infra k8s export --force

Flags:

  • -o, --output — Output directory (default: deployments/k8s/)
  • -f, --force — Overwrite existing files

Generated Structure:

deployments/k8s/
├── base/
│   ├── deployment.yaml        # Deployment per app (replicas, probes, resources)
│   ├── service.yaml           # ClusterIP Service per app
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml  # 1 replica, dev- prefix
    └── prod/
        └── kustomization.yaml  # 3 replicas, prod- prefix

forge infra k8s deploy

Deploy to Kubernetes using kubectl apply.

forge infra k8s deploy                        # Deploy all
forge infra k8s deploy -s api-gateway         # Deploy specific service
forge infra k8s deploy --env=prod --namespace=production
forge infra k8s deploy --dry-run              # Preview without applying

Flags:

  • -s, --service — Service to deploy (default: all)
  • -e, --env — Environment (default: dev)
  • -n, --namespace — Kubernetes namespace (default: default)
  • --dry-run — Preview changes without applying

Kustomize is used if available; otherwise falls back to raw kubectl apply -f.

forge infra do export (aliases: digitalocean)

Export DigitalOcean App Platform spec.

forge infra do export
forge infra do export -o ./do-config --force

Generated Files:

deployments/do/
├── app.yaml          # DO App Platform spec
├── .env.example
└── README.md

forge infra do deploy

Deploy to DigitalOcean App Platform.

forge infra do deploy
forge infra do deploy -s api-gateway --region=nyc1

Flags:

  • -s, --service — Service to deploy (default: all)
  • -e, --env — Environment (default: dev)
  • -r, --region — DigitalOcean region

forge infra render export

Export Render.com blueprint.

forge infra render export
forge infra render export -o ./render-config --force

Generated Files:

deployments/render/
├── render.yaml       # Render Blueprint spec
├── .env.example
└── README.md

forge infra render deploy

Deploy to Render.com.

forge infra render deploy
forge infra render deploy -s api-gateway

Flags:

  • -s, --service — Service to deploy (default: all)
  • -e, --env — Environment (default: dev)

Forge Cloud

Forge Cloud is the managed deployment platform for Forge applications. The forge cloud command provides a complete workflow for deploying, monitoring, scaling, and managing your services.

Forge Cloud is currently in preview. Some commands return stub data while the backend is being finalized.

forge cloud login

Authenticate with Forge Cloud.

forge cloud login                  # Open browser for OAuth login
forge cloud login --token=<TOKEN>  # Authenticate with API token

Flags:

  • -t, --token — API token (skip browser OAuth flow)

forge cloud logout

Log out from Forge Cloud and clear stored credentials.

forge cloud logout

forge cloud deploy

Deploy services to Forge Cloud.

forge cloud deploy                              # Deploy all services
forge cloud deploy -s api-gateway               # Deploy specific service
forge cloud deploy -s api-gateway -e prod       # Deploy to production
forge cloud deploy -s api-gateway -r us-east-1  # Specify region
forge cloud deploy --watch                      # Watch deployment progress

Flags:

  • -s, --service — Service to deploy (default: all, interactive selector shown)
  • -e, --env — Environment (default: dev)
  • -r, --region — Deployment region
  • -w, --watch — Watch deployment progress in real time

Workflow:

  1. Verifies authentication (prompts forge cloud login if needed)
  2. Discovers apps in the project
  3. Builds images, pushes to registry, and initiates deployment
  4. With --watch, streams deployment progress until healthy

forge cloud status

Show deployment status across services and environments.

forge cloud status                     # Dev environment status
forge cloud status --env=prod          # Production status
forge cloud status -s api-gateway      # Filter by service
forge cloud status --watch             # Live status updates

Flags:

  • -e, --env — Environment (default: dev)
  • -s, --service — Filter by service name
  • -w, --watch — Watch for status updates

Example Output:

☁️  Forge Cloud Status (prod environment)

 Service          Status      Instances  Version  Updated
 api-service      ✓ Running   3/3        v1.2.3   2 hours ago
 auth-service     ✓ Running   2/2        v1.1.0   1 day ago
 worker-service   ⚠ Degraded  1/2        v0.9.0   3 days ago

forge cloud logs

View service logs from Forge Cloud.

forge cloud logs -s api-service              # Last 100 lines
forge cloud logs -s api-service -f           # Follow (stream) logs
forge cloud logs -s api-service -n 500       # Last 500 lines
forge cloud logs -s api-service -e prod      # Production logs

Flags:

  • -s, --service — Service name (required)
  • -e, --env — Environment (default: dev)
  • -f, --follow — Follow log output (live stream)
  • -n, --tail — Number of lines to show (default: 100)

forge cloud rollback

Rollback a service to a previous deployment version.

forge cloud rollback -s api-service              # Rollback to previous version
forge cloud rollback -s api-service -v v1.1.0    # Rollback to specific version
forge cloud rollback -s api-service -e prod      # Rollback in production

Flags:

  • -s, --service — Service to rollback (required)
  • -e, --env — Environment (default: dev)
  • -v, --version — Target version (default: previous)

forge cloud scale

Scale service instances up or down.

forge cloud scale -s api-service -r 5           # Scale to 5 replicas
forge cloud scale -s api-service -r 1 -e prod   # Scale prod to 1

Flags:

  • -s, --service — Service to scale (required)
  • -e, --env — Environment (default: dev)
  • -r, --replicas — Number of replicas (default: 1, minimum: 1)

Docker Integration

Generated Dockerfiles

When exporting with forge infra docker export, Forge generates multi-stage Dockerfiles for each discovered app. The build stage compiles the Go binary with static linking, and the runtime stage uses a minimal Alpine image.

Docker Compose Workflow

A typical Docker-based development and deployment workflow:

# 1. Export Docker configuration
forge infra docker export

# 2. Review and customize generated files
vim deployments/docker/docker-compose.yml

# 3. Copy .env.example and fill in values
cp deployments/docker/.env.example deployments/docker/.env

# 4. Build and deploy locally
forge infra docker deploy --build

# 5. Or use docker compose directly
docker compose -f deployments/docker/docker-compose.yml up -d

# 6. View logs
docker compose -f deployments/docker/docker-compose.yml logs -f

# 7. Tear down
docker compose -f deployments/docker/docker-compose.yml down

CI/CD Integration

GitHub Actions

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Setup Go
      uses: actions/setup-go@v5
      with:
        go-version: '1.25'

    - name: Build
      run: forge build --production

    - name: Build and Push Docker
      run: forge deploy docker -a api-gateway -t ${{ github.sha }}

    - name: Deploy to Staging
      run: forge deploy k8s -e staging

GitLab CI

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - forge build --production
    - forge deploy docker -a api-gateway -t $CI_COMMIT_SHA

deploy_staging:
  stage: deploy
  script:
    - forge deploy k8s -e staging
  only:
    - develop

deploy_production:
  stage: deploy
  script:
    - forge deploy k8s -e production
  only:
    - main

Troubleshooting

Build Failures

# Check for syntax errors
forge build -a api-gateway

# Check dependencies
go mod tidy

# Build with verbose output
forge build -a api-gateway --verbose

Docker Build Issues

# Test Docker build manually
docker build -t api-gateway .

# Check Docker daemon
docker info

# Check if Docker is available (forge does this automatically)
which docker && docker info

Kubernetes Deployment Issues

# Check cluster connection
kubectl cluster-info

# Check namespace
kubectl get namespaces

# Check deployment status
kubectl get deployments -n staging

# View pod logs
kubectl logs -f deployment/api-gateway -n staging

Infrastructure Export Issues

# Export already exists (use --force to overwrite)
forge infra docker export --force

# No apps found
forge dev list   # Check if apps are discoverable

For development server commands, see the Development Commands documentation.

How is this guide?

Database Commands

Database migration tools including SQL and Go migrations, app-scoped migrations, and migration management

Extension Commands

Manage Forge extensions and their configurations

On this page

Build, Deploy, and Infrastructure Commands
Build Commands
forge build
Deploy Commands
forge deploy
forge deploy docker
forge deploy k8s (aliases: kubernetes)
forge deploy status
Deploy Configuration
Infrastructure Commands
Command Overview
forge infra docker export
forge infra docker deploy
forge infra k8s export (aliases: kubernetes)
forge infra k8s deploy
forge infra do export (aliases: digitalocean)
forge infra do deploy
forge infra render export
forge infra render deploy
Forge Cloud
forge cloud login
forge cloud logout
forge cloud deploy
forge cloud status
forge cloud logs
forge cloud rollback
forge cloud scale
Docker Integration
Generated Dockerfiles
Docker Compose Workflow
CI/CD Integration
GitHub Actions
GitLab CI
Troubleshooting
Build Failures
Docker Build Issues
Kubernetes Deployment Issues
Infrastructure Export Issues