Deploy an Example App

This guide will walk you through the process of deploying an example App on Aptible.

📘 Want to skip the reading? Deploy this starter template directly from the Aptible Dashboard.

By the end of this tutorial, you'll be familiar with the Aptible Dashboard, Aptible CLI, and the Twelve-Factor App model.

The Demo App you'll deploy in this guide is a small, anonymous "message board" app written in Python, comprising multiple services: a web server, a background worker, a PostgreSQL Database, and a Redis instance. This app will allow you to post and view short messages, and the deployment process is designed to feature a diverse set of Aptible features.

The steps in this tutorial will use both the Dashboard and the CLI at various points, demonstrating how you can interact with your Aptible app.

Prerequisites

This guide has the following prerequisites:

• Install Git
• Install the Aptible CLI
• Add an SSH public key to your Aptible user account

Clone the Repo

Clone the deploy-demo-app to your local machine.

Create an App

To deploy your code on Aptible, you'll begin by creating an App. When you launch your app on Aptible, it is deployed as one or more service Containers.

📘 While this guide demonstrates how apps can be created from the Aptible Dashboard, it is also possible to create an app via the CLI command aptible apps:create. We will demonstrate CLI usage later in the tutorial.

Let's begin by creating an app on the Aptible Dashboard:

1. Under the Apps tab of your environment on the Aptible Dashboard, click on Create App.
2. Provide a handle for the app (such as demo-app), then click Save App.

Configure Your Local Environment

After your app has been created, Aptible will provide a Git remote address for your repo. Copy this address, and in your local clone of the Demo App repository, run this command to set the aptible remote:

# Substitute $GIT_REMOTE with the URL copied from the Aptible dashboard.
git remote add aptible "$GIT_REMOTE"

For the rest of this guide, we'll reference your app's handle as $APP_HANDLE and your Git remote as $GIT_REMOTE; if you want to make it easier to copy and paste commands from this tutorial, you can set these variables in your local environment:

# Set to your app's handle
export APP_HANDLE="demo-app"
# Substitute the URL for your Git remote below
export GIT_REMOTE="git@beta.aptible.com:YOUR-ENV-NAME/YOUR-APP.git"

Deploy the App

After you have configured your local environment with the Git remote from Aptible, you are ready to push your code to Aptible. Run git push in your local repository to push the branch to Aptible:

git push aptible master

When you push to Aptible, deploy logs will stream to your terminal. These will show you the progress of your deployment and help you to troubleshoot if anything goes wrong.

📘 App deployments can only be initiated via the CLI.

Now that your app is deployed to Aptible, you should see on your Dashboard two running Services: web and background.

If you would like to understand how these services are defined, have a look at the Procfile contained in your local clone of the Demo App repository.

Create a Default Endpoint

Now that your app is running, you need to expose its running web process with an Endpoint to be able to receive web requests. Each endpoint defines an Elastic Load Balancer and one or more proxies that provide SSL termination; these expose your application to the web and keep your traffic secure, respectively.

On the Dashboard, select your app and navigate to the Endpoints tab. Create your first endpoint with all of the default settings, and click Save Endpoint. This configuration will use the Default Domain of *.on-aptible.com to route traffic to your application. Later on, you can create your own endpoint with a Custom Domain.

📘 This section demonstrates how an Endpoint can be created with the Aptible Dashboard, but it is also possible to create the endpoint using the CLI command aptible endpoints:https:create.

After the endpoint is provisioned, the configured hostname will be available to accept traffic. While you are waiting for the underlying infrastructure to be provisioned, you can continue following along with this guide.

Create Databases

Because app containers on Aptible are ephemeral, this demo uses two Databases to provide persistent storage:

• PostgreSQL is used to store relational data, and
• Redis is used as a queue for the asynchronous worker process.

📘 Like everything else in this guide, databases may be provisioned from either the Dashboard or the CLI. In this section, we'll demonstrate how you can use the CLI to provision databases, so make sure you have the Aptible CLI installed and that you have logged in with aptible login.

If you would like to be able to copy and paste commands as you follow along, set environment values for the $DB_HANDLE and the $REDIS_HANDLE environment variables:

export DB_HANDLE="demo-postgres"
export REDIS_HANDLE="demo-redis"

Provision the PostgresSQL Database

Now you are ready to create the PostgresSQL database for your app:

aptible db:create "${DB_HANDLE}" --type postgresql

As the aptible db:create command runs, deployment logs will stream to your local terminal. At the end of successfully provisioning the database, the command will return a connection string:

This is a Database Credential, and you'll need it later to configure your app. We'll refer to the credential via the environment variable $DATABASE_URL, which you should set in your local environment:

export DATABASE_URL="postgresql://aptible:abcdef123456@db-shared-us-east.aptible.in:28438/db"

Provision the Redis Database

Next, create a Redis database with the aptible db:create command:

aptible db:create $REDIS_HANDLE --type redis

Retrieve the secure rediss:// credentials from your Aptible Dashboard by selecting the newly-provisioned Redis database, and clicking the "Reveal Credentials" link. This credential specifies the app will connect over TLS, and it’s the one you should use for regulated or sensitive information. Don't worry, the PostgreSQL database you created earlier is secured by default!

We'll refer to this credential by the environment variable $REDIS_URL, which you can also set in your local environment:

export REDIS_URL="rediss://:abcdef123456@db-shared-us-east.aptible.in:21097"

Now that we have our databases provisioned, let's get them connected to our application.

Tell the Application About the Databases

📘 Note

To set environment variables for your deployment on Aptible, you must use the CLI.

The demo application follows the Twelve-Factor model, which calls for storing configuration in environment variables. This ensures that the configuration, which often includes secrets such as passwords or private keys, is not stored in the code repository.

For this demo, you will need to set the DATABASE_URL and REDIS_URL environment variables on the Aptible platform to the credential strings that were given to us by Aptible. To set these environment variables, you'll need to use the aptible config:set command.

Make sure the $APP_HANDLE, $DATABASE_URL, and $REDIS_URL environment variables have been set locally with their proper values. Then, you can share the configuration with your Aptible deployment:

aptible config:set --app "${APP_HANDLE}" DATABASE_URL="${DATABASE_URL}" REDIS_URL="${REDIS_URL}"

This will restart your app with the new variables set in the deployment environment!

❗️ Warning

For the REDIS_URL, be sure to use the "redis+ssl" credential, which specifies a URL with the protocol rediss://. This ensures your Redis connection is secured with TLS.

If you need to retrieve your credentials again for any database, you can find them on the Aptible Dashboard.

Run Database Migrations

Our database starts out empty, so we will need to add a table for our app's data model. This would normally be accomplished through a migration script created specifically for the application, so we have bundled a migration script with the demo app.

Using the command aptible ssh, you can create an ephemeral SSH session. As with the standard OpenSSH command you're likely used to using, it's possible to specify, from your local terminal, what shell command should be run on the remote host.

Let's use the aptible ssh command to run python migrations.py for our deployed app:

Once logged in, run python migrations.py from the interactive shell:

❯ aptible ssh --app "${APP_HANDLE}" python migrations.py

INFO -- : Starting App execute operation with ID: 41025547
INFO -- : STARTING: Schedule ephemeral session
INFO -- : COMPLETED (after 0.71s): Schedule ephemeral session
INFO -- : STARTING: Launch ephemeral container
INFO -- : WAITING FOR: Launch ephemeral container
INFO -- : COMPLETED (after 2.01s): Launch ephemeral container
INFO -- : STARTING: Commit ephemeral container in API
INFO -- : COMPLETED (after 0.07s): Commit ephemeral container in API

(8ミ | INFO: === Aptible SSH ===
(8ミ | INFO: Ephemeral container for: demo-app-demo/demo-app
(8ミ | INFO: Remember: you are NOT logging in to an existing app container
(8ミ | INFO: For more information, see: https://www.aptible.com/documentation/enclave/reference/apps/ssh-sessions.html

(8ミ | WARN: This session may be recorded by your organization.

(8ミ | INFO: Executing command: python migrations.py
(8ミ | INFO: (pass a command to aptible ssh to customize)

INFO:root:Attempting DB initialization...
INFO:root:Done!
Connection to ip-10-183-87-234.ec2.internal closed.
Connection to bastion-layer-shared-us-east-1-teal.aptible.in closed.

Alternatively, if you prefer to use an interactive SSH session, leave python migrations.py off of your aptible ssh command. Without a command to run non-interactively, an interactive session will be established:

❯ aptible ssh --app "${APP_HANDLE}"

INFO -- : Starting App execute operation with ID: 41025534
INFO -- : STARTING: Schedule ephemeral session
INFO -- : COMPLETED (after 0.68s): Schedule ephemeral session
INFO -- : STARTING: Launch ephemeral container
INFO -- : WAITING FOR: Launch ephemeral container

INFO -- : WAITING FOR: Launch ephemeral container
INFO -- : COMPLETED (after 16.61s): Launch ephemeral container
INFO -- : STARTING: Commit ephemeral container in API
INFO -- : COMPLETED (after 0.43s): Commit ephemeral container in API

(8ミ | INFO: === Aptible SSH ===
(8ミ | INFO: Ephemeral container for: demo-app-demo/demo-app
(8ミ | INFO: Remember: you are NOT logging in to an existing app container
(8ミ | INFO: For more information, see: https://www.aptible.com/documentation/enclave/reference/apps/ssh-sessions.html

(8ミ | WARN: This session may be recorded by your organization.

(8ミ | INFO: Executing command: /bin/bash
(8ミ | INFO: (pass a command to `aptible ssh` to customize)

root@0408c3108050:/app#

Test the App!

All the necessary configuration is done. That was it!

Now that you have finished configuring your app, you should be able to insert and retrieve messages from the system by visiting its endpoint URL.

If you wish to look behind the scenes, you can follow the application logs live with the aptible logs ${APP_HANDLE} command. This will show you stdout and stderr of the app container:

aptible logs --app "${APP_HANDLE}"

Continue Learning

We've designed the Demo App to showcase many of the features that Aptible offers, some of which are included in the Setup Checklist that you can find in the application itself.

There are many other Aptible features you can experiment with using this demo application, some of which are included in the Setup Checklist in the application itself. After you complete each task in the checklist, the task will be checked off so that you can be sure you followed the right steps.

If you want to learn how to complete the last few tasks on the Setup Checklist, or if you'd just like to better understand the information covered in this tutorial, have a look at these additional articles:

• Automate your database migrations
• Scale your App
• Redirect all request to HTTPS
• Change your Endpoint's default timeout
• Create a custom HTTPS endpoint using your own domain
• Deploy directly from a Docker image