Deploying Python projects with Docker

Using Docker we can deploy a Python project along with all his dependencies in completely isolated containers, exposing only the strictly necessary ports for running our apps. The only packages we need to install in the server are Docker and SSH, this way we will keep our production server in mint conditions.

Here you will learn how to deploy your Python project to the production server using docker, and how to configure and link together all these components:

This is just a docker tutorial, for harder deployments when there is more than one production server involved you should combine docker with some orchestration software like Ansible, Puppet, Chef or Salt.

For this guide I am using a Macbook Pro (OS X El Capitan) and a Ubuntu Server (Ubuntu Trusty 14.04.3) running in a VirtualBox. We will use the Ubuntu Server installed in the VirtualBox as a fake production server, and we will connect to it through ssh to perform the deployments.

Installing VirtualBox + Ubuntu server

You will find here all information regarding the VirtualBox installation.

Create Virtual machine

After installing VirtualBox in your system you should create a new Virtual machine with a Linux distribution (I am using Ubuntu 64-bit).

Configure and install Linux in your Virtual machine

Once the Virtual machine has been created, you need to download a linux distribution (I got Ubuntu Server 14.04.3). Then go to VirtualBox menu: Settings -> Storage and click on The CD icon, browse for the linux image you have downloaded. You should mark also the “Live CD/DVD” option. This way it will use the linux image as a Live CD and the next time you initialize the Virtual machine you should get the Linux installation screen. Go ahead, install Linux.

Note.- If after installation you are still getting the installation screen, go to Menu -> System -> Boot Order and place the Hard drive before the CD. Otherwise it will try to Initialize from the CD every time you run the Virtual machine.

Configure VirtualBox to allow SSH connection

We just need to open our Ubuntu’s VirtualBox settings, go to Network -> Port Forwarding, and add the following rule:

Name Protocol Host IP Host Port Guest IP Guest Port
SSH TCP 3022 22

We will also need to install the SSH server in our Virtual machine. Just initialize the Ubuntu server normally and install the required packages. Use apt-get update first for fetching the latest versions of all packages:

sudo apt-get update
sudo apt-get install openssh-server

Now we should be able to connect to the Virtual machine using port 3022 and your user created during the Ubuntu installation.

ssh -p 3022 [email protected]

Install Docker in the VirtualBox server

For installing Docker in the Ubuntu server please follow this instructions from Docker documentation.
Once it is installed add your user to the docker group. So you don’t need to write sudo every single time you are using docker:

sudo usermod -aG docker my_user_name

Create folders for releases and docker files

We will need to add some folders for storing the releases and docker files. The docker files will be stored in a folder called docker inside the data folder, you will understand why afterwards. I created these folders in /var/data/, but the location is really up to you.

sudo mkdir /var/data
sudo mkdir /var/data/releases
sudo mkdir /var/data/docker
sudo mkdir /var/data/docker/elasticsearch
sudo mkdir /var/data/docker/cassandra
sudo mkdir /var/data/docker/postgres
sudo mkdir /var/data/docker/postgres/data
sudo mkdir /var/data/docker/nginx
sudo mkdir /var/data/docker/redis
sudo mkdir /var/data/docker/app

Now we change the group of this folders to docker and add write permissions to the group members. This way we will be able to use the scp command for creating files inside these folders without getting permission errors.

sudo chgrp -R docker /var/data
sudo chmod -R 0775 /var/data

This will add the group docker to all new files created within the directory:

sudo chmod -R g+s /var/data

Exporting Python project to the Production server

In this tutorial I am using a Pylons/Pyramid project, but the release process should be fairly similar in Bottle, Flask, Django, Falcon or any other frameworks. I am assuming that everybody knows how to create releases with Git. So I will try to be brief here, I use the Gitflow Workflow, I am creating tags for each release in the master branch. All dependencies of the project should be defined in the file requirements.txt, this file is automatically generated in the root folder of the project when running pip freeze:

pip freeze > requirements.txt

So you must be sure that this file is up to date in the release branch before going any further.

Exporting App

Using git archive we can export our app in a gzip file. In this case I am exporting the project using the tagged branch 1.0.0:

git archive 1.0.0 --format=tar | gzip > /tmp/my_app.tar.gz

Copy app to the Production server:

scp -P 3022 /tmp/my_app.tar.gz [email protected]:/var/data/releases/1.0.0/my_app.tar.gz

Exporting database

We also need to export the database data, in postgres this can be achieved easily like this:

# Exporting all database data:
pg_dump my_db > /tmp/db_import.psql

Now we send the the file to the production server:

scp -P 3022 /tmp/db_import.psql your_u[email protected]:/var/data/docker/postgres/data/db_import.psql

Project, dependencies and database are now in the production server, so it is time to use Docker.

Creating docker files for the App

Now it’s time to connect to the production server and start creating our docker files.

ssh -p 3022 [email protected]

The folder /var/data/docker will be in charge of building our releases, it contains 6 folders: elasticsearch, nginx, app, postgres, cassandra, redis. Each of theses folders will contain at least one docker configuration file which will take care of creating the corresponding component along with his respective configuration.

Copy app and create initialization script

We start with our app, first thing we need is to get a fresh copy of the current release located at /var/data/releases/1.0.0 and place it in the /var/data/docker/app folder. Don’t use symbolic links because they are not supported in Docker for good.

cp /var/data/releases/1.0.0/app.tar.gz /var/data/docker/app/app.tar.gz

Now we add the docker initialization script using our favorite text editor:

vim /var/data/docker/app/

Add the following content:

set -e

if [ "$1" = 'uwsgi' ]; then
	. /env/bin/activate;
	exec gosu www-data "$@"

exec "$@"

Maybe you are wondering what is the gosu thing, it’s a command very extended in the docker world, similar to sudo but with better signal handling. Basically it will execute the commands provided to the script using the www-data user.

Creating the app docker file

Create the docker file:

vim /var/data/docker/app/my_app.docker

Write the docker file:

# my_app.docker
# Use Ubuntu Trusty v14.04.3
FROM ubuntu:14.04.3
# Get gosu, we will use it in the entrypoint instead of sudo.
RUN gpg --keyserver --recv-keys B42F6819007F00F88E364FD4036A9C25BF357DD4
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates wget && rm -rf /var/lib/apt/lists/* \
	&& wget -O /usr/local/bin/gosu "$(dpkg --print-architecture)" \
	&& wget -O /usr/local/bin/gosu.asc "$(dpkg --print-architecture).asc" \
	&& gpg --verify /usr/local/bin/gosu.asc \
	&& rm /usr/local/bin/gosu.asc \
	&& chmod +x /usr/local/bin/gosu \
	&& apt-get purge -y --auto-remove ca-certificates wget
# Refresh all packages, install virtualenv and all the required packages.
RUN apt-get update && apt-get install -qy \
    build-essential python3-dev libev4 libev-dev libpq-dev python-virtualenv openssl libffi-dev libssl-dev libpcre3 libpcre3-dev
# Python 3.4 is already installed in the current Ubuntu version,
# so we just need to create a virtual environment.
RUN virtualenv -p /usr/bin/python3.4 /env
# Deploy application in the app folder
ADD app.tar.gz /var/www/my_app
# Add group and permissions for the uwsgi server (Running with the user: www-data)
RUN chown -R www-data:www-data /var/www/my_app\
	&& chmod -R 775 /var/www/my_app/server /var/www/my_app/logs\
	&& chmod 770 /var/www/my_app/production.ini  /var/www/my_app/development.ini
# Activate the Python 3.4 environment and install all required pip packages.
RUN . /env/bin/activate; \
    pip install pip==7.1.2 \
    && pip install setuptools==18.4 \
    && pip install -r /var/www/my_app/requirements.txt
# Add the Docker initialization script for running UWSGI
# Set root to the app directory.
WORKDIR /var/www/my_app
# Create a volume for the app directory. It will be used by nginx
# for accessing the static files and connecting to the uwsgi server.
VOLUME /var/www/my_app
ENTRYPOINT ["/", "uwsgi"]
CMD ["--ini-paste", "/var/www/my_app/production.ini"]

This docker file is based on a linux ubuntu:14.04.3, It installs all the required libraries and a virtualenv where our app will be executed. The ADD command extract all files from our compressed app.tar.gz to the folder /var/www/my_app (inside the docker context) and changes the ownership of the app folder /var/www/my_app to the user www-data, this is really important because the uwsgi server will run under the www-data user. Otherwise it will not be able to reach the unix socket and the connection with the nginx server will fail.
It also add 770 permissions to some files that could contain sensitive information like the production.ini. Afterwards the script will install all pip dependencies based on the file requirements.txt.
COPY will add the initialization script to docker so it can be used as the entrypoint, meaning that this script will be executed every time we run the docker container.
The VOLUME instruction, creates a volume for the app directory, this way we will be able to share the app between docker containers. For example nginx will also use this volume for connecting through the unix socket (/var/www/my_app/server/uwsgi.socket) and for serving static content.
Finally The ENTRYPOINT and CMD set the default params that will be executed when we run the container, executing the uwsgi server:

uwsgi --ini-paste /var/www/my_app/production.ini

uWSGI configuration

This is the uwsgi configuration in the production.ini file.

uid = www-data
gid = www-data
chmod-socket = 664
chdir = /var/www/my_app
socket = /var/www/my_app/server/uwsgi.sock
master = true
workers = 1
harakiri = 60
harakiri-verbose = true
limit-post = 65536
post-buffering = 8192
pidfile = ./server/
listen = 128
max-requests = 1000
reload-on-as = 128
reload-on-rss = 96
no-orphans = true
log-slow = true
virtualenv = /env
thunder-lock = true

It is important that the uid and gid are www-data because the folder containing the socket is owned by this user. There is no need to use the daemonice option, docker will take care of running the app and collecting the logs.

Creating docker files for Postgres

First we create the initialization script:

vim /var/data/docker/postgres/data/

That will take care of creating the database and add restricted roles for the different users.

psql --username deployer <<-EOSQL
	CREATE DATABASE "my_db_production" WITH OWNER deployer TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'en_US.UTF-8' ;

psql -U deployer my_db_production < /docker-entrypoint-initdb.d/db_import.psql

psql --username deployer <<-EOSQL
	# Create role write with basic read/write permissions:
	# Create user "production" and grant all privileges of the role "write" to him.
	GRANT write TO production;

I have used the deployer user with root privileges for taking care of creating the database and perform all the pertinent modifications. Looking at the last part of the file you may wonder why I added those database users. It is a good practice creating database users with limited privileges. If you are using postgres, you can follow this approach, I have created a role called write with permission only for reading and writing on existing tables, but they cannot modify the database structure whatsoever:

/* We also need to add sequence permissions. The sequences are the objects generating unique numeric identifiers (usually for primary keys). */

After we have applied the role write to the user production, who will inherit all the privileges (You should use the user production in your app configuration for connecting to the database):

/* Create a role called production with a secret password */
/* Add Write's privileges to production user */
GRANT write TO production;

We also add the file db_import.psql to the same folder:


which contains the whole schema of hour database.

Writing the postgres docker file

Lets create the file:

vim /var/data/docker/postgres/postgres.docker

This is the content:

# postgres.docker
# Use postgres version 9.4.5
FROM postgres:9.4.5
ENV POSTGRES_PASSWORD your_secret_paswword
COPY data/ /docker-entrypoint-initdb.d/

The script imports postgres v9.4.5 and creates a super user with the data defined in POSTGRES_USER and POSTGRES_PASSWORD. In this case I am creating the user deployer with password your_secret_paswword. The last steps just copies the scripts db_import.psql and within the folder /docker-entrypoint-initdb.d inside the docker container. This folder has the peculiarity of executing all the .sh files within the directory during initialization.

Creating docker files for Nginx

Nginx is the proxy server that will send all http/https requests to the uWSGI server.

Create config file

We will need to modify the default Nginx configuration for setting the correct paths to our application, configure the unix socket, ETC. This file will be copied by the nginx.docker file overwriting the default configuration.

vim /var/data/docker/nginx/nginx.conf

This is the content of my nginx.conf file:

# I strongly recommend to use "www-data" as the nginx and uWSGI user.
# This way we will avoid permission issues when connecting through  unix sockets.
user  www-data;
worker_processes  1;

error_log  /var/log/nginx/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

pid /var/run/;

events {
    worker_connections  1024;

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
    #                  '$status $body_bytes_sent "$http_referer" '
    #                  '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    gzip  on;
    gzip_http_version 1.0;
    gzip_proxied      any;
    gzip_min_length   500;
    gzip_disable      "MSIE [1-6]\.";
    gzip_types        text/plain text/xml text/css

    # Configuration for Nginx
    server {
        listen       80;
        server_name  localhost;
        charset utf-8;
        #access_log  logs/host.access.log  main;
        # Settings to by-pass for static files
        location ^~ /static/  {
            root /var/www/my_app/my_app;

        # Serve a static file (ex. favico) outside static dir.
        location = /favico.ico  {
            root /var/www/my_app/my_app/static;

        location / {
            uwsgi_pass  unix:///var/www/my_app/server/uwsgi.sock;
            include     uwsgi_params;

        #error_page  404              /404.html;

        # redirect server error pages to the static page /50x.html
        error_page   500 502 503 504  /error.html;
        location = /error.html {
            root   /var/www/my_app/my_app/static/page;

First we set the Nginx user to www-data (same way as we did with uwsgi), this way we assure that there won’t be permission issues when connecting through the unix socket. The line location ^~ /static/ is just a bypass, this way Nginx will load the static files directly from the filesystem without making unnecessary calls to the uWSGI server.
Note that you may need to change these paths according to your app structure.

Writing the nginx docker file

Lets create the file:

vim /var/data/docker/nginx/nginx.docker

With the following content:

# nginx.docker
# Use nginx
FROM nginx:1.9.5

# Update nginx configuration
COPY nginx.conf /etc/nginx/nginx.conf

This docker file simply collects the nginx v1.9.5 installed in a lightweight Debian Linux distribution and applies the Nginx configuration we created in the previous step.

Creating docker files for Elasticsearch

Let’s create the docker file for the search engine:

vim /var/data/docker/elasticsearch/elasticsearch.docker

Content of the file:

# elasticsearch.docker
# Use elasticsearch 1.7.3
FROM elasticsearch:1.7.3
RUN /usr/share/elasticsearch/bin/plugin install license
RUN /usr/share/elasticsearch/bin/plugin install marvel-agent

This docker file simply retrieves Elasticsearch 1.7.3 installed in a lightweight Debian distribution and also installs Marvel which is an Elasticsearch monitoring tool.

Creating docker files for Redis

For Redis we don’t really need a docker file, we will create the Redis container using the default image: redis:3.0.5.

Creating docker files for Cassandra

Add Cassandra’s docker file:

vim /var/data/docker/cassandra/cassandra.docker

Content of the file:

# cassandra.docker
# Use Cassandra version 2.2.3
FROM cassandra:2.2.3

This docker file retrieves Cassandra 2.2.3 installed in a lightweight Debian distribution and sets the cluster name and snitch configuration. You can learn more about how to configure Cassandra here.

Building the docker images

Now it is time to create the images out of our docker files. I will use this nomenclature my_app/component_name for all components, for instance elasctisearch image will be created as my_app/elasticsearch.

Build the app

For building the app we just need to run the docker build command at the root directory of the docker app.

cd /var/data/docker/app
docker build -t my_app -f my_app.docker .;

Build Postgres

Building the docker files is pretty much the same for all docker files. Just go to the root directory of each docker component and execute docker build.

cd /var/data/docker/postgres
docker build -t my_app/postgres -f postgres.docker .;

Build Nginx

cd /var/data/docker/nginx
docker build -t my_app/nginx -f nginx.docker .;

Build Elasticsearch

cd /var/data/docker/elasticsearch
docker build -t my_app/elasticsearch -f elasticsearch.docker .;

Build cassandra

cd /var/data/docker/cassandra
docker build -t my_app/cassandra -f cassandra.docker .;

Check the new images

You can see all the images created with the command:

docker images

Run the components/Creating containers

Having all the images already in place now we can create the containers for each of the components. The app and Nginx will be created last respectively, because the app relies on the others containers and Nginx needs the volume /var/www/my_app defined in app to run. Once the containers are created you can display them using docker ps.
If you have any problem running containers just check the logs.

Run Postgres

For creating the Postgres database container just run:

docker run --name my_app_postgres -d my_app/postgres

The name is actually up to you, but it’s needed for linking the containers afterwards.

Now that the Postgres database is running you can connect to the PSQL console at any time:

docker run -it --link my_app_postgres:postgres --rm my_app/postgres sh -c 'exec psql -h "$POSTGRES_PORT_5432_TCP_ADDR" -p "$POSTGRES_PORT_5432_TCP_PORT" -U deployer'

This will connect to the database using the deployer user who has superuser privileges. The –rm option is just for creating a temporal container for accessing the console. It will be deleted when closing the console.

Run Elasticsearch

Create Elasticsearch container:

docker run --name my_app_elasticsearch -d my_app/elasticsearch

Run Cassandra

Create Cassandra container:

docker run --name my_app_cassandra -d my_app/cassandra

If this is the first time you run the container and you want to access the cqlsh console for adding default keyspaces and tables, this could be a good moment. If you just created the container you may need to wait a few seconds for Cassandra initialization, then run this command:

docker run -it --link my_app_cassandra:cassandra --rm my_app/cassandra cqlsh cassandra

The –rm option is just for creating a temporal container for accessing the console. It will be deleted when closing the console.

Run Redis

Create Redis container:

docker run --name my_app_redis -d redis:3.0.5

Run the App

Now that we have all the required containers in place we can run the app and link it to the components.

docker run --name my_app:1.0.0 --link my_app_redis:redis --link my_app_elasticsearch:elasticsearch --link my_app_cassandra:cassandra --link my_app_postgres:postgres -d my_app

There is a lot of magic going on here. First it’s creating our app container tagged with the version 1.0.0 (Our release). Then is linking all the existing containers to the app. What do you mean linking? If you look at the containers they all have a colon “:” followed by a name. For example in Redis my_app_redis:redis, the name following the colon is an alias that will be created as a domain inside our app container. For example if we access to the app container and take a look at the /etc/hosts file, we should see something like this:	postgres 4e70c95bb61a my_app_postgres	redis e39bcae5be48 my_app_redis	cassandra e3d756eb63f1 my_app_cassandra	elasticsearch cfc93af8c3b4 my_app_elasticsearch

Docker is dynamically associating the ip of each container to the aliases and names that we defined. You must take this into account when writing your production.ini file.
For instance if you have the following postgres connection defined in your development.ini :

postgresql://my_user:[email protected]/my_db

In the production.ini the ip must be replaced by the postgres domain defined in --link my_app_postgres:postgres


Do the same with all components.

Run Nginx

Now that the app container is running we need HTTP/HTTPS access to test it, and the Nginx server will take care of that. We cannot run Nginx the same way as we did with the other components because Nginx also needs to be accessed externally through HTTP/HTTPS. That’s why we use the -p (port) option, to define which port of our production server will be linked to the HTTP/HTTPS ports of the Nginx server.

docker run --name my_app_nginx -d -p -p --volumes-from my_app my_app/nginx

We have attached the addresses, of our production server to the ports 80(HTTP) and 443(HTTPS) respectively. This part: --volumes-from my_app is also extremely important, it is telling Nginx to use the volumes of my_app. Meaning that they are sharing the folder that contains our app /var/www/my_app. Otherwise Nginx would not be able to connect to uwsgi through the unix socket located at /var/www/my_app/server/.

Now we should be able to check if Nginx is working just typing these addresses in the web browser of the production server. But wait, there is no browser there… so lets try with curl:


You should see your app’s main page.

Testing with the web browser

Testing webpages with curl is a bit tiresome isn’t it? So we are going to link those addresses to our main computer, this way we can test it using our favorite web browser. We have done this already with the ssh ports, we just need to open our Ubuntu’s VirtualBox settings, go to Network -> Port Forwarding, and add the HTTP/HTTPS ports:

Name Protocol Host IP Host Port Guest IP Guest Port
SSH TCP 3022 22
HTTP TCP 32769 32769
HTTPS TCP 32768 32768

You may need to reboot the production server afterwards. Once the server is ready, the containers will be probably stopped. So we just need to reload them:

docker start my_app_elasticsearch
docker start my_app_redis
docker start my_app_cassandra
docker start my_app_postgres
docker start my_app
docker start my_app_nginx

And that’s all, just open any browser in your computer and check the address

Notice that in a real production server we won’t use strange addresses like I have used these ports because VirtualBox only allow forwarding ports higher than 1024. In a real production server we will probably use the domain name and the port 80 (HTTP) to redirect all HTTP requests to our App.

Some useful docker commands

Just some useful commands that your will end up using sooner or later.

Access to a running container

You can access to any running container through bash console using the following command:

docker exec -it container_name bash

Execute command into  a running container

You can execute any command within the container to any running container through bash console using the following command:

docker exec -it container_name echo "I'm inside the container!"

Display containers

The running containers can be displayed with ps:

docker ps

If you need to see all containers just add -a:

docker ps -a

Inspect containers

This command is extremely useful, it displays everything about the container; ip address, volumes, linked ports, environment variables, ETC.

docker inspect my_container_name

Docker logs

If you have any problems creating containers, or if every time you run a container is stopping automatically you should take a look at the logs:

docker logs my_container_name

Debug your image

When the container stops automatically for some error during the initialization, we can override the entry point for debugging purposes:

docker run -it --rm --entrypoint=/bin/bash my_image:latest

Delete all containers

Forces deletion of all existing containers.

docker rm -f $(docker ps -a -q)

Delete all images

Forces deletion of all existing images.

docker rmi -f $(docker images -q)

Delete unused volumes

Remove all unused local volumes. Unused local volumes are those which are not referenced by any containers

docker volume prune

Leave a Reply

Your email address will not be published. Required fields are marked *