Skip to content
Pilum

Quick Start

This guide walks you through deploying a service with Pilum. We’ll use GCP Cloud Run as an example, but the process is similar for any provider.

1. Initialize a Service

Use the interactive init command to generate a pilum.yaml:

Terminal window
pilum init

This walks you through:

  1. Selecting a provider (GCP, AWS, Homebrew, etc.)
  2. Selecting a service type (Cloud Run, Lambda, etc.)
  3. Filling in required and optional fields
  4. Choosing a build language (Go, Python, Rust, Node)

2. Or Create Manually

Create a pilum.yaml in your project directory:

name: my-api
provider: gcp
project: my-gcp-project
region: us-central1


build:
  language: go
  version: "1.23"
  env_vars:
    CGO_ENABLED: "0"
  flags:
    ldflags:
      - "-s"
      - "-w"

3. Validate Configuration

Ensure your service is configured correctly:

Terminal window
pilum check

This validates your pilum.yaml against the recipe’s required fields. If anything is missing, you’ll see a helpful error message.

4. Preview the Deployment

See what commands would run without actually executing them:

Terminal window
pilum dry-run --tag=v1.0.0

Output:

my-api: build binary
  [go build -ldflags "-s -w" -o ./dist/my-api .]


my-api: build docker image
  [docker build -t us-central1-docker.pkg.dev/my-gcp-project/my-api:v1.0.0 .]


my-api: push to registry
  [docker push us-central1-docker.pkg.dev/my-gcp-project/my-api:v1.0.0]


my-api: deploy to cloud run
  [gcloud run deploy my-api --image us-central1-docker.pkg.dev/my-gcp-project/my-api:v1.0.0 ...]

5. Deploy

When you’re ready, deploy for real:

Terminal window
pilum deploy --tag=v1.0.0

You’ll see real-time progress:

Step 1: build binary
  my-api  ✓ (1.2s)


Step 2: build docker image
  my-api  ✓ (15.3s)


Step 3: push to registry
  my-api  ✓ (8.7s)


Step 4: deploy to cloud run
  my-api  ✓ (12.1s)


Deployment complete! 4 steps, 1 service, 37.3s total

Common Commands

Terminal window
# Deploy all services
pilum deploy --tag=v1.0.0


# Deploy specific service
pilum deploy my-api --tag=v1.0.0


# Build only (skip push and deploy)
pilum build --tag=v1.0.0


# Build and push images (skip deploy)
pilum publish --tag=v1.0.0


# Run only deploy steps (assumes images exist)
pilum deploy --only-tags=deploy --tag=v1.0.0


# List discovered services
pilum list

Project Structure

A typical Pilum project looks like this:

my-project/
├── .pilumignore                  # Optional: custom ignore file
├── services/
│   ├── api/
│   │   ├── pilum.yaml            # Service configuration
│   │   ├── main.go
│   │   └── Dockerfile
│   └── worker/
│       ├── pilum.yaml
│       ├── main.go
│       └── Dockerfile

Next Steps