The goal of this project is to make a ready to deploy Django installation in Docker as easy as possible. Deployment options include using uWSGI as the HTTP server (local development), using Nginx to run the HTTP server (http services for the web), or using Nginx to run the HTTP server with SSL support (https services for the web).
Defaults include:
- Custom User model defined from the start
- uWSGI based server (optionally use Nginx as the web server)
- PostgreSQL backend (using psycopg2-binary)
- Pytest integration (using pytest, pytest-cov, pytest-django)
- Python .ENV app settings management (using python-dotenv)
- Docker Compose based services
In addition to my own Docker based exploits, this work was inspired by:
- Caktus Group's blog: Here's a Production-Ready Dockerfile for Your Python/Django App
- Will Vincent's blog: Django Tips #6: Custom User Model
Generate a new Django project named example_project using Nginx, SSL and uWSGI server.
docker run --rm \
-e PROJECT_NAME=example_project \
-v $(pwd):/code \
mjstealey/django-startproject-docker \
--nginx \
--ssl-certs \
--owner-uid $(id -u) \
--owner-gid $(id -g) \
--uwsgi-uid $(id -u) \
--uwsgi-gid $(id -g)
Get into the newly created example_project directory
cd example_project
Bring up all the containers using docker-compose
docker-compose up -d
Verify that all containers are running (containers take a few moments to run all setup scripts)
$ docker-compose ps
Name Command State Ports
----------------------------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp
django /code/docker-entrypoint.sh Up 0.0.0.0:8000->8000/tcp
nginx nginx -g daemon off; Up 0.0.0.0:8443->443/tcp, 0.0.0.0:8080->80/tcp
Browse to https://localhost:8443/ and verify the running Django site using a self signed SSL certificate
Enjoy!
Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. Built by experienced developers, it takes care of much of the hassle of Web development, so you can focus on writing your app without needing to reinvent the wheel. Itβs free and open source.
Generates a ready to run Django project using Docker based scripts with
- Custom User model per Django's recommendation
- Python 3 based Docker definition (python:3 on Dockerhub)
- Virtual environment managed by virtualenv (virtualenv tool)
- PostgreSQL database backend adapter (psycopg2-binary)
- uWSGI based run scripts (uWGSI)
- python-dotenv app settings management (python-dotenv)
- pytest Python testing tool
- Docker Compose definition and environment files
- Nginx web server (
--nginx
flag) (nginx on Dockerhub)- Implements uWSGI socket file
- Provides an HTTP service configuration for use in Docker
- Provides stub configuration for HTTPS / SSL using self generated certificates
- Unix socket protocol for Django services
- Host ports mapped as
8080:80
and8443:443
by default
Project files are designed to be run either locally using virtualenv, or in Docker using the generated docker-compose.yml
file. Virtualenv is used within Docker for improved environment isolation.
This project does not generate trusted HTTPS / SSL certificates.
- These are stubbed as self-signed certificates and left to the user to implement using the methods that best fit their scenario.
Setup is simple, and you don't even need to clone this repository as everything you need is already included in the django-startproject-docker image on Docker Hub.
Pull image from dockerhub
docker pull mjstealey/django-startproject-docker:latest
Optionally you can clone the repository and build the mjstealey/django-startproject-docker
image yourself. This allows you the opportunity to modify the build to your specific requirements if needed.
docker build -t mjstealey/django-startproject-docker .
There are a small set of system requirements in order to run the output of this code. If you're planning on doing additional development, which is most likely the case, then additional requirements may be applicable.
To Run
- Docker
- Docker Compose
To Develop
- Docker
- Docker Compose
- Python 3 / Pip 3
- Virtualenv
Depending on your goal, there are three deployment scenarios to consider.
- uWSGI runs the HTTP server - suitable for local development and testing, but not necessarily for web deployment
- Nginx runs the HTTP server - suitable for web deployment but does not make use of SSL encryption (non-production)
- Nginx runs the HTTP server using SSL - suitable for web deployment and makes use of SSL encryption (production)
When the django-startproject-docker container is run it will generate your Django project files using the configuration options you provide.
-e PROJECT_NAME=example_project
- name given to the Django project-v LOCAL_VOL:/code
- project files are generated within the container's/code
direcotry. Share a volume from the host to persist these files locally.
Additional usage options can be discovered by using the -h|--help
flag:
$ docker run --rm mjstealey/django-startproject-docker --help
### Help ###
Usage: django-startproject-docker [-nsh] [-o owner_uid] [-z owner_gid] [-u uwsgi_uid] [-g uwsgi_gid]
-n|--nginx = Include Nginx service definition files with build output
-s|--ssl-certs = Generate self-signed SSL certificates and configure Nginx to use https
-h|--help = Help/Usage output
-o|--owner-uid = UID to attribute output file ownership to (default=1000)
-z|--owner-gid = GID to attribute output file ownership to (default=1000)
-u|--uwsgi-uid = UID to run the uwsgi service as (default=1000)
-g|--uwsgi-gid = GID to run the uwsgi service as (default=1000)
NOTE: It is generally a good idea to set the -o|--owner-uid
and -z|--owner-gid
flags to be that of the user that will be running the application. So, if the current user were to be the same as the one running the application, these flags would take the form of --owner-uid $(id -u)
and --owner-gid $(id -g)
.
This configuration is suitable for local development and testing, but not necessarily for web deployment. The default configuration will run at http://localhost:8000/.
Let's create a new project named example_project in the present working directory with files owned by the current user.
docker run --rm \
-e PROJECT_NAME=example_project \
-v $(pwd):/code \
mjstealey/django-startproject-docker \
--owner-uid $(id -u) \
--owner-gid $(id -g)
Let's look at the generated files.
$ tree -a example_project
example_project # Project root
βββ .env # Compose .env file (ignored by git)
βββ .gitignore # Git .gitignore file
βββ Dockerfile # Dockerfile definition for django constainer
βββ conftest.py # Pytest configuration file
βββ docker-compose.yml # Compose definition for running the Django application stack
βββ docker-entrypoint.sh # Entry point definition for django container
βββ env.template # Compose .env template file
βββ example_project # Primary project directory
βΒ Β βββ .env # Python .env file (ignored by git)
βΒ Β βββ __init__.py # Python init
βΒ Β βββ env.template # Python .env template file
βΒ Β βββ runner.py # Pytest test runner for Django
βΒ Β βββ secrets.py # Django secrets file (ignored by git)
βΒ Β βββ secrets.py.template # Django secrets template file
βΒ Β βββ settings.py # Main Django settings file
βΒ Β βββ urls.py # Main Django urls file
βΒ Β βββ wsgi.py # Django WSGI file
βββ example_project_uwsgi.ini # uWSGI configuration file
βββ manage.py # Django manage.py file
βββ media # Django media files directory (ignored by git)
βββ pg_data # PostgreSQL host volume (ignored by git)
βΒ Β βββ data # PostgreSQL data
βΒ Β βββ logs # PostgreSQL logs
βββ pytest.ini # Pytest configuration file
βββ requirements.txt # Pip install requirements file
βββ run_uwsgi.sh # uWSGI run script
βββ static # Django static files directory (ignored by git)
βββ users # Django users app for CustomUser
βββ __init__.py # Python init
βββ admin.py # CustomUser admin
βββ apps.py # CustomUser apps
βββ forms.py # CustomUser forms
βββ migrations # CustomUser migrations directory
βΒ Β βββ __init__.py # Python init
βββ models.py # CustomUser model definition
βββ tests.py # CustomUser tests
βββ views.py # CustomUser views
8 directories, 29 files
Now lets run it!
This configuration is suitable for web deployment but does not make use of SSL encryption (non-production). The default configuration will run at http://localhost:8080/.
Let's create a new project named example_project in the present working directory with files owned by the current user using Nginx as the web server.
docker run --rm \
-e PROJECT_NAME=example_project \
-v $(pwd):/code \
mjstealey/django-startproject-docker \
--nginx \
--owner-uid $(id -u) \
--owner-gid $(id -g)
Let's look at the generated files.
$ tree -a example_project
example_project
βββ .env
βββ .gitignore
βββ Dockerfile
βββ conftest.py
βββ docker-compose.yml
βββ docker-entrypoint.sh
βββ env.template
βββ example_project
βΒ Β βββ .env
βΒ Β βββ __init__.py
βΒ Β βββ env.template
βΒ Β βββ runner.py
βΒ Β βββ secrets.py
βΒ Β βββ secrets.py.template
βΒ Β βββ settings.py
βΒ Β βββ urls.py
βΒ Β βββ wsgi.py
βββ example_project_uwsgi.ini
βββ manage.py
βββ media
βββ nginx # Nginx directory
βΒ Β βββ default.conf # Nginx default http configuration (ignored by git)
βΒ Β βββ default.conf.template # Nginx default http configuration template
βΒ Β βββ default_ssl.conf.template # Nginx default https configuration template
βββ pg_data
βΒ Β βββ data
βΒ Β βββ logs
βββ pytest.ini
βββ requirements.txt
βββ run_uwsgi.sh
βββ static
βββ users
βΒ Β βββ __init__.py
βΒ Β βββ admin.py
βΒ Β βββ apps.py
βΒ Β βββ forms.py
βΒ Β βββ migrations
βΒ Β βΒ Β βββ __init__.py
βΒ Β βββ models.py
βΒ Β βββ tests.py
βΒ Β βββ views.py
βββ uwsgi_params
9 directories, 33 files
Now lets run it!
This configuration is suitable for web deployment and makes use of SSL encryption (production), and is preferred.The default configuration will run at https://localhost:8443/.
Let's create a new project named example_project in the present working directory with files owned by the current user using Nginx as the web server with SSL support.
docker run --rm \
-e PROJECT_NAME=example_project \
-v $(pwd):/code \
mjstealey/django-startproject-docker \
--nginx \
--ssl-certs \
--owner-uid $(id -u) \
--owner-gid $(id -g)
Let's look at the generated files.
$ tree -a example_project
example_project
βββ .env
βββ .gitignore
βββ Dockerfile
βββ conftest.py
βββ docker-compose.yml
βββ docker-entrypoint.sh
βββ env.template
βββ example_project
βΒ Β βββ .env
βΒ Β βββ __init__.py
βΒ Β βββ env.template
βΒ Β βββ runner.py
βΒ Β βββ secrets.py
βΒ Β βββ secrets.py.template
βΒ Β βββ settings.py
βΒ Β βββ urls.py
βΒ Β βββ wsgi.py
βββ example_project_uwsgi.ini
βββ manage.py
βββ media
βββ nginx # Nginx directory
βΒ Β βββ default.conf # Nginx default http configuration (ignored by git)
βΒ Β βββ default.conf.template # Nginx default http configuration template
βΒ Β βββ default_ssl.conf.template # Nginx default https configuration template
βββ pg_data
βΒ Β βββ data
βΒ Β βββ logs
βββ pytest.ini
βββ requirements.txt
βββ run_uwsgi.sh
βββ ssl # SSL directory
βΒ Β βββ ssl_dev.crt # Self signed SSL certificate file
βΒ Β βββ ssl_dev.key # Self signed SSL key file
βββ static
βββ users
βΒ Β βββ __init__.py
βΒ Β βββ admin.py
βΒ Β βββ apps.py
βΒ Β βββ forms.py
βΒ Β βββ migrations
βΒ Β βΒ Β βββ __init__.py
βΒ Β βββ models.py
βΒ Β βββ tests.py
βΒ Β βββ views.py
βββ uwsgi_params
10 directories, 35 files
Now lets run it!
Running the application is the same regardless of the configuration you used to generate the files.
- Running everything in Docker should yield the Django welcome page once the containers finish their setup scripts.
- Running Django locally will take a little more configuration and is somewhat dependent on your local system (macOS, Linux or Windows)
To run everything in Docker, simply change into the project's root directory and bring the containers up.
cd example_project
docker-compose up -d
Files from your host will be shared with the running Docker containers using volume mounts.
The django
container
volumes:
- .:/code
- ./static:/code/static
- ./media:/code/media
The nginx
container
volumes:
- .:/code
- ./static:/code/static
- ./media:/code/media
- ${NGINX_DEFAULT_CONF:-./nginx/default.conf}:/etc/nginx/conf.d/default.conf
- ${NGINX_SSL_CERT:-./ssl/ssl_dev.crt}:/etc/ssl/SSL.crt # SSL certificate
- ${NGINX_SSL_KEY:-./ssl/ssl_dev.key}:/etc/ssl/SSL.key # SSL key
Two docker containers should be observed running
$ docker-compose ps
Name Command State Ports
-------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp
django /code/docker-entrypoint.sh Up 0.0.0.0:8000->8000/tcp
You Django project should now be running at: http://localhost:8000/
Three docker containers should be observed running
$ docker-compose ps
Name Command State Ports
----------------------------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp
django /code/docker-entrypoint.sh Up 0.0.0.0:8000->8000/tcp
nginx nginx -g daemon off; Up 0.0.0.0:8443->443/tcp, 0.0.0.0:8080->80/tcp
You Django project should now be running at: http://localhost:8080/
Three docker containers should be observed running
$ docker-compose ps
Name Command State Ports
----------------------------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp
django /code/docker-entrypoint.sh Up 0.0.0.0:8000->8000/tcp
nginx nginx -g daemon off; Up 0.0.0.0:8443->443/tcp, 0.0.0.0:8080->80/tcp
You Django project should now be running at: https://localhost:8443/. Accept the dialogue regarding a non-trusted CA as the SSL certificates are self generated.
By default this project is configured to run everything in Docker which may be non-optimal for development. In order to enable local development using Python 3 the user must make a few small changes prior to running the code.
Create the virtual environment and install packages from the Django root directory
virtualenv -p $(which python3) venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
Start the pre-defined PostgreSQL database in Docker
Update POSTGRES_HOST
in the Django .env file to reflect the IP of your local machine (For example, from export POSTGRES_HOST=database
to export POSTGRES_HOST=127.0.0.1
)
docker-compose up -d database
Validate that the database container is running.
$ docker-compose ps
Name Command State Ports
-------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp
Update the uWSGI ini file
...
; use protocol uwsgi over TCP socket (use if UNIX file socket is not an option)
;socket = :8000
; add an http router/server on the specified address **port**
http = :8000
; map mountpoint to static directory (or file) **port**
static-map = /static/=static/
static-map = /media/=media/
; bind to the specified UNIX/TCP socket using uwsgi protocol (full path) **socket**
;uwsgi-socket = ./django.sock
; ... with appropriate permissions - may be needed **socket**
;chmod-socket = 666
...
Execute the run_uwsgi.sh
script
UWSGI_UID=$(id -u) UWSGI_GID=$(id -g) ./run_uwsgi.sh
- NOTE: the
uwsgi
service will be spawned using the user's UID and GID values. These would otherwise default toUID=1000
andGID=1000
as denoted in therun_uwsgi.sh
script.
Validate that the Django is running site at http://localhost:8000/
NOTE: Depending on your system (macOS) you may not be able to run the Nginx server using file sockets mounted from the host. For more information refer to this Github issue: Support for sharing unix sockets. If this is the case, you'll either need to run your Nginx server over ports, or run everything in Docker. The following will describe how to run the Nginx server using TCP ports.
Update the uWSGI ini file
...
; use protocol uwsgi over TCP socket (use if UNIX file socket is not an option)
socket = :8000
; add an http router/server on the specified address **port**
;http = :8000
; map mountpoint to static directory (or file) **port**
;static-map = /static/=static/
;static-map = /media/=media/
; bind to the specified UNIX/TCP socket using uwsgi protocol (full path) **socket**
;uwsgi-socket = ./django.sock
; ... with appropriate permissions - may be needed **socket**
;chmod-socket = 666
...
Update the Nginx configuration file to use the TCP socket (http or https)
# the upstream component nginx needs to connect to
upstream django {
#server unix:///code/django.sock; # UNIX file socket
# Defaulting to macOS equivalent of docker0 network for TCP socket
server host.docker.internal:8000; # TCP socket
}
- NOTE:
host.docker.internal
is macOS specific, substitute as required by your operating system
Launch the nginx
container
docker-compose up -d nginx
Validate that both the database and nginx containers are running.
docker-compose ps
Name Command State Ports
----------------------------------------------------------------------------------------------
database docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp
nginx nginx -g daemon off; Up 0.0.0.0:8443->443/tcp, 0.0.0.0:8080->80/tcp
Execute the run_uwsgi.sh
script
UWSGI_UID=$(id -u) UWSGI_GID=$(id -g) ./run_uwsgi.sh
- NOTE: the
uwsgi
service will be spawned using the user's UID and GID values. These would otherwise default toUID=1000
andGID=1000
as denoted in therun_uwsgi.sh
script.
Validate that the Django is running site at http://localhost:8080/
- NOTE: you should be automatically redirected to port
8443
if using Nginx with SSL certificates.
- Django docs: https://docs.djangoproject.com/en/2.2/
- Docker docs: https://docs.docker.com
- Docker Compose docs: https://docs.docker.com/compose/
- uWSGI options: http://uwsgi-docs.readthedocs.io/en/latest/Options.html
- Nginx docs: https://nginx.org/en/docs/