Quickstart - Porter

This guide walks you through deploying your first application on Porter, from creating an account to seeing your app live at a public URL.

Prerequisites

Before you begin, make sure you have:

Cloud provider account

An active account with AWS, GCP, or Azure with admin or owner permissions. Porter provisions infrastructure in your cloud account, so you’ll need permissions to create resources like Kubernetes clusters, networking components, and IAM roles.

A deployable application

Your application should:

Have a start command or Dockerfile
Be pushed to a GitHub repository (or have a container image in a registry)

Navigate to dashboard.porter.run and create an account
Click Create Project
Enter a project name

Project names must be 1-25 characters, using only lowercase letters, numbers, and hyphens.

Step 2: Select your cloud provider

Choose the cloud provider where you want Porter to provision your infrastructure.

If you’ve previously connected a cloud account to Porter, you can reuse those credentials.

Step 3: Set up your cluster

Porter provisions a Kubernetes cluster in your cloud account. The setup process varies by provider.

AWS
GCP
Azure

Porter uses AWS IAM role assumption to securely access your account without storing static credentials.

Enter your AWS Account ID

Log into your AWS Console and find your 12-digit Account ID in the top-right corner. Enter this ID in Porter.

Create the CloudFormation stack

Click Grant Permissions. Porter opens the AWS CloudFormation console to create a stack that provisions the porter-manager IAM role.

If the popup is blocked, check your browser settings and allow popups from Porter.

Scroll to the bottom of the CloudFormation page, check the I acknowledge that AWS CloudFormation might create IAM resources box, and click Create Stack.

The IAM role must remain in your AWS account for Porter to manage your infrastructure. Deleting it will prevent Porter from making changes.

Review costs

Porter displays estimated monthly costs for your infrastructure (~$225/month for AWS).

These estimates are for the default cluster configuration. Actual costs vary based on usage, region, and any customizations you make.Review the cost breakdown and click Accept to continue.

Configure and provision

Porter pre-configures your cluster with sensible defaults:

Cluster name: Auto-generated based on your project
Region: Defaults to us-east-1
Node groups: Pre-configured with appropriate instance types

AWS resource quota limits

If AWS is limiting your account’s resource quota, Porter will display a warning and offer to auto-request quota increases on your behalf. Allow Porter to auto-request AWS quota is enabled by default.

Alternatively, you can manually request quota increases through the AWS Service Quotas console.

You can customize these settings or accept the defaults. Click Provision to start creating your infrastructure.

Provisioning takes approximately 30-45 minutes. You can close the browser and return later. Porter continues working in the background.

Porter connects to GCP using Workload Identity Federation. Workload Identity Federation offers a mechanism for Porter to connect with your GCP project without requiring any static keys.

Enter your GCP Project ID

In Porter, select GCP. Enter your GCP project ID (visible at the top of any page in the GCP Console) and click Connect.

Run the setup in Cloud Shell

Porter generates a one-line setup command tied to this integration. Copy it, click Open Cloud Shell, and paste it into the shell that opens.The script runs Terraform inside your project to create a service account, a Workload Identity Pool with a trust policy scoped to your tenant, and the five Google APIs Porter needs to bootstrap federation (Cloud Resource Manager, IAM, IAM Credentials, STS, Service Usage). Setup takes about 30 seconds.

Wait for verification

The Porter dashboard polls automatically. Once the bootstrap completes, Porter finishes enabling the remaining APIs, grants the heavier IAM roles, and marks the cloud account connected. The status banner turns green and the Continue button enables.For the full mechanism (trust boundary, permissions granted, troubleshooting), see Connecting a Cloud Account → GCP.

Review costs

Porter displays estimated monthly costs for your infrastructure (~$253/month for GCP).

These estimates are for the default cluster configuration. Actual costs vary based on usage, region, and any customizations you make.Review the cost breakdown and click Accept to continue.

Configure and provision

Porter pre-configures your cluster with sensible defaults:

Cluster name: Auto-generated based on your project
Region: Defaults to us-east1
Node groups: Pre-configured with appropriate instance types

You can customize these settings or accept the defaults. Click Provision to start creating your infrastructure.

Provisioning takes approximately 30-45 minutes. You can close the browser and return later. Porter continues working in the background.

Porter connects to Azure using a service principal with permissions to manage your infrastructure.

Create a service principal

Before connecting Azure to Porter, you need to create a service principal. You can do this using our automated script or manually.

Option 1: Automated setup (recommended)

If you have the Azure CLI installed and authenticated (az login), run our setup script:

# Download the setup script
curl -O https://raw.githubusercontent.com/porter-dev/docs/main/scripts/setup-azure-porter.sh

# Make it executable
chmod +x setup-azure-porter.sh

# Run the script (optionally provide subscription ID)
./setup-azure-porter.sh [your-subscription-id]

The script creates the required role, service principal, and grants necessary permissions. Copy the output credentials for the next step.

Option 2: Manual setup

For manual setup, follow the detailed instructions in our Azure provisioning guide. You’ll need to:

Enable required Azure resource providers
Create a custom IAM role
Create a service principal
Grant Microsoft Graph API permissions

Enter your credentials

In Porter, enter the following values from your service principal:

Field	Description
Subscription ID	Your Azure subscription ID
Application (Client) ID	The `appId` from your service principal
Client Secret	The `password` from your service principal
Tenant ID	The `tenant` from your service principal

Porter verifies the credentials immediately when you submit.

Review costs

Porter displays estimated monthly costs for your infrastructure (~$165/month for Azure).

These estimates are for the default cluster configuration. Actual costs vary based on usage, region, and any customizations you make.Review the cost breakdown and click Accept to continue.

Configure and provision

Porter pre-configures your cluster with sensible defaults:

Cluster name: Auto-generated based on your project
Region: Defaults to eastus
Node groups: Pre-configured with appropriate instance types

You can customize these settings or accept the defaults. Click Provision to start creating your infrastructure.

Provisioning takes approximately 30-45 minutes. You can close the browser and return later. Porter continues working in the background.

Step 4: Create your first application

Once your cluster is ready, choose how you want to deploy your code.

Agent
Dashboard
CLI

Ask an agent connected to the Porter MCP server to create the application for you. It detects your build settings from the codebase and opens a pull request that you merge to deploy.

Check the prerequisites

Connect your agent to the Porter MCP server. curl -fsSL https://agents.porter.run | sh does this for you and installs Porter’s skills.
Install the Porter GitHub App on the repository you want to deploy. The MCP server cannot install the GitHub App for you.

Ask your agent to deploy

Deploy this GitHub repository to Porter. Detect the build method and application settings from the codebase.

The agent resolves your Porter project and cluster, then calls create_app with the repository source and build configuration. Porter creates the application with a placeholder image and opens a pull request containing a GitHub Actions workflow.

Merge the pull request

Review and merge the pull request that the agent returns. Merging it triggers the workflow that builds your code and runs the first real deployment.

In the Porter dashboard, click Create Application, then choose your source.

GitHub repository
Docker registry

Porter builds your application from source code and sets up automated deployments on every push.

Connect GitHub

If this is your first deployment, install the Porter GitHub App:

Click Connect repositories
Authorize the Porter GitHub App
Choose which repositories Porter can access (all repositories or select specific ones)

Porter needs read access to detect your code structure and write access to create the deployment workflow.

Select your repository

Choose the repository containing your application
Select the branch to deploy (defaults to main or master)

Review detected applications

Porter scans your repository and automatically detects:

Frameworks and languages (Node.js, Python, Go, etc.)
Dockerfiles
Service types (web servers, workers, etc.)

You’ll see a card for each detected application showing the app name, detected framework, and repository path.

For monorepos with multiple services, Porter detects each application separately. A Node.js API in /api and a React frontend in /web appear as distinct applications. If some services are already deployed on your cluster, Porter hides them by default so you can focus on new applications. Expand the previously deployed section to view or re-add them.

Configure your application (optional)

Click the gear icon on any application card to customize:

Build method: Docker (using your Dockerfile) or Buildpacks (automatic)
Start command: The command to run your application
Port: The port your application listens on

For most applications, Porter’s detected defaults work without changes.

Deploy

Click Deploy to start your deployment.

Merge the GitHub Actions PR

This step is critical. Your application won’t be available until you merge the PR.

Porter creates a pull request in your repository containing a GitHub Actions workflow file at .github/workflows/porter.yml. This workflow handles building and deploying your application on every push.After clicking Deploy, you’ll see:

A toast notification with a “View PR” button that links directly to the pull request
A warning banner on your app’s page with a “Merge PR” link

Click either link to open the pull request on GitHub, then merge it. After merging, click Refresh on the banner to update the status. GitHub Actions triggers automatically and your first deployment begins.

What's in the workflow file?

The workflow Porter creates looks like this:

on:
  push:
    branches:
      - main
name: Deploy to Porter
jobs:
  porter-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: porter-dev/setup-porter@v0.2.0
      - run: porter apply
        env:
          PORTER_TOKEN: ${{ secrets.PORTER_APP_... }}

This approach works well when you have an existing CI/CD pipeline or are deploying third-party images.

Select container registry

From the Create Application screen, click Or, deploy from a container registry in the top right.

Specify your image

Enter your image details:

Image repository: The full path to your image
- Docker Hub: docker.io/username/image or username/image
- Amazon ECR: 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app
- Google Artifact Registry: us-docker.pkg.dev/project-id/repo/image
- Azure Container Registry: myregistry.azurecr.io/my-app
Tag: The version to deploy (e.g., latest, v1.2.3, or a commit SHA)

Configure your application

Porter creates an application configuration with sensible defaults. Since Porter can’t inspect your pre-built image, you’ll need to specify:

Port: The port your container listens on (for web services)
Start command: Override the image’s default CMD if needed

Click the gear icon to adjust resources (CPU, RAM, instances) if the defaults don’t fit your needs.

Deploy

Click Deploy to pull your image and start running it.

To update your application later, push a new image tag and use the Porter CLI:

porter app update-tag APP_NAME --tag NEW_TAG

Deploy the application from a porter.yaml file:

porter apply -f porter.yaml

Learn how to define and deploy an application in the configuration-as-code guide.

Step 5: View your running application

Return to the Porter dashboard to monitor your deployment:

Click on your application to view deployment progress
Watch the build logs as Porter builds your container image
Monitor the deployment as Porter starts your application

Once the deployment completes, your application status changes to Running.

Access your application

Porter automatically provisions a public URL for your application at *.onporter.run. Click the URL in your dashboard to visit your deployed application.

Congratulations! Your application is now live and will automatically redeploy whenever you push to your selected branch.

Next steps

Now that your application is running, explore these guides to customize your deployment:

Custom domains

Connect your own domain name to your application.

Environment groups

Configure secrets and environment variables for your app.

Autoscaling

Scale your application automatically based on traffic.

Types of services

Add workers, jobs, and configure service settings.

​Prerequisites

​Step 1: Sign up and create a project

​Step 2: Select your cloud provider

​Step 3: Set up your cluster

​Step 4: Create your first application

​Step 5: View your running application

​Access your application

​Next steps

Custom domains

Environment groups

Autoscaling

Types of services

Prerequisites

Step 1: Sign up and create a project

Step 2: Select your cloud provider

Step 3: Set up your cluster

Step 4: Create your first application

Step 5: View your running application

Access your application

Next steps