Enclave Demo App

This step-by-step guide will walk you through deploying a demo application on the Enclave platform. It is intended to let you experience Enclave, even if you do not have an app ready to deploy. Specifically, it will familiarize you with the Aptible Dashboard , Aptible CLI, and the Twelve-Factor App model.

The Enclave Demo App you will be deploying is a simple, anonymous “message board” written in Python, designed to feature a diverse set of Enclave features. It is comprised of a web service, a background worker, a PostgreSQL database, and a Redis database to allow you to post and view short messages.

Each step will guide you to use the Dashboard and/or the CLI; some steps may specifically require one or the other, but none of them will require both.

Note

There are a few prerequisites needed to complete this guide:

  1. Install Git on your machine.
  2. Clone the enclave-demo-app repository to your local machine
  3. Add your SSH public key to your Aptible user account
  4. Install the Aptible CLI

Create an App

Note

You can can create an App from either the Dashboard or the CLI. In this guide you will create the App on the Dashboard, and later learn to use the CLI to create databases.

Apps are how you deploy your code on Enclave. Eventually, your Apps are deployed as one or more Containers. To get started, let’s create an App using your Aptible Dashboard:

  1. Click ‘Create App’
  2. Provide a handle for the App, and click ‘Save App’

Enclave will provide your App’s Git remote in return. Copy it, you’ll need it later. Going forward in this document, we’ll refer to the App’s handle as $APP_HANDLE, and its Git Remote as $GIT_REMOTE.

Deploy the App

Note

Deploying an App can only be done through the CLI.

You can deploy code to your new App by adding Aptible as a Git remote to your local code repository, and then use git push to push your code. On your machine, run the following commands in ‘enclave-demo-app’ folder:

git remote add aptible "$GIT_REMOTE"
git push aptible master

Deploy logs will stream to your terminal. They’ll be useful in case anything goes wrong to understand the cause of the failure.

Now that the App is deployed to Enclave, you should see on your Dashboard two Services running, they are named web and background:

You can find how these services are defined within the Procfile contained in the enclave-demo-app code repository.

See also

In the advanced section of this guide, you will also learn how to deploy directly from a prebuilt Docker image.

Create a Default Endpoint

Note

Creating Endpoints can only be done on the Dashboard.

Now that your App is running, you need to expose to the Apps web process with an Endpoint, so that it can receive web requests. Each endpoint is a combination of an Elastic Load Balancer, and one or more proxies that provide SSL termination, which in tandem expose and secure your application on the Internet.

On the Dashboard, select your App and navigate to the “Endpoints” tab. Since you do not yet have any endpoints defined, a dialog will present to create your first endpoint: simply accept all the defaults and click “Save Endpoint”! This endpoint will be created on the Default Domain of *.on-aptible.com. Later, in Advanced section of this guide, you can try your hand at creating an endpoint on your own Custom Domain.

The Endpoint hostname will become available once the Endpoint is provisioned. Feel free to continue with this guide while you wait, in our experience AWS can be quite slow in provisioning the ELB, and there’s plenty of Enclave you can explore while you wait!

Create Databases

Since App containers on Enclave are ephemeral, this demo application makes use of two Database types to provide persistent storage: PostgreSQL is used to store relational data, and Redis is used as a queue for the asynchronous worker process.

Note

Databases may be created from the Dashboard or the CLI, in this example we’ll learn to use the Aptible CLI, so be sure you have it installed and have logged in with the command aptible login.

Start by creating the PostgreSQL database for your App:

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

Make sure you set or substitute $DB_HANDLE with the database name of your choice.

The aptible db:create will return a connection string on success. This is a Database Credential. You’ll need it later to configure your App.

Going forward in this document, we’ll refer to the Credential as $DATABASE_URL.

Then, create a Redis database :

aptible db:create $REDIS_HANDLE --type redis

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

Tell the application about your databases

Note

Environment variables can only be set through 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 to the credential strings for the two databases you previously created. If you need to, you can retrieve the credentials for any database on the Aptible Dashboard.

On Enclave, you can set environment variables using the aptible config:set command as shown below. Make sure you set or substitute $APP_HANDLE, $DATABASE_URL, and $REDIS_URL with their proper values.

aptible config:set $APP_HANDLE DATABASE_URL="$DATABASE_URL" REDIS_URL="$REDIS_URL"

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. You need do nothing for the PostgresSQL database connection to specify a secure connection; TLS is the default connection method.

This will restart your app with the new environment variables, and you should then see in the demo app checklist that the variables have been set successfully!

Run Database Migrations

Since our database is currently empty, we will need to add a table which matches the demo application’s models. This can be done by running the initial migration included with the application.

Using the command aptible ssh you can create an ephemeral SSH session. Once logged in, run python migrations.py from the interactive shell:

$ aptible ssh --app $APP_HANDLE
(8ミ | INFO: Pulling app image: dualstack-v2-registry-i-bf53878f.aptible.in:46022/app-6163/e697ee0e-f19a-44d5-ace9-2c3040c15289
Login Succeeded

(8ミ | INFO: === Aptible SSH ===
(8ミ | INFO: Ephemeral container for: newenvironment/aptible-demo
(8ミ | INFO: Remember: you are NOT logging in to an existing app container
(8ミ | INFO: For more information, see: https://www.aptible.com/support/topics/cli/how-to-ssh-into-app/

root@71b990c4bf47:/app# python migrations.py
INFO:root:Attempting DB initialization...
INFO:root:Done!

Alternatively, you can run the migrations via an SSH session non-interactively, by specifying a shell command with aptible ssh :

aptible ssh --app $APP_HANDLE python migrations.py

See also

Now that you’ve mastered running migrations from an Aptible SSH session, check out Automating Database Migrations!

Try the app!

Now that you’ve completed the required setup, you should be able to insert and retrieve messages from the system. 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 Apps containers!

aptible logs --app $APP_HANDLE

Advanced - Self-paced Study

There are many other Enclave features you can experiment with using this demo application, some of which are included in the Setup Checklist in the application itself, so that you know when you’ve completed the task: