Porter — PaaS on Your Own Cloud

Overview

Porter, the platform that provides a Heroku-like experience on your own AWS, GCP, or Azure account. Helps developers deploy applications on managed Kubernetes clusters provisioned in their own cloud accounts, with the simplicity of git push deployment and the control of owning your infrastructure.

Instructions

Getting Started

# Porter provisions a Kubernetes cluster in YOUR cloud account
# 1. Sign up at dashboard.porter.run
# 2. Connect your AWS/GCP/Azure account
# 3. Porter creates a managed EKS/GKE/AKS cluster
# 4. Deploy apps through the dashboard or CLI

# Install Porter CLI
brew install porter-dev/porter/porter

# Login
porter auth login

# Set context
porter config set-project --project <project-id>
porter config set-cluster --cluster <cluster-id>

Application Deployment

# porter.yaml — Application configuration
version: v2

apps:
  api:
    build:
      method: pack                 # pack (buildpacks) | docker | registry
      context: .
      builder: heroku/builder:22
    
    services:
      web:
        type: web
        port: 3000
        cpus: 0.5
        memory: 512Mi
        replicas:
          min: 2
          max: 10
        autoscaling:
          enabled: true
          targetCPU: 60
          targetMemory: 70
        health_check:
          enabled: true
          path: /health
        domains:
          - name: api.myapp.com

      worker:
        type: worker
        cpus: 1
        memory: 1Gi
        replicas:
          min: 1
          max: 5
        command: "node dist/worker.js"

      cron:
        type: job
        cpus: 0.25
        memory: 256Mi
        command: "node dist/cron/daily-report.js"
        schedule: "0 8 * * *"
        timeout: 300

    env:
      NODE_ENV: production
      # Secrets managed via Porter dashboard or CLI
      DATABASE_URL:
        secret: true
      REDIS_URL:
        secret: true

    predeploy:
      - "npx prisma migrate deploy"

CLI Deployment

# Deploy from current directory
porter app update api

# Deploy a specific service
porter app update api --service web

# Run a one-off command (like Heroku run)
porter app run api -- npm run seed

# View logs
porter app logs api --service web --follow

# Scale a service
porter app update api --service web --replicas 5

# Set environment variables
porter app env set api DATABASE_URL=postgres://...
porter app env set api --secret API_KEY=sk-xxx

# List apps
porter app list

# Get app status
porter app get api

Database Addons

# Deploy managed databases (provisioned in your cloud account)
porter addon create postgresql \
  --name main-db \
  --version 16 \
  --plan db.t4g.medium \
  --storage 50

# Porter provisions RDS/Cloud SQL/Azure Database in YOUR account
# Connection strings auto-injected into linked apps

porter addon create redis \
  --name cache \
  --version 7 \
  --plan cache.t4g.micro

# Link addon to app
porter app env set api DATABASE_URL=$(porter addon get main-db --connection-string)

Preview Environments

# porter.yaml — Preview environment configuration
version: v2

previews:
  enabled: true
  # Every PR gets its own environment with isolated database
  apps:
    api:
      build:
        method: pack
      services:
        web:
          type: web
          port: 3000
          cpus: 0.25
          memory: 256Mi
          replicas:
            min: 1
            max: 1
      predeploy:
        - "npx prisma migrate deploy"
        - "npx prisma db seed"

  addons:
    - type: postgresql
      name: preview-db
      plan: db.t4g.micro

GitHub Actions Integration

# .github/workflows/deploy.yml
name: Deploy to Porter
on:
  push:
    branches: [main]

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

      - name: Deploy to Porter
        uses: porter-dev/porter-cli-action@v0.1.0
        with:
          command: app update api
        env:
          PORTER_TOKEN: ${{ secrets.PORTER_TOKEN }}
          PORTER_PROJECT: ${{ secrets.PORTER_PROJECT }}
          PORTER_CLUSTER: ${{ secrets.PORTER_CLUSTER }}

Examples

Example 1: Setting up Porter for a microservices project

User request:

I have a Node.js API and a React frontend running in Docker. Set up Porter for monitoring/deployment.

The agent creates the necessary configuration files based on patterns like # Porter provisions a Kubernetes cluster in YOUR cloud accou, sets up the integration with the existing Docker setup, configures appropriate defaults for a Node.js + React stack, and provides verification commands to confirm everything is working.

Example 2: Troubleshooting application deployment issues

User request:

Porter is showing errors in our application deployment. Here are the logs: [error output]

The agent analyzes the error output, identifies the root cause by cross-referencing with common Porter issues, applies the fix (updating configuration, adjusting resource limits, or correcting syntax), and verifies the resolution with appropriate health checks.

Guidelines

1. Your cloud, Porter's UX — Infrastructure runs in your AWS/GCP/Azure account; you own the data and the bill
2. Use porter.yaml — Define services, scaling, and env vars in code; avoid dashboard-only configuration
3. Predeploy for migrations — Run database migrations in the predeploy step; they execute before the new version goes live
4. Preview environments for PRs — Each PR gets isolated resources including databases; reviewers test real deployments
5. Autoscaling with CPU targets — Set targetCPU: 60 for web services; Porter handles HPA configuration on Kubernetes
6. Secrets through CLI/dashboard — Mark sensitive values with secret: true; they're stored as Kubernetes secrets
7. One-off commands with app run — Use for database seeding, REPL access, or debugging; runs in the same environment as your app
8. Monitor cloud costs — Porter creates real cloud resources (EKS, RDS, EC2); monitor your cloud bill directly