Private Registry Authentication

Whether you are using Dockerfile Deploy or Direct Docker Image Deploy, you may need to provide Enclave with private registry credentials to pull images on your behalf, respectively to pull a private base image, or a private image to deploy.

On Enclave, this is done by providing the APTIBLE_PRIVATE_REGISTRY_USERNAME and APTIBLE_PRIVATE_REGISTRY_PASSWORD Configuration variables.

Tip

If you set those Configuration variables, Enclave will use them regardless of whether the image you are attempting to pull is public or private.

If needed, you can unset those Configuration variables by setting them to an empty string ("").

Long term credentials

Most Docker image registries provide long-term credentials, which you can provide once to Enclave.

Dockerfile deploy

The easiest approach when you need to provide credentials for a Dockerfile Deploy is to set them using the CLI’s aptible config:set before updating your FROM declaration to depend on a private image and pushing your Dockerfile to Enclave:

aptible config:set \
  --app "$APP_HANDLE" \
  "APTIBLE_PRIVATE_REGISTRY_USERNAME=$USERNAME"
  "APTIBLE_PRIVATE_REGISTRY_PASSWORD=$PASSWORD"

Direct Docker Image deploy

For a Direct Docker Image Deploy, simply provide the registry credentials the first time you deploy. You don’t need to provide them again going forward:

aptible deploy \
  --app "$APP_HANDLE" \
  --docker-image "$DOCKER_IMAGE" \
  --private-registry-username "$USERNAME" \
  --private-registry-password "$PASSWORD"

Short term credentials

Some registries only provide short-term credentials, notably AWS Elastic Container Registry (ECR).

In this case, you’ll likely need to update your registry credentials every time you deploy.

Dockerfile deploy

To perform a Dockerfile Deploy using short-term credentials, you’ll need to synchronize your deployment with an update of your credentials.

Since Docker credentials are provided as Configuration variables, you’ll need to use the CLI in addition to git push to deploy.

There are two solutions to this problem.

The first and recommended approach is to deploy in as follows: push your code to Aptible without deploying it, then deploy it while setting the new Configuration.

Review Synchronizing Configuration and code changes for more information and usage examples on this recommended approach.

The alternative approach is to first update the variables using aptible config:set, and then deploy using git push aptible master.

However, this alternative approach will require restarting your app once to apply the Configuration change before the deploy can start. This means it’ll be slower than the recommended approach.

Direct Docker Image deploy

This case is simpler: just provide updated credentials whenever you deploy, as if it were the first time you deployed:

aptible deploy \
  --app "$APP_HANDLE" \
  --docker-image "$DOCKER_IMAGE" \
  --private-registry-username "$USERNAME" \
  --private-registry-password "$PASSWORD"