Dockerfile Deploy

Learn about deploying to Aptible with Dockerfile Deploy

Overview

A Dockerfile Deploy is the easiest way to get up and running on Aptible if you're migrating over from another Platform-as-a-Service or your team isn't using Docker yet.

The workflow for Dockerfile Deploy is as follows:

1. You add a Dockerfile at the root of your code repository and commit it.
2. You use git push to push your code repository to a Git Remote provided by Aptible.
3. Aptible builds a new Image from your Dockerfile, then starts new Containers for your App using the newly-built image.

Guides & Examples:

• How to deploy with Dockerfile Deploy
• How to migrate from Direct Docker Image Deploy to Dockerfile Deploy

📘 Only pushing the master branch of the Aptible Git Remote will trigger to a deploy. If you push to a different branch, you can manually deploy the branch using the aptible deploy --git-commitish $BRANCH_NAME CLI command. This can be used to synchronize code and configuration changes.

❗️ If SSO is required for accessing your Aptible organization, attempts to use the git remote will return an App not found or not accessible error. Users will need to be added to the SSO Allow List to access your Organization's resources via git.

Private Registry Authentication

You may need to provide Aptible with private registry credentials to pull images on your behalf. To do this, use the APTIBLE_PRIVATE_REGISTRY_USERNAME and APTIBLE_PRIVATE_REGISTRY_PASSWORD Configuration variables.

📘 If you set those Configuration variables, Aptible 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 only need to provide once to Aptible.

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

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

Short term credentials

Some registries, like AWS Elastic Container Registry (ECR), only provide short-term credentials. In these cases, you will likely need to update your registry credentials every time you 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 recommended approach:

1. Push your code to Aptible without deploying it using git push
2. Deploy your code while setting the new Configuration
3. Review Synchronizing Configuration and code changes for more information and usage examples on this recommended approach.

An alternative approach:

1. Update the variables using aptible config:set
2. Deploy using git push aptible master
3. This approach will require restarting your App once to apply the Configuration change before the deploy can start. It will be slower than the recommended approach.

Keep reading:

• Accessing Configuration variables during the Docker build
• Dockerfile
• Build Context
• Git Remote