--- name: terminal--porter description: >- Expert guidance for 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 origin: "github.com/TerminalSkills/skills (skill: porter)" license: Apache-2.0 version: "1.0.0" compatibility: "yamtam-engine >= 0.14.0" --- # 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 ```bash # 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 porter config set-cluster --cluster ``` ### Application Deployment ```yaml # 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 ```bash # 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 ```bash # 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 ```yaml # 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 ```yaml # .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