Skip to main content
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:
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.
Your application should:
  • Have a start command or Dockerfile
  • Be pushed to a GitHub repository (or have a container image in a registry)

​
Step 1: Sign up and create a project

  1. Navigate to dashboard.porter.run and create an account
  2. Click Create Project
  3. Enter a project name
Create project screen
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. Cloud provider selection If you’ve previously connected a cloud account to Porter, you can reuse those credentials. Existing cloud accounts

​
Step 3: Set up your cluster

Porter provisions a Kubernetes cluster in your cloud account. The setup process varies by provider.
Porter uses AWS IAM role assumption to securely access your account without storing static credentials.
1

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.
2

Create the CloudFormation stack

Click Grant Permissions. Porter opens the AWS CloudFormation console to create a stack that provisions the porter-manager IAM role.Create CloudFormation stack
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.
3

Review costs

Porter displays estimated monthly costs for your infrastructure (~$225/month for AWS).AWS cost reviewThese 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.
4

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 cluster configuration
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.AWS quota limitsAlternatively, 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.

​
Step 4: Create your first application

Once your cluster is ready, you’ll see the Porter dashboard. Click Create Application to deploy your code.
Porter builds your application from source code and sets up automated deployments on every push.
1

Connect GitHub

If this is your first deployment, you’ll need to connect your GitHub account:Source selection screen
  1. Click Connect repositories
  2. Authorize the Porter GitHub App
  3. 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.
2

Select your repository

  1. Choose the repository containing your application
  2. Select the branch to deploy (defaults to main or master) GitHub repository and branch selector
3

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.) Detected applications list
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.
4

Configure your application (optional)

Click the gear icon on any application card to customize:Settings button on application card
  • 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.
5

Deploy

Click Deploy to start your deployment.
6

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 Merge PR banner
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.
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.1.0
      - run: porter apply
        env:
          PORTER_TOKEN: ${{ secrets.PORTER_APP_... }}

​
Step 5: View your running application

Return to the Porter dashboard to monitor your deployment:
  1. Click on your application to view deployment progress
  2. Watch the build logs as Porter builds your container image
  3. 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. 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.