Porter supports linking a private Docker container registry to your project. This container registry is used to deploy Docker containers onto a cluster and push new versions of the image to your registry from CI/CD workflows. We support the following container registries:

The following guide will show you how to link your container registries depending on your registry provider. Some container registries can only be linked from the CLI, so make sure that you’ve following the installation guide for the CLI.

​
Amazon Elastic Container Registry (ECR)

In order to link ECR, an AWS IAM user must be created in your AWS account with access to push, pull and list images from the ECR registry. If you are logged in via the AWS CLI, Porter can generate these credentials for you automatically when you run porter connect ecr. Alternatively, you must first create an ECR user and have those credentials ready for the next step!

You can link ECR using either the dashboard or the CLI:

  • Browser

  • CLI

In order to link an existing ECR registry from the dashboard, navigate to the Integrations tab and select Docker Registry. Then, select Add a Registry in top right, and select Elastic Container Registry. Give the registry a name, for example my-awesome-registry: ECR Next, input the AWS credentials (if you do not have your AWS credentials, follow the instructions below). Then, click Save Settings.

To verify that the ECR registry was linked correctly, you can navigate to the Integrations tab, click Docker Registry, and expand a registry to make sure you see all repositories listed.

Troubleshooting

If you are unable to connect to your registry, double-check that the user exists, the region is correct, and the credentials were copied correctly.

​
Creating an AWS ECR User

Before linking your ECR registry, you can create an AWS IAM user that has access to ECR, and then generate AWS credentials. To create a new user, go to your AWS console and navigate to IAM -> Users and select Add user:

AWS add user

Give your user a name and select Programmatic access. After selecting Next, you will be prompted to set permissions for your user, choose Attach existing policies directly and search for the policy AmazonEC2ContainerRegistryFullAccess that can push/pull images from ECR.

If you’d like to customize the IAM policy, you can create a new policy and attach that to the user directly.

After creating this user, you will see an AWS Access Key and Secret — make sure you have these credentials ready, and link your ECR registry using the instructions above.

​
Google Artifact Registry (GAR)

​
Creating a GCP Service Account for GAR

Before you can connect to an existing GAR instance, you must create a service account with permission to push/pull from GAR. To do this, follow the steps below.

  1. First, go to your Google Cloud console and navigate to IAM & Admin -> Service Accounts:

GCP service accounts

  1. Select Create Service Account:

Create SA

  1. Name your service account (for example, “porter-gar-access”), grant the service account Artifact Registry Administrator permissions, then select Done:

Artifact registry administrator permissions

  1. After creating the service account, you will be redirected to the list of service accounts. Find the row with the newly created service account, and select “Manage keys” in the “Actions” column:

Manage keys SA

  1. Finally, press the “Add key” dropdown and select “Create new key”. After choosing the JSON key type, your key file will be automatically downloaded:

JSON key download

​
Linking GAR

Now that you have a service account and JSON key downloaded, linking GAR can either be done from the dashboard or the CLI:

  • Browser

  • CLI

In order to link an existing GAR registry from the dashboard, navigate to the Integrations tab and select Docker Registry. Then, select Add a Registry in top right, and select Google Artifact Registry. Give the registry a name, for example my-awesome-registry: GAR Next, input the GCP credentials that you downloaded above, and enter your GAR region. Then, click Save Settings.

​
Google Container Registry (GCR)

​
Creating a GCP Service Account for GCR

Before you can connect to an existing GCR instance, you must create a service account with permission to push/pull from GCR. To do this, follow the steps below.

  1. First, go to your Google Cloud console and navigate to IAM & Admin -> Service Accounts:

GCP service accounts

  1. Select Create Service Account:

Create SA

  1. Name your service account (for example, “porter-gcr-access”), grant the service account Storage Admin permissions, then select Done:

Storage admin permissions

  1. After creating the service account, you will be redirected to the list of service accounts. Find the row with the newly created service account, and select “Manage keys” in the “Actions” column:

Manage keys SA

  1. Finally, press the “Add key” dropdown and select “Create new key”. After choosing the JSON key type, your key file will be automatically downloaded:

JSON key download

​
Linking GCR

Now that you have a service account and JSON key downloaded, linking GCR can either be done from the dashboard or the CLI:

  • Browser

  • CLI

In order to link an existing GCR registry from the dashboard, navigate to the Integrations tab and select Docker Registry. Then, select Add a Registry in top right, and select Google Container Registry. Give the registry a name, for example my-awesome-registry: GCR Next, input the GCP credentials that you downloaded above, and enter your registry URL, the the form [GCR_DOMAIN]/[GCP_PROJECT_ID]. For most, the GCR domain will be gcr.io (for more information, click here). Then, click Save Settings.

​
Digital Ocean Container Registry

At the moment, linking a Digital Ocean Container Registry can only be done using the Porter CLI. To connect, run the following command:

porter connect docr

If you have not yet linked a DigitalOcean account, this command will open the browser that allows you to link your DigitalOcean account. Authorize the DigitalOcean account that you’d like to give access. You will then be redirected to the dashboard, at which point you can close out of the browser tab and go back to the CLI.

The CLI will then prompt you to provide a link to the container registry, in the form registry.digitalocean.com/[REGISTRY_NAME]. This can be found by navigating to the “Container Registry” tab in DigitalOcean and copying the registry name:

Container registry name

Please provide the registry URL, in the form registry.digitalocean.com/[REGISTRY_NAME]. For example, registry.digitalocean.com/porter-test.
Registry URL: registry.digitalocean.com/porter-hi

That’s it! If you navigate to the “Launch” tab in the dashboard, you should see your existing DigitalOcean Container Registry images in the “Registry” section.

​
Docker Hub

In order to connect to a Docker Hub image repository, you must first generate a personal access token in the Docker Hub dashboard. Navigate to the “Security” tab in your account settings, and select “New Access Token”:

Access token

Name this access token something like “Porter,” and copy the access token to the clipboard.

If you’re planning on linking more than one image repository through Docker Hub, you will need to re-use this access token multiple times, so you may want to copy it to a local file on your computer and delete it when you’re finished.

Then type porter connect dockerhub into the CLI. You will first be prompted to enter the path to the Docker Hub image repository that you would like to link. The image repository path can be found by going to the “Repositories” tab in Docker Hub and copying the username/organization and repository name. For example, for an organization called “porter1” and an image repository name called “porter”, the repo name would be “porter1/porter”:

Provide the Docker Hub image path, in the form of ${org_name}/${repo_name}. For example, porter1/porter.
Image path: porter1/porter

You should then enter your Docker Hub username and the access token you just copied.

That’s it! If you navigate to the “Launch” tab in the dashboard, you should see your existing Docker Hub image repository in the “Registry” section.

Multiple Docker Hub Repositories

This flow only links a single Docker Hub repository at a time. If you’d like to link multiple repositories, you must run porter connect dockerhub for each repository.

​
Custom/Private Registries

Other Docker container registries are supported, as long as they implement the Registry HTTP API v2 specification. To link these, type porter connect registry into the CLI. You will then be asked to input the URL of your image repository:

Provide the image registry URL (include the protocol). For example, https://my-custom-registry.getporter.dev.
Image registry URL: https://my-custom-registry.getporter.dev

If your registry is public, you can simply press enter when asked to input the username/password. Otherwise, enter the username/password that you would use for docker login.

That’s it! If you navigate to the “Launch” tab in the dashboard, you should see your existing image repositories in the “Registry” section.

OverviewDeploying from an Existing Docker Registry