Docker Explained: How To Containerize Python Web Applications
This article is deprecated and no longer maintained.
The techniques in this article are outdated and may no longer reflect Docker best-practices.
The threat of having a web application hijacked and used for taking over the entire host is a vast and scary one. It has long been a challenge to keep things isolated from one another for enhanced security, especially if the applications belong to different clients. Many measures can be taken to prevent this unfortunate scenario, however, they are usually too costly (both on time and resources) or too complicated for most developers' or administrators' use cases.
In this DigitalOcean article, we'll talk about "containerizing" Python web applications in order to have them in very secure sandboxes, absolutely kept within their own environments (unless you explicitly "link" them to another). In order to achieve this, we'll see about creating a docker container to host a Python web application step-by-step, finally bootstrapping our build processes with a Dockerfile to fully automate it.
1. Docker in Brief
2. Installing Docker on Ubuntu
3. Basic Docker Commands
- Running the docker daemon and CLI Usage
- docker Commands
4. Building a Docker Container To Sandbox Python WSGI Apps
- Creating a Base Docker Container From Ubuntu
- Preparing the Base Container for the Installation
- Installing Common Python Tools for Deployment
- Installing The Web Application and Its Dependencies
- Configuring your Python WSGI Application
5. Creating the Dockerfile to Automatically Build the Image
- Dockerfile Basics
- Dockerfile Commands Overview
- Creating the Dockerfile
- Defining the Fundamentals
- Updating the Default Application Repository for Installations
- Installing the Basic Tools
- Base Installation Instructions for Python and Basic Python Tools
- Application Deployment
- Bootstrapping Everything
- Final Dockerfile
- Using the Dockerfile to Automatically Build Containers
Docker in Brief
The docker project offers higher-level tools, working together, which are built on top of some Linux kernel features. The goal is to help developers and system administrators port applications - with all of their dependencies conjointly - and get them running across systems and machines - headache free.
Docker achieves this by creating safe, LXC (i.e. Linux Containers) based environments for applications called docker containers. These containers are created using docker images, which can be built either by executing commands manually or automatically through Dockerfiles.
Note: To learn more about docker and its parts (e.g. docker daemon, CLI, images etc.), check out our introductory article to the project: docker Explained: Getting Started.
Installing Docker on Ubuntu (Latest)
With its most recent release (0.7.1. dating 5 Dec.), docker can be deployed on various Linux operating systems including Ubuntu / Debian and CentOS / RHEL.
Remember that you can quickly get started by using DigitalOcean's ready-to-use docker image built on Ubuntu 13.04.
We will quickly go over the installation process for Ubuntu (Latest).
Installation Instructions for Ubuntu
Update your droplet:
sudo aptitude update sudo aptitude -y upgrade
Make sure aufs support is available:
sudo aptitude install linux-image-extra-`uname -r`
Add docker repository key to apt-key for package verification:
sudo sh -c "wget -qO- https://get.docker.io/gpg | apt-key add -"
Add the docker repository to aptitude sources:
sudo sh -c "echo deb http://get.docker.io/ubuntu docker main\ > /etc/apt/sources.list.d/docker.list"
Update the repository with the new addition:
sudo aptitude update
Finally, download and install docker:
sudo aptitude install lxc-docker
Ubuntu's default firewall (UFW: Uncomplicated Firewall) denies all forwarding traffic by default, which is needed by docker.
Enable forwarding with UFW:
Edit UFW configuration using the nano text editor.
sudo nano /etc/default/ufw
Scroll down and find the line beginning with
Press CTRL+X and approve with Y to save and close.
Finally, reload the UFW:
sudo ufw reload
Basic Docker Commands
Before we begin working with docker, let's quickly go over its available commands to refresh our memory from our first Getting Started article.
Running the docker daemon and CLI Usage
Upon installation, the docker daemon should be running in the background, ready to accept commands sent by the docker CLI. For certain situation where it might be necessary to manually run docker, use the following.
Running the docker daemon:
sudo docker -d &
docker CLI Usage:
sudo docker [option] [command] [arguments]
Note: docker needs sudo privileges in order to work.
Here is a summary of currently available (version 0.7.1) docker commands:
Attach to a running container
Build a container from a Dockerfile
Create a new image from a container's changes
Copy files/folders from the containers filesystem to the host path
Inspect changes on a container's filesystem
Get real time events from the server
Stream the contents of a container as a tar archive
Show the history of an image
Create a new filesystem image from the contents of a tarball
Display system-wide information
Insert a file in an image
Return low-level information on a container
Kill a running container
Load an image from a tar archive
Register or Login to the docker registry server
Fetch the logs of a container
Lookup the public-facing port which is NAT-ed to PRIVATE_PORT
Pull an image or a repository from the docker registry server
Push an image or a repository to the docker registry server
Restart a running container
Remove one or more containers
Remove one or more images
Run a command in a new container
Save an image to a tar archive
Search for an image in the docker index
Start a stopped container
Stop a running container
Tag an image into a repository
Lookup the running processes of a container
Show the docker version information
Building a Docker Container To Sandbox Python WSGI Apps
After having installed docker on our VPS and having quickly gone over its commands, we are ready to start with the actual work to create our docker container running a Python WSGI Application.
Note: The following section will enable you to have a dockerized (containerized) Python WSGI web application. However, it is definitely not the recommended method due to its complexity and impracticability. It is here to offer you a chance to learn how to work with a live container and get familiar with the commands we will need to define later in the next section to automate the process.
Creating a Base Docker Container From Ubuntu
Using docker's RUN command, we will begin with creating a new container based on the Ubuntu image. We are going to attach a terminal to it using the -t flag and will have bash as the running process.
We are going to expose port 80 so that our application will be accessible from the outside. In future, you might want to load-balance multiple instances and "link" containers to each other to access them using a reverse-proxy running container, for example.
sudo docker run -i -t -p 80:80 ubuntu /bin/bash
Note: After executing this command, docker might need to pull the Ubuntu image before creating a new container for you.
Remember: You will be attached to the container you create. In order to detach yourself and go back to your main terminal access point, run the escape sequence: CTRL+P followed by CTRL+Q. Being attached to a docker container is like being connected to a new droplet from inside another.
To attach yourself back to this container:
List all running containers using "sudo docker ps"
Find its ID
Use "sudo docker attach [id]" to attach back to its terminal
Important: Please do not forget that since we are in a container, all the following commands will be executed there, without affecting the host it resides.
Preparing the Base Container for the Installation
In order to deploy Python WSGI web applications inside a container - and the tools we need for the process - the relevant application repositories must be available for the downloads. Unfortunately (and intentionally to keep things simple) this is not the case with the default Ubuntu image that comes with docker.
Let's append Ubuntu's universe repository to the default list of application sources list of the base image.
echo "deb http://archive.ubuntu.com/ubuntu/ $(lsb_release -sc) main universe" >> /etc/apt/sources.list
Update the list with the newly added source.
Before we proceed with setting up Python WSGI applications, there are some tools we should have such as nano, tar, curl, etc. - just in case.
Let's download some useful tools inside our container.
apt-get install -y tar \ git \ curl \ nano \ wget \ dialog \ net-tools build-essential
Installing Common Python Tools for Deployment
For our tutorial (as an example), we are going to create a very basic Flask application. After following this article, you can use and deploy your favorite framework instead, the same way you would deploy it on a virtual server.
Remember: All the commands and instructions below still take place inside a container, which acts almost as if it is a brand new droplet of its own.
Let's begin our deployment process with installing Python and pip the Python package manager:
# Install pip's dependency: setuptools: apt-get install -y python python-dev python-distribute python-pip
Installing The Web Application and Its Dependencies
Before we begin with creating a sample application, we better make sure that everything - i.e. all the dependencies - are there. First and foremost, you are likely to have your Web Application Framework (WAF) as your application's dependency (i.e. Flask).
As we have pip installed and ready to work, we can use it to pull all the dependencies and have them set up inside our container:
# Download and install Flask framework: pip install flask
After installing pip, let's create a basic, sample Flask application inside a "my_application" folder which is to contain everything.
# Make a my_application folder mkdir my_application # Enter the folder cd my_application
Note: If you are interested in deploying your application instead of this simple-sample example, see the "Quick Tip" mid-section below.
Let's create a single, one page flask "Hello World!" application using nano.
# Create a sample (app.py) with nano: nano app.py
And copy-and-paste the contents below for this small application we have just mentioned:
from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello World!" if __name__ == "__main__": app.run()
Press CTRL+X and approve with Y to save and close.
Alternatively, you can use a "requirements.txt" to contain your application's dependencies such as Flask.
To create a requirements.txt using nano text editor:
And enter the following inside, alongside all your dependencies:
Press CTRL+X and approve with Y to save and close.
Note: You can create your a list of your actual application's dependencies using pip. To see how, check out our tutorial Common Python Tools: Using virtualenv, Installing with Pip, and Managing Packages.
Our final application folder structure:
/my_application | |- requirements.txt # File containing list of dependencies |- /app # Application module (which should have your app) |- app.py # WSGI file containing the "app" callable |- server.py # Optional: To run the app servers (CherryPy)
Note: Please see the following section regarding the "server.py" - Configuring your Python WSGI Application .
Remember: This application folder will be created inside the container. When you are automatically building images (see the following section on Dockerfiles), you will need to make sure to have this structure on the host, alongside the Dockerfile.
__ * Quick tip for actual deployments * __
How to get your application repository and its requirements inside a container
In the above example, we created the application directory inside the container. However, you will not be doing that to deploy your application. You are rather likely to pull its source from a repository.
There are several ways to copy your repository inside a container.
Below explained are two of them:
# Example  # Download the application using git: # Usage: git clone [application repository URL] # Example: git clone https://github.com/mitsuhiko/flask/tree/master/examples/flaskr # Example  # Download the application tarball: # Usage: wget [application repository tarball URL] # Example: (make sure to use an actual, working URL) wget http://www.github.com/example_usr/application/tarball/v.v.x # Expand the tarball and extract its contents: # Usage: tar vxzf [tarball filename .tar (.gz)] # Example: (make sure to use an actual, working URL) tar vxzf application.tar.gz # Download and install your application dependencies with pip. # Download the requirements.txt (pip freeze output) and use pip to install them all: # Usage: curl [URL for requirements.txt] | pip install -r - # Example: (make sure to use an actual, working URL) curl http://www.github.com/example_usr/application/requirements.txt | pip install -r -
Configuring your Python WSGI Application
To serve this application, you will need a web server. The web server, which powers the WSGI app, needs to be installed in the same container as the application's other resources. In fact, it will be the process that docker runs.
Note: In this example, we will use CherryPy's built-in production ready HTTP web server due to its simplicity. You can use Gunicorn, CherryPy or even uWSGI (and set them up behind Nginx) by following our tutorials on the subject.
Download and install CherryPy with pip:
pip install cherrypy
Create a "server.py" to serve the web application from "app.py":
Copy and paste the contents from below for the server to import your application and start serving it:
# Import your application as: # from app import application # Example: from app import app # Import CherryPy import cherrypy if __name__ == '__main__': # Mount the application cherrypy.tree.graft(app, "/") # Unsubscribe the default server cherrypy.server.unsubscribe() # Instantiate a new server object server = cherrypy._cpserver.Server() # Configure the server object server.socket_host = "0.0.0.0" server.socket_port = 80 server.thread_pool = 30 # For SSL Support # server.ssl_module = 'pyopenssl' # server.ssl_certificate = 'ssl/certificate.crt' # server.ssl_private_key = 'ssl/private.key' # server.ssl_certificate_chain = 'ssl/bundle.crt' # Subscribe this server server.subscribe() # Start the server engine (Option 1 *and* 2) cherrypy.engine.start() cherrypy.engine.block()
And that's it! Now you can have a "dockerized" Python web application securely kept in its sandbox, ready to serve thousands and thousands of client requests by simply running:
This will run the server on the foreground. If you would like to stop it, press CTRL+C.
To run the server in the background, run the following:
python server.py &
When you run an application in the background, you will need to use a process manager (e.g. htop) to kill (or stop) it.
Note: To learn more about configuring Python WSGI applications for deployment with CherryPy, check out our tutorial: How to deploy Python WSGI apps Using CherryPy Web Server
To test that everything is running smoothly, which they should given that all the port allocations are already taken care of, you can visit http://[your droplet's IP] with your browser to see the "Hello World!" message.
Creating the Dockerfile to Automatically Build the Image
As we have mentioned in the previous step, it is certainly not the recommended way to create containers this way for a scalable production deployment. The right way to do can be considered as using Dockerfiles to automate the build process in a structured way.
After having gone through the necessary commands for downloading and installing inside a container, we can use the same knowledge to compose a Dockerfile that docker can use to build an image from, which then can be used to run a Python WSGI application container easily.
Before we start working on the Dockerfile, let's quickly go over the basics.
Dockerfiles are scripts containing commands declared successively, which are to be executed in that order by docker to automatically create a new docker image. They help greatly with deployments.
These files always begin with defining an base image using the FROM command. From there on, the build process starts and each following action taken forms the final image which will be committed on the host.
# Build an image using the Dockerfile at current location # Tag the final image with [name] (e.g. *nginx*) # Example: sudo docker build -t [name] . sudo docker build -t nginx_img .
Note: To learn more about Dockerfiles, check out our article: Docker Explained: Using Dockerfiles to Automate Building of Images.
Dockerfile Commands Overview
Copy a file from the host into the container
Set default commands to be executed, or passed to the ENTRYPOINT
Set the default entrypoint application inside the container
Set environment variable (e.g. "key = value")
Expose a port to outside
Set the base image to use
Set the author / owner data of the Dockerfile
Run a command and commit the ending result (container) image
Set the user to run the containers from the image
Mount a directory from the host to the container
Set the directory for the directives of CMD to be executed
Creating the Dockerfile
To create a Dockerfile at the current location using the nano text editor, execute the following command:
sudo nano Dockerfile
Note: Append all the following lines one after the other to form the Dockerfile.
Defining the Fundamentals
Let's begin our Dockerfile by defining the basics (fundamentals) such as the FROM image (i.e. Ubuntu) and the MAINTAINER.
Append the following:
############################################################ # Dockerfile to build Python WSGI Application Containers # Based on Ubuntu ############################################################ # Set the base image to Ubuntu FROM ubuntu # File Author / Maintainer MAINTAINER Maintaner Name
Updating the Default Application Repository for Installations
Run the following to update the
apt-get repository with additional applications just as we did in the previous section.
Append the following:
# Add the application resources URL RUN echo "deb http://archive.ubuntu.com/ubuntu/ $(lsb_release -sc) main universe" >> /etc/apt/sources.list # Update the sources list RUN apt-get update
Installing the Basic Tools
After updating the default application repository sources list, we can begin our deployment process by getting the basic applications we will need.
Append the following:
# Install basic applications RUN apt-get install -y tar git curl nano wget dialog net-tools build-essential
Note: Although you are unlikely to ever need some of the tools above, we are getting them nonetheless - just-in-case.
Base Installation Instructions for Python and Basic Python Tools
For deploying Python WSGI applications, you are extremely likely to need some of the tools which we worked with before (e.g. pip). Let's install them now before proceeding with setting up the framework (i.e. your WAF) and the your web application server (WAS) of choice.
Append the following:
# Install Python and Basic Python Tools RUN apt-get install -y python python-dev python-distribute python-pip
Given that we are building docker images to deploy Python web applications, we can very all take advantage of docker's ADD command to copy the application repository, preferably with a REQUIREMENTS file to quickly get running in one single step.
Note: To package everything together in a single file and not to repeat ourselves, an application folder, structured similarly to the one below might be a good way to go.
Example application folder structure:
/my_application | |- requirements.txt # File containing list of dependencies |- /app # Application module |- app.py # WSGI file containing the "app" callable |- server.py # Optional: To run the app servers (CherryPy)
Note: To see about creating this structure, please roll back up and refer to the section Installing The Web Application and Its Dependencies.
Append the following:
# Copy the application folder inside the container ADD /my_application /my_application
Note: If you want to deploy from an online host git repository, you can use the following command to clone:
RUN git clone [application repository URL]
Please do not forget to replace the URL placeholder with your actual one.
After adding the instructions for copying the application, let's finish off with final configurations such as pulling the dependencies from the requirements.txt.
# Get pip to download and install requirements: RUN pip install -r /my_application/requirements.txt # Expose ports EXPOSE 80 # Set the default directory where CMD will execute WORKDIR /my_application # Set the default command to execute # when creating a new container # i.e. using CherryPy to serve the application CMD python server.py
In the end, this is what the Dockerfile should look like:
############################################################ # Dockerfile to build Python WSGI Application Containers # Based on Ubuntu ############################################################ # Set the base image to Ubuntu FROM ubuntu # File Author / Maintainer MAINTAINER Maintaner Name # Add the application resources URL RUN echo "deb http://archive.ubuntu.com/ubuntu/ $(lsb_release -sc) main universe" >> /etc/apt/sources.list # Update the sources list RUN apt-get update # Install basic applications RUN apt-get install -y tar git curl nano wget dialog net-tools build-essential # Install Python and Basic Python Tools RUN apt-get install -y python python-dev python-distribute python-pip # Copy the application folder inside the container ADD /my_application /my_application # Get pip to download and install requirements: RUN pip install -r /my_application/requirements.txt # Expose ports EXPOSE 80 # Set the default directory where CMD will execute WORKDIR /my_application # Set the default command to execute # when creating a new container # i.e. using CherryPy to serve the application CMD python server.py
Again save and exit the file by pressing CTRL+X and confirming with Y.
Using the Dockerfile to Automatically Build Containers
As we first went over in the "basics" section, Dockerfiles' usage consists of calling them with docker build command.
Since we are instructing docker to copy an application folder (i.e. /my_application) from the current directory, we need to make sure to have it alongside this Dockerfile before starting the build process.
This docker image will allow us to quickly create containers running Python WSGI applications with a single command.
To start using it, build a new container image with the following:
sudo docker build -t my_application_img .
And using that image - which we tagged myapplicationimg - we can run a new container running the application with:
sudo docker run -name my_application_instance -p 80:80 -i -t my_application_img
Now you can visit the IP address of your droplet, and your application will be running via a docker container.
# Usage: Visit http://[my droplet's ip] http://220.127.116.11/
For the full set of instructions to install docker (including other OSs), check out the docker installation documentation at docker.io.