​
Overview

Deploying via Git (formerly known as Dockerfile Deploy) is the easiest deployment method 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 deployment process 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 and deploys it to new app containers

​
Get Started

If you are just getting started deploy a starter template or review guides for deploying with Git.

​
Dockerfile

The Dockerfile is a series of instructions that indicate how Docker should build an image for your app when you deploy via Git.

To build your Dockerfile on Aptible, the file must be named Dockerfile, and located at the root of your repository.

If it takes Aptible longer than 30 minutes to build your image from the Dockerfile, the deploy Operation will time out. If your image takes long to build, consider deploying via Docker Image.

New to Docker? Check out our guide for Getting Started with Docker.

​
Git Remote

A Git Remote is a reference to a repository stored on a remote server. When you provision an Aptible app, the platform creates a unique Git Remote. For example:

git @beta.aptible.com: $ENVIRONMENT_HANDLE / $APP_HANDLE.git

When deploying via Git, you push your code repository to the unique Git Remote for your app. To do this, you must:

  • Register an SSH Public Key with Aptible
  • Push your code to the master or main branch of the Aptible Git Remote
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.

​
Branches and refs

There are three branches that take action on push.

  • master and main attempt to deploy the incoming code before accepting the changes.
  • aptible-scan checks that the repo is deployable, usually by verifying the dockerfile can be built.

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 also be used to synchronize code and configuration changes.

When pushing multiple refs, each is processed individually. This means, for example you could check the deployability of your repo and push to an alternate branch using git push $APTIBLE_REMOTE $BRANCH_NAME:aptible-scan $BRANCH_NAME.

​
Aptible’s Git Server’s SSH Key Fingerprints

For an additional security check, public key fingerprints can be used to validate the connection to Aptible’s Git server. These are Aptible’s public key fingerprints for the Git server (beta.aptible.com):

  • SHA256:tA38HY1KedlJ2GRnr5iDB8bgJe9OoFOHK+Le1vJC9b0 (RSA)
  • SHA256:FsLUs5U/cZ0nGgvy/OorvGSaLzvLRSAo4+xk6+jNg8k (ECDSA)

​
Private Registry Authentication

You may need to provide Aptible with private registry credentials to pull images on your behalf. To do this, use the following configuration variables.

  • APTIBLE_PRIVATE_REGISTRY_USERNAME 
  • APTIBLE_PRIVATE_REGISTRY_PASSWORD 
Aptible will use configuration varibles when the image is attempting to be pulled is public or private. Configuration variables can be unset 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.

It’s recommended to set the credentials before updating your FROM declaration to depend on a private image and push your Dockerfile to Aptible. Credentials can be set in the following ways:

  • From the Aptible Dashboard by
    • Navigating to the App
    • Selecting the **Configuration **tab
  • Using the aptible config:set CLI command:
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.

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.

  1. Recommended: Synchronize configuration and code changes. This approach is the fastest.
  2. Update the variables using aptible config:set, deploy using git push aptible master, and restart your app to apply to apply the configuration change before the deploy can start. This approach is slower.

​
FAQ