How to deploy to Aptible with CI/CD
Overview
To make it easier to deploy on Aptible—whether you’re migrating from another platform or deploying your first application—we offer integrations with several continuous integration services.
If your team is already using a Git-based deployment workflow, deploying your app to Aptible should be relatively straightforward.
Deploying with Git
Prerequisites
To deploy to Aptible via Git, you must have a public SSH key associated with your account. We recommend creating a robot user to manage your deployment:
-
Create a “Robots” custom role in your Aptible organization, and grant it “Full Visibility” and “Deployment” permissions for the environment where you will be deploying.
-
Invite a new robot user with a valid email address (for example,
deploy@yourdomain.com
) to theRobots
role. -
Sign out of your Aptible account, accept the invitation from the robot user’s email address, and set a password for the robot’s Aptible account.
-
Generate a new SSH key pair to be used by the robot user, and don’t set a password:
ssh-keygen -t ed25519 -C "your_email@example.com"
-
Register the SSH Public Key with Aptible for the robot user.
Configuring the Environment
First, you’ll need to configure a few environment variables and secrets for your repository:
- Environment variable:
APTIBLE_APP
, the name of the App to deploy. - Environment variable:
APTIBLE_ENVIRONMENT
, the name of the Aptible environment in which your App lives. - Secret:
APTIBLE_USERNAME
, the username of the Aptible user with which to deploy the App. - Secret:
APTIBLE_PASSWORD
, the password of the Aptible user with which to deploy the App.
Configuring the Workflow
Finally, you must configure the workflow to deploy your application to Aptible:
Configuring the Environment
First, you’ll need to configure a few environment variables and secrets for your repository:
- Environment variable:
APTIBLE_APP
, the name of the App to deploy. - Environment variable:
APTIBLE_ENVIRONMENT
, the name of the Aptible environment in which your App lives. - Secret:
APTIBLE_USERNAME
, the username of the Aptible user with which to deploy the App. - Secret:
APTIBLE_PASSWORD
, the password of the Aptible user with which to deploy the App.
Configuring the Workflow
Finally, you must configure the workflow to deploy your application to Aptible:
Configuring SSH
To deploy to Aptible via CircleCI, add your SSH Private Key via the CircleCI Dashboard with the following values:
- Hostname:
beta.aptible.com
- Private Key: The contents of the SSH Private Key created in the previous step.
Configuring the Environment
You also need to set environment variables on your project with the name of your Aptible environment and app, in APTIBLE_ENVIRONMENT
and APTIBLE_APP
, respectively. You can add these to your project using environment variables on the Circle CI dashboard.
Configuring the Deployment
Finally, you must configure the Circle CI project to deploy your application to Aptible:
Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the circle-deploy
branch):
The most important part of this configuration is the value of the command
key under the run
step. Here we add our SSH private key to the Circle CI environment, configure a new remote for our repository on Aptible’s platform, and push our branch to Aptible:
From there, the procedure for a Dockerfile-based deployment remains the same!
Configuring SSH
To deploy to Aptible via Travis CI, add your SSH Private Key via the Travis CI repository settings with the following values:
- Name:
APTIBLE_GIT_SSH_KEY
- Value: The base64-encoded contents of the SSH Private Key created in the previous step.
⚠️ Warning
The SSH private key added to the Travis CI environment variable must be base64-encoded.
Configuring the Environment
You also need to set environment variables on your project with the name of your Aptible environment and app, in APTIBLE_ENVIRONMENT
and APTIBLE_APP
, respectively. You can add these to your project using environment variables on the Travis CI dashboard.
Configuring the Deployment
Finally, you must configure the Travis CI project to deploy your application to Aptible:
Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the travis-deploy
branch) and where we are going to deploy (so we add beta.aptible.com
as a known host):
The Travis CI configuration then allows us to split our script into two parts, with the before_script
configuring the Travis CI environment to use our SSH key:
Finally, our script
block configures a new remote for our repository on Aptible’s platform, and pushes our branch to Aptible:
From there, the procedure for a Dockerfile-based deployment remains the same!
Configuring SSH
To deploy to Aptible via GitLab CI, add your SSH Private Key via the GitLab CI dashboard with the following values:
- Key:
APTIBLE_GIT_SSH_KEY
- Value: The base64-encoded contents of the SSH Private Key created in the previous step.
⚠️ Warning
The SSH private key added to the GitLab CI environment variable must be base64-encoded.
Configuring the Environment
You also need to set environment variables on your project with the name of your Aptible environment and app, in APTIBLE_ENVIRONMENT
and APTIBLE_APP
, respectively. You can add these to your project using project variables on the GitLab CI dashboard.
Configuring the Deployment
Finally, you must configure the GitLab CI pipeline to deploy your application to Aptible:
Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the gitlab-deploy
branch), and then we define the before_script
that will configure SSH in our job environment:
Finally, our script
block configures a new remote for our repository on Aptible’s platform, and pushes our branch to Aptible:
From there, the procedure for a Dockerfile-based deployment remains the same!
Deploying with Docker
Prerequisites
To deploy to Aptible with a Docker image via a CI integration, you should create a robot user to manage your deployment:
-
Create a
Robots
custom Aptible role in your Aptible organization. Grant it “Read” and “Manage” permissions for the environment where you would like to deploy. -
Invite a new robot user with a valid email address (for example,
deploy@yourdomain.com
) to theRobots
role. -
Sign out of your Aptible account, accept the invitation from the robot user’s email address, and set a password for the robot’s Aptible account.
Some of the below instructions and more information can also be found on the Github Marketplace page for the Deploy to Aptible Action.
Configuring the Environment
To deploy to Aptible via GitHub Actions, you must first create encrypted secrets for your repository with Docker registry and Aptible credentials:
DOCKERHUB_USERNAME
and DOCKERHUB_TOKEN
The credentials for your private Docker registry (in this case, DockerHub).
APTIBLE_USERNAME
and APTIBLE_PASSWORD
The credentials for the robot account created to deploy to Aptible.
Configuring the Workflow
Additionally, you will need to set some environment variables within the GitHub Actions workflow:
IMAGE_NAME
The Docker image you wish to deploy from your Docker registry.
APTIBLE_ENVIRONMENT
The name of the Aptible environment acting as the target for this deployment.
APTIBLE_APP
The name of the app within the Aptible environment we are deploying with this workflow.
Configuring the Workflow
Finally, you must configure the workflow to deploy your application to Aptible:
Some of the below instructions and more information can also be found on the Github Marketplace page for the Deploy to Aptible Action.
Configuring the Environment
To deploy to Aptible via GitHub Actions, you must first create encrypted secrets for your repository with Docker registry and Aptible credentials:
DOCKERHUB_USERNAME
and DOCKERHUB_TOKEN
The credentials for your private Docker registry (in this case, DockerHub).
APTIBLE_USERNAME
and APTIBLE_PASSWORD
The credentials for the robot account created to deploy to Aptible.
Configuring the Workflow
Additionally, you will need to set some environment variables within the GitHub Actions workflow:
IMAGE_NAME
The Docker image you wish to deploy from your Docker registry.
APTIBLE_ENVIRONMENT
The name of the Aptible environment acting as the target for this deployment.
APTIBLE_APP
The name of the app within the Aptible environment we are deploying with this workflow.
Configuring the Workflow
Finally, you must configure the workflow to deploy your application to Aptible:
Configuring the Environment
You also need to set environment variables on your project with the name of your Aptible environment and app, in APTIBLE_ENVIRONMENT and APTIBLE_APP, respectively. You can add these to your project using environment variables on the Travis CI dashboard.
To define how the Docker image is built and deployed, you’ll need to set a few additional variables:
APTIBLE_USERNAME
and APTIBLE_PASSWORD
The credentials for the robot account created to deploy to Aptible.
APTIBLE_DOCKER_IMAGE
The name of the Docker image you wish to deploy to Aptible.
If you are using a private registry to store your Docker image, you also need to specify credentials to be passed to Aptible:
APTIBLE_PRIVATE_REGISTRY_USERNAME
The username of the account that can access the private registry containing the Docker image.
APTIBLE_PRIVATE_REGISTRY_PASSWORD
The password of the account that can access the private registry containing the Docker image.
Configuring the Deployment
Finally, you must configure the workflow to deploy your application to Aptible:
Let’s break down how this works. The script for the build-and-test
stage does what it says on the label: It builds our Docker image as runs tests on it, as we’ve defined in a Makefile.
Then, script from the push
stage pushes our image to the Docker registry:
Finally, it installs the Aptible CLI in the Travis CI build environment, logs in to Aptible, and deploys your Docker image to the specified envrionment and app:
From there, you can review our resources for Direct Docker Image Deployments!