Docs / Configuration

Configuration Reference

Full pier.yml specification. Everything you can configure per service.

pier.yml (full spec)

# Project name (defaults to directory name)
name: myapp

services:
  api:
    # Source: image or build path (one required)
    image: node:20-alpine
    build: ./api             # Path to Dockerfile

    # Networking
    port: 3000               # Container port
    domain: api.myapp.dock   # Local HTTPS domain
    expose: [3000, 9229]     # Additional exposed ports

    # Health
    health: /api/health      # HTTP health endpoint
    health_interval: 10s     # Check interval (default: 10s)
    health_timeout: 5s       # Timeout per check (default: 5s)
    health_retries: 3        # Retries before unhealthy

    # Dependencies
    depends_on: [db, redis]  # Wait for these to be healthy

    # Environment
    env:
      NODE_ENV: development
      DATABASE_URL: postgres://db:5432/myapp
    env_file: .env.local     # Load from file

    # Volumes
    volumes:
      - ./api/src:/app/src   # Bind mount (dev)
      - node_modules:/app/node_modules  # Named volume

    # Resources
    cpu: 2                   # CPU cores limit
    memory: 1024             # Memory MB limit

    # Lifecycle
    command: npm run dev     # Override default CMD
    entrypoint: /bin/sh      # Override ENTRYPOINT
    restart: unless-stopped  # Restart policy

    # Labels (for reverse proxy, monitoring)
    labels:
      tier: backend
      team: payments

Key Concepts

Domains & HTTPS

Any *.dock domain gets automatic HTTPS via mkcert (local CA). In production, set real domains and Pier uses Let's Encrypt. The reverse proxy (Caddy) handles TLS termination automatically.

Health Checks

When a service has a health endpoint, Pier polls it before marking the service as ready. Services listed in depends_on wait for their dependencies to be healthy. This eliminates race conditions on startup.

Volumes

Two types: bind mounts (./src:/app/src) for local development, and named volumes (pg_data:/var/lib/data) for persistent data. Named volumes survive pier down. Use pier volumes prune to clean up.

Secrets

Use pier secrets set KEY to encrypt a value. Reference it in pier.yml with ${SECRET:KEY}. Secrets are decrypted at runtime and injected as environment variables. The encrypted file (.env.pier) is safe to commit.

Environment Precedence

Priority: CLI flags > env_file > env block > .env in project root. For secrets: ${SECRET:KEY} resolves from .env.pier. For external values: ${ENV:KEY} reads from host environment.

Next: Deployment