How To Use the Dokku One-Click DigitalOcean Image to Deploy a Python/Flask App

Note: The Dokku project has changed significantly since this guide was written. The instructions below may not reflect the current state of the Dokku project.

Introduction

A significant hurdle in developing an application is providing a sane and easy way to deploy your finished product. Dokku is a Platform as a Service solution that enables you to quickly deploy and configure an application to a production environment on a separate server.

Dokku is similar to Heroku in that you can deploy to a remote server. The difference is that Dokku is built to deploy to a single, personal server and is extremely lightweight. Dokku uses Docker, a Linux container system, to easily manage its deployments.

In this guide, we will cover how to deploy a Python/Flask app with Dokku using the DigitalOcean Dokku one-click installation image.

Step One — Create the Dokku Droplet

The first thing we need to do is create the VPS instance that contains our Dokku installation. This is simple to set up using the DigitalOcean Dokku application.

Click on the “Create” button to create a new droplet:

Name your droplet, and select the size and region that you would like to use:

Scroll down and click on the “Applications” tab. Select the Dokku application image:

Select your SSH keys if you have them available. If you do not already have them configured, now is a great time to create SSH keys to use with your DigitalOcean droplets. This step will help you later.

Click “Create Droplet”. Your Dokku VPS instance will be created.

Once your droplet is created, you should set up your domain name to point to your new Dokku droplet. You can learn how to configure domain names with DigitalOcean here.

Step Two — Access the Droplet To Complete Configuration

You can complete your Dokku configuration by accessing your VPS from a web browser.

If you configured a domain name to point to your Dokku installation, you should visit your domain name with your favorite web browser. If you do not have a domain name configured, you can use your droplet’s IP address.

You will be given a simple configuration page. There are a few parts that you need to configure here.

First, check that the Public Key matches the computer that you will be deploying from. This means that if your project is on your home computer, you should use the public key that corresponds to that set up.

If you selected multiple SSH keys to embed during droplet creation, only the first will be available here. Modify it as necessary.

Next, modify the Hostname field to match your domain name. Leave this as your IP address if you do not have a domain name configured.

Choose the way that you want your applications to be referenced. By default, the application will be served like this:

http://your_domain.com:app_specific_port_number

If you select the “Use virtualhost naming for apps” check box, your apps will be accessible using a virtualhost instead:

http://app_name.your_domain.com

Click the “Finish Setup” button to complete the configuration.

Step Three — Deploy a Sample Flask Application to your Dokku Droplet

At this point, your Dokku droplet is configured and ready to start receiving git repositories, which it will deploy automatically.

This process is as simple as pushing a local git repository to your Dokku droplet.

What Requirements do Dokku Apps Have?

Besides functioning in its own right, for your flask application to be deployed successfully with Dokku (or Heroku, for that matter), it needs to have two components to know how to deploy the app.

Procfile: A file called “Procfile” is required to be in the root application directory. The purpose of this file is to specify how the application should be run once deployed.

Basically, it specifies the commands necessary to start the web process for your project.

For many Flask projects, this can be as simple as:

web: gunicorn app_name:app

Dependencies File: You need to include a file that will tell Dokku which libraries and applications are needed to run your app. This can either be a requirements.txt file or a setup.py file.

If you do not already have a requirements.txt file and you’ve been using Python’s pip installer to get your dependencies, you can try to auto-generate a requirements.txt file by issuing this command:

pip freeze > requirements.txt

This works best if you have built your app using virtualenv to isolate your application environment.

Deploy a Flask App Database

If the application you are deploying does not use a database, you can skip to the next section. The sample app that we will deploy will use a database.

Dokku and Heroku both adhere to a philosophy that application resources, such as databases, should be handled as separate entities so that they can easily be swapped out without changes to the application code.

Because of this, databases must be deployed separately and then associated with the application. This makes it easy to change a backend if there are problems.

Dokku handles databases through a plugin system. If your application relies on a database, you can install the related Dokku plugin, which will handle the database deployment.

We will deploy a PostgreSQL database for our application. Log into your Dokku droplet as root.

Change to the Dokku plugin directory:

cd /var/lib/dokku/plugins/

We will clone the PostgreSQL plugin from GitHub. You can see a list of available Dokku plugins here.

git clone https://github.com/Kloadut/dokku-pg-plugin.git postgresql

After cloning the files, we need to tell Dokku to install all available plugins:

dokku plugins-install

You now have the Dokku PostgreSQL installed. We will deploy a database instance to associate with our application. We can see that with our plugin installation, the available commands for Dokku have been modified:

dokku help
config <app> display the config vars for an app config:get <app> KEY display a config value for an app config:set <app> KEY1=VALUE1 [KEY2=VALUE2 ...] set one or more config vars config:unset <app> KEY1 [KEY2 ...] unset one or more config vars delete <app> Delete an application help Print the list of commands logs <app> plugins-install Install active plugins plugins Print active plugins postgresql:create <app> Create a PostgreSQL container postgresql:delete <app> Delete specified PostgreSQL container postgresql:info <app> Display database informations postgresql:link <app> <db> Link an app to a PostgreSQL database postgresql:logs <app> Display last logs from PostgreSQL container run <app> <cmd> Run a command in the environment of an application url <app>

We have some additional PostgreSQL commands available. We will have to decide right now what we want to call our application. This will have implications on the URL we will access our app from if we are using virtualhost naming.

When you know what you’d like to call your application, you can create the associated database by typing:

dokku postgresql:create app_name

Your database will be created and you can now deploy your application easily.

Deploy your Flask Application

To avoid having to build an entire application complex enough to use a database, we will use a sample found on GitHub. We will clone the Flask-Social example application.

On the computer that has the RSA key that matched the one you deployed with Dokku, we will clone the repository. You will need to install git on the computer. The installation procedures will differ based on the operating system, but you can get help here.

Change into the directory where you want the project directory. Type this command:

git clone https://github.com/mattupstate/flask-social-example.git

Change into the directory that was created:

cd flask-social-example

Now, we need to add a remote that references our Dokku server and the application name we chose earlier:

git remote add name_for_remote dokku@your_domain.com:app_name

A few things to note here. The name_for_remote can be anything you want. It is simply how you’re referencing your Dokku server. In many cases, it would be sensible to name it dokku.

Another thing to be sure to get right is the app_name. This must match the app_name you chose during the database creation. It is the only way that Dokku will know to tie these two pieces together.

Now, all you need to do to put your application on the Dokku server and automatically deploy it is push the repository:

git push name_for_remote master

Your application will be deployed to Dokku. When the deployment is complete, you will a message similar to this:

-----> app_name linked to postgresql/app_name database -----> Deploying app_name ... -----> Cleaning up ... =====> Application deployed: http://app_name.your_domain.com To dokku@your_domain.com:app_name * [new branch] master -> master

If you go to the URL that you were given, you should see the sample app:

http://app_name.your_domain.com

Conclusion

By now, you should have successfully deployed your first Python/Flask application on Dokku. Further application deployments should be easy on the same droplet.

Python deployments on Dokku are easy if you keep the following points in mind:

• Build your application dependencies using pip.
• Create a requirements.txt file or setup.py file so that Dokku can build your application dependencies
• Include a Procfile so that Dokku knows how to start your application
• Deploy your database backend separately using the Dokku plugin system.

Once you get a handle on these few points, deploying applications to your own VPS server can happen rapidly and automatically. Dokku can help make your life easier by taking the headache out of deployment

Originally published at www.stratotechnology.com.