Overview

What is porter.yaml?

porter.yaml is a configuration file that defines how your application should be built and deployed on Porter. It serves as a single source of truth for your application’s infrastructure, enabling version-controlled, repeatable deployments.

Think of porter.yaml like a Dockerfile for your entire application stack - it declares your services, their resources, environment variables, and deployment settings in one place.

When to Use Configuration-as-Code

CI/CD Pipelines

Deploy your application automatically on every push using porter apply:

porter apply -f porter.yaml

Version-Controlled Infrastructure

Track infrastructure changes alongside your code. Every deployment configuration change goes through code review.

Preview Environments

Spin up isolated environments for pull requests with consistent configuration:

porter apply -f porter.yaml --preview

How It Works

1. Define Configuration

   Create a porter.yaml file in your repository that describes your application’s services, resources, and settings.

2. Run porter apply

   The Porter CLI reads your configuration and sends it to the Porter API.

3. Build (if configured)

   If a build section is defined, Porter builds and pushes your container image.

4. Deploy

   Porter deploys or updates your services according to the configuration.

Getting Started

1. Export Existing Configuration

If you already have an app deployed on Porter, export its current configuration:

porter app yaml my-app > porter.yaml

2. Create from Scratch

Start with a minimal configuration:

version: v2
name: my-app

services:
  - name: web
    type: web
    run: npm start
    port: 3000
    cpuCores: 0.5
    ramMegabytes: 512

build:
  method: docker
  context: .
  dockerfile: ./Dockerfile

3. Deploy

Apply the configuration to deploy your app:

porter apply -f porter.yaml

Example Configuration

This example demonstrates common configuration patterns:

version: v2
name: my-app

# Build configuration (or use 'image' for pre-built images)
build:
  method: docker
  context: .
  dockerfile: ./Dockerfile

# Environment variables
env:
  NODE_ENV: production
  LOG_LEVEL: info

# Attach shared environment groups
envGroups:
  - production-secrets
  - shared-config

# Pre-deploy job (runs before service deployment)
predeploy:
  run: npm run migrate

# Auto-rollback on failed deployments
autoRollback:
  enabled: true

# Service definitions
services:
  # Web service (publicly accessible)
  - name: api
    type: web
    run: npm start
    port: 8080
    cpuCores: 0.5
    ramMegabytes: 512
    autoscaling:
      enabled: true
      minInstances: 2
      maxInstances: 10
      cpuThresholdPercent: 70
    healthCheck:
      enabled: true
      httpPath: /health

  # Worker service (background processing)
  - name: worker
    type: worker
    run: npm run worker
    cpuCores: 0.25
    ramMegabytes: 256
    instances: 2

  # Scheduled job
  - name: cleanup
    type: job
    run: npm run cleanup
    cpuCores: 0.1
    ramMegabytes: 128
    cron: "0 0 * * *"  # Daily at midnight

Configuration vs Dashboard

When you deploy using porter apply, the configuration in porter.yaml takes precedence. Changes made in the Porter dashboard may be overwritten on the next deployment.

For consistent deployments, we recommend:

• Use porter.yaml as the source of truth for production
• Use the dashboard for experimentation and one-off changes
• Export dashboard changes with porter app yaml to update your configuration file

Next Steps

• Full Reference - Complete documentation of all configuration options
• Service Configuration - Detailed service type documentation
• porter apply Command - CLI reference for deployments
• Using Other CI Tools - Integrate with GitHub Actions, GitLab CI, etc.