---
title: Build, Deploy, and Infrastructure Commands
description: 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.

```bash
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`:

```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.

```bash
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.

```bash
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`:

```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>`.

```bash
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.

```bash
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`:

```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

```bash
forge infra <provider> <command> [flags]
```

| Provider | Alias | Description |
|----------|-------|-------------|
| `docker` | — | Docker Compose infrastructure |
| `k8s` | `kubernetes` | Kubernetes with Kustomize |
| `do` | `digitalocean` | DigitalOcean 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.

```bash
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:**

```yaml
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):**

```dockerfile
# 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`:**

```bash
# 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.

```bash
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.

```bash
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`.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

<Callout type="warn">
Forge Cloud is currently in preview. Some commands return stub data while the backend is being finalized.
</Callout>

### `forge cloud login`

Authenticate with Forge Cloud.

```bash
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.

```bash
forge cloud logout
```

### `forge cloud deploy`

Deploy services to Forge Cloud.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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:

```bash
# 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

```yaml
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

```yaml
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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

<Callout type="info">
For development server commands, see the [Development Commands](/docs/forge/forge/(cli)/development) documentation.
</Callout>