diff --git a/getting-started/concepts.mdx b/getting-started/concepts.mdx new file mode 100644 index 0000000..6a9ef0f --- /dev/null +++ b/getting-started/concepts.mdx @@ -0,0 +1,71 @@ +--- +title: "Concepts" +description: "Key concepts to understand when using Porter" +--- + +Check out our [deployment documentation](/deploy/overview), [infrastructure provisioning guides](/provision/overview), and more. + +
+ +
+

Cloud Account

+ + Your cloud provider account where Porter provisions and manages infrastructure. Porter connects to your AWS, GCP, or Azure account using secure access methods, maintaining full ownership and control in your own cloud. All infrastructure costs can be covered with your cloud credits. +
+ + Cloud account connection + + +
+ +
+ +
+

Cluster

+ + A managed Kubernetes cluster that Porter provisions in your cloud account to run your applications. Porter abstracts away the complexity of Kubernetes while intelligently allocating your applications across available nodes based on resource requirements. +
+ + Cluster configuration + + +
+ +
+ +
+

Node Group

+ + Groups of compute instances that make up your cluster. Porter provisions three default node groups: System (for Kubernetes workloads), Monitoring (for observability), and Application (for your workloads, with autoscaling). +
+ + Node groups configuration + + +
+ +
+ +
+

Application

+ + A group of services that share the same build and environment variables. When you deploy from a Git repository, Porter builds your code once and can run multiple services from that same build. Porter also supports deployment from both public and private Docker registries. +
+ + Configure applications + + +
+ +
+ +
+

Service

+ + Individual processes that make up your application. Each service can have different start commands, resource allocations, and configurations. Porter supports three types: **Web** (HTTP traffic), **Worker** (background processes), and **Job** (scheduled or on-demand tasks). +
+ + Service types + + +
diff --git a/getting-started/introduction.mdx b/getting-started/introduction.mdx new file mode 100644 index 0000000..2564fea --- /dev/null +++ b/getting-started/introduction.mdx @@ -0,0 +1,18 @@ +--- +title: "Introduction" +description: "Welcome to the Porter documentation" +--- + +## What is Porter? + +Porter is a platform as a service (PaaS) that runs in your own cloud. It brings the magical experience of deploying an application with just a few clicks into a cloud provider of your choice, whether that is AWS, GCP, or Azure. Porter will provision and manage the underlying infrastructure for you - simply point at your repository and Porter will handle the rest, from building your application to autoscaling it. + + + + Deploy your first application to Porter in minutes. + + + Learn the key concepts behind Porter's architecture. + + + diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx new file mode 100644 index 0000000..fc8e61d --- /dev/null +++ b/getting-started/quickstart.mdx @@ -0,0 +1,428 @@ +--- +title: "Quickstart" +description: "Get up and running with Porter in minutes" +--- + +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](https://dashboard.porter.run) and create an account +2. Click **Create Project** +3. Enter a project name + +![Create project screen](/images/getting-started/step-1.webp) + + +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](/images/getting-started/step-2.webp) + +If you've previously connected a cloud account to Porter, you can reuse those credentials. + +![Existing cloud accounts](/images/getting-started/step-2-existing.webp) + +--- + +## 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. + + + + Log into your [AWS Console](https://console.aws.amazon.com) and find your 12-digit Account ID in the top-right corner. Enter this ID in Porter. + + + Click **Grant Permissions**. Porter opens the AWS CloudFormation console to create a stack that provisions the `porter-manager` IAM role. + + ![Create CloudFormation stack](/images/getting-started/step-3-aws-create-stack.webp) + + + 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. + + + + Porter displays estimated monthly costs for your infrastructure (~$225/month for AWS). + + ![AWS cost review](/images/getting-started/step-3-aws-review-costs.webp) + + 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. + + + 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](/images/getting-started/step-3-aws-configure-and-provision.webp) + + + 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 limits](/images/getting-started/step-3-aws-limiting-quota.webp) + + Alternatively, you can manually request quota increases through the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/). + + + 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 a service account with permissions to manage your infrastructure. + + + + In your [GCP Console](https://console.cloud.google.com), navigate to **APIs & Services** and enable these five APIs: + + - Compute Engine API + - Kubernetes Engine API + - Cloud Resource Manager API + - Container Registry API + - Artifact Registry API + + + 1. Navigate to **IAM & Admin** > **Service Accounts** + 2. Click **Create Service Account** + 3. Name your service account (e.g., `porter-service-account`) + 4. Grant these five permissions: + - **Cloud Storage > Storage Admin** + - **Compute Engine > Compute Admin** + - **Kubernetes Engine > Kubernetes Engine Admin** + - **Service Accounts > Service Account User** + - **Artifact Registry > Artifact Registry Administrator** + 5. Click **Done** to create the account + 6. Under **Actions**, select **Manage keys** + 7. Click **Add Key** > **Create new key** > **JSON** + 8. The JSON key file downloads automatically. Keep it safe + + + In Porter, click **Drop a GCP Service Account JSON here, or click to browse** and upload the JSON key file you downloaded. + + ![Upload GCP service account key](/images/getting-started/step-3-gcp-upload-json.webp) + + Porter verifies the credentials and permissions. This typically takes about a minute. + + + Porter displays estimated monthly costs for your infrastructure (~$253/month for GCP). + + ![GCP cost review](/images/getting-started/step-3-gcp-review-costs.webp) + + 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. + + + 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 + + ![GCP cluster configuration](/images/getting-started/step-3-gcp-configure-and-provision.webp) + + 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. + + + + Before connecting Azure to Porter, you need to create a service principal. You can do this using our automated script or manually. + + + + If you have the Azure CLI installed and authenticated (`az login`), run our setup script: + + ```bash + # 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. + + + For manual setup, follow the detailed instructions in our [Azure provisioning guide](/provision/provisioning-on-azure#option-2-manual-setup). You'll need to: + + 1. Enable required Azure resource providers + 2. Create a custom IAM role + 3. Create a service principal + 4. Grant Microsoft Graph API permissions + + + + + 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 | + + ![Azure credentials entry](/images/getting-started/step-3-azure-permissions.webp) + + Porter verifies the credentials immediately when you submit. + + + Porter displays estimated monthly costs for your infrastructure (~$165/month for Azure). + + ![Azure cost review](/images/getting-started/step-3-azure-review-costs.webp) + + 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. + + + 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 + + ![Azure cluster configuration](/images/getting-started/step-3-azure-configure-and-provision.webp) + + 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. + + + + If this is your first deployment, you'll need to connect your GitHub account: + + ![Source selection screen](/images/deploy/v2/github-source-selection.webp) + + 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. + + + 1. Choose the repository containing your application + 2. Select the branch to deploy (defaults to `main` or `master`) + + ![GitHub repository and branch selector](/images/deploy/v2/github-repo-branch-selector.webp) + + + 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](/images/deploy/v2/detected-apps-list.webp) + + 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. + + + + Click the **gear icon** on any application card to customize: + + ![Settings button on application card](/images/deploy/v2/app-card-settings-button.webp) + + - **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. + + + Click **Deploy** to start your deployment. + + + + 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](/images/getting-started/step-4-github-merge-pr-banner.webp) + + 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: + + ```yaml + 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_... }} + ``` + + + + + + This approach works well when you have an existing CI/CD pipeline or are deploying third-party images. + + + + From the Create Application screen, click **Or, deploy from a container registry** in the top right. + + ![Container registry link](/images/deploy/v2/github-deploy-registry-link.webp) + + + 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) + + ![Container registry inputs](/images/deploy/v2/container-registry-inputs.webp) + + + 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. + + + 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: + ```bash + porter app update-tag APP_NAME --tag NEW_TAG + ``` + + + + + + +--- + +## 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](/images/getting-started/step-5-deployed.webp) + + +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: + + + + Connect your own domain name to your application. + + + Configure secrets and environment variables for your app. + + + Scale your application automatically based on traffic. + + + Add workers, jobs, and configure service settings. + + diff --git a/images/getting-started/apps.webp b/images/getting-started/apps.webp new file mode 100644 index 0000000..5dee5c0 Binary files /dev/null and b/images/getting-started/apps.webp differ diff --git a/images/getting-started/cloud-account.webp b/images/getting-started/cloud-account.webp new file mode 100644 index 0000000..fe4bb63 Binary files /dev/null and b/images/getting-started/cloud-account.webp differ diff --git a/images/getting-started/cluster.webp b/images/getting-started/cluster.webp new file mode 100644 index 0000000..4d37647 Binary files /dev/null and b/images/getting-started/cluster.webp differ diff --git a/images/getting-started/node-groups.webp b/images/getting-started/node-groups.webp new file mode 100644 index 0000000..3997906 Binary files /dev/null and b/images/getting-started/node-groups.webp differ diff --git a/images/getting-started/services.webp b/images/getting-started/services.webp new file mode 100644 index 0000000..508ad1f Binary files /dev/null and b/images/getting-started/services.webp differ diff --git a/images/getting-started/step-1.webp b/images/getting-started/step-1.webp new file mode 100644 index 0000000..a1e1f29 Binary files /dev/null and b/images/getting-started/step-1.webp differ diff --git a/images/getting-started/step-2-existing.webp b/images/getting-started/step-2-existing.webp new file mode 100644 index 0000000..bb9b015 Binary files /dev/null and b/images/getting-started/step-2-existing.webp differ diff --git a/images/getting-started/step-2.webp b/images/getting-started/step-2.webp new file mode 100644 index 0000000..aedd048 Binary files /dev/null and b/images/getting-started/step-2.webp differ diff --git a/images/getting-started/step-3-aws-configure-and-provision.webp b/images/getting-started/step-3-aws-configure-and-provision.webp new file mode 100644 index 0000000..d5f0ed7 Binary files /dev/null and b/images/getting-started/step-3-aws-configure-and-provision.webp differ diff --git a/images/getting-started/step-3-aws-create-stack.webp b/images/getting-started/step-3-aws-create-stack.webp new file mode 100644 index 0000000..59064cb Binary files /dev/null and b/images/getting-started/step-3-aws-create-stack.webp differ diff --git a/images/getting-started/step-3-aws-limiting-quota.webp b/images/getting-started/step-3-aws-limiting-quota.webp new file mode 100644 index 0000000..4f2e46e Binary files /dev/null and b/images/getting-started/step-3-aws-limiting-quota.webp differ diff --git a/images/getting-started/step-3-aws-review-costs.webp b/images/getting-started/step-3-aws-review-costs.webp new file mode 100644 index 0000000..176f002 Binary files /dev/null and b/images/getting-started/step-3-aws-review-costs.webp differ diff --git a/images/getting-started/step-3-azure-configure-and-provision.webp b/images/getting-started/step-3-azure-configure-and-provision.webp new file mode 100644 index 0000000..93d1589 Binary files /dev/null and b/images/getting-started/step-3-azure-configure-and-provision.webp differ diff --git a/images/getting-started/step-3-azure-permissions.webp b/images/getting-started/step-3-azure-permissions.webp new file mode 100644 index 0000000..8e110a8 Binary files /dev/null and b/images/getting-started/step-3-azure-permissions.webp differ diff --git a/images/getting-started/step-3-azure-review-costs.webp b/images/getting-started/step-3-azure-review-costs.webp new file mode 100644 index 0000000..2b5fb4d Binary files /dev/null and b/images/getting-started/step-3-azure-review-costs.webp differ diff --git a/images/getting-started/step-3-gcp-configure-and-provision.webp b/images/getting-started/step-3-gcp-configure-and-provision.webp new file mode 100644 index 0000000..9ff2f0e Binary files /dev/null and b/images/getting-started/step-3-gcp-configure-and-provision.webp differ diff --git a/images/getting-started/step-3-gcp-review-costs.webp b/images/getting-started/step-3-gcp-review-costs.webp new file mode 100644 index 0000000..2cc7b4b Binary files /dev/null and b/images/getting-started/step-3-gcp-review-costs.webp differ diff --git a/images/getting-started/step-3-gcp-upload-json.webp b/images/getting-started/step-3-gcp-upload-json.webp new file mode 100644 index 0000000..e1438d4 Binary files /dev/null and b/images/getting-started/step-3-gcp-upload-json.webp differ diff --git a/images/getting-started/step-4-github-merge-pr-banner.webp b/images/getting-started/step-4-github-merge-pr-banner.webp new file mode 100644 index 0000000..4e650e8 Binary files /dev/null and b/images/getting-started/step-4-github-merge-pr-banner.webp differ diff --git a/images/getting-started/step-5-deployed.webp b/images/getting-started/step-5-deployed.webp new file mode 100644 index 0000000..4ef3db4 Binary files /dev/null and b/images/getting-started/step-5-deployed.webp differ diff --git a/introduction.mdx b/introduction.mdx deleted file mode 100644 index 1ee9e3d..0000000 --- a/introduction.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Introduction" -description: "Welcome to the Porter documentation" ---- - -## What is Porter? - -Porter is a platform as a service (PaaS) that runs in your own cloud. It brings the magical experience of deploying an application with just a few clicks into a cloud provider of your choice, whether that is AWS, GCP, or Azure. Porter will provision and manage the underlying infrastructure for you - simply point at your repository and Porter will handle the rest, from building your application to autoscaling it. - -Get started with the documentation: - - - Connect your AWS, GCP, or Azure account. - - - Deploy from a Github repository, Docker registry, or write your own workflow - - - Manage, scale, and monitor your applications. - - -## Why Porter? - -Many companies that start building on a PaaS eventually migrate away from it as they scale due to technical and economic constraints. While the simplicity of these PaaS's may be appealing at first for companies that want to focus on application logic, it comes at the risk of being locked into inflexible infrastructure. Companies are thus faced with the following dilemma: build on a PaaS to move fast or run their own infrastructure to prevent problems in the future. - -**But what if running your own infrastructure was just as easy as, if not easier than, building on a PaaS?** - -Porter gives you the best of both worlds by bringing the simplicity of a PaaS into your own infrastructure that you can fully control. If necessary, you can always directly interact with the infrastructure Porter is managing through your cloud provider and it is even possible to eject your infrastructure from Porter. There is no vendor lock-in. - -**Simply put, Porter is a PaaS that you can't outgrow.** - -## Relationship with Kubernetes - -Under the hood, Porter runs on top of Kubernetes. Porter provisions and manages each cloud provider's native Kubernetes offering (i.e. EKS on AWS, GKE on GCP, and AKS on Azure) while abstracting away its complexity. - -Some find it daunting that Porter runs on top of Kubernetes. For teams who don't know Kubernetes, **Kubernetes is an incidental implementation detail**. You don't need to know anything about Kubernetes other than a few basic concepts to use Porter. -It just _happens_ that Kubernetes is the best underlying layer to deliver the PaaS experience on. In fact, most traditional PaaS's actually run on top of Kubernetes, although that detail is hidden away from the end user. Many of our users who have migrated from another PaaS experience no learning curve, and you can still take advantage of the power of Kubernetes in the future should you need it. diff --git a/mint.json b/mint.json index 358c3ff..010f154 100644 --- a/mint.json +++ b/mint.json @@ -24,13 +24,6 @@ "name": "Get Started", "url": "https://porter.run" }, - "anchors": [ - { - "name": "Get Started", - "icon": "play", - "url": "https://dashboard.porter.run" - } - ], "modeToggle": { "default": "dark" }, @@ -38,7 +31,14 @@ { "group": "", "pages": [ - "introduction", + { + "group": "Getting Started", + "pages": [ + "getting-started/introduction", + "getting-started/concepts", + "getting-started/quickstart" + ] + }, { "group": "Cloud Accounts", "pages": [