You can jump to the scripts and configuration files if you don’t care about the theory and just want to see the end result.

Why Docker?

Docker is a technology that has taken the software engineering world by storm. The main promise is isolation: a Docker container that works on an x86_64 Linux machine will work on any x86_64 Linux machine in the same way. Want to quickly set up PostgreSQL for testing? Just run docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d --restart=unless-stopped postgres and wait a few seconds. Docker is great for deployment as well as production deployments, and it even supports Windows Server containers these days (whether or not this is a pleasant experience is a different question).

Of course, there is a trade-off: running something in a Docker container requires more disk space than running the same software outside of Docker would. This is because Docker containers have their own copies of everything: the C library, the shell, core commands, and the runtime of your favorite language. But this is not a bug, it’s a feature.

If you read the nginx/uWSGI Emperor guide I wrote ten years ago, you might notice there are many cases where the configuration differs depending on the Linux distribution in use. Some distributions made logging an optional feature, others have it built in. Each distribution has a slightly different directory structure, and different users and groups for Web services. Some distros did not ship systemd service files. Red Hat is still pushing SELinux.

But uWSGI is not the only pain point. There’s also the system Python. Every distribution treats it differently and applies different customizations. Arch maps python to python3, but other distributions do not. Arch and Fedora ship a single Python package, while Debian/Ubuntu have many split packages. Taking a dependency on the system Python also makes distro upgrades harder: if the system Python is upgraded, the virtual environment needs to be recreated. (Hope you have an up-to-date requirements.txt!)

Should everything be in Docker?

It depends on your definition of everything. I ended up with only one non-dockerized application (which requires access to resources that cannot easily be provided to it when it is in a container): an ASP.NET Core Minimal API compiled with Native AOT, so its maintenance burden is essentially zero. Except for that app, all web applications on my VPS, whether written in PHP, Python, or .NET, run in Docker. I don't need to figure out how to make PHP happy; I use a container image in which someone else had done the hard parts for me. I don't need to maintain Python virtual environments; they can just live inside containers. The maintenance burden for .NET is smaller, but containers still prevent issues that could be caused by removing an old version of .NET, for example. (Those apps are ASP.NET Core MVC, so they are not compatible with Native AOT.)

But I am not running the Web-facing nginx instance in Docker. Similarly, I’ve kept PostgreSQL outside of Docker, and I’ve just un-dockerized a MariaDB instance. The main difference here is that I can apt install nginx and get a supported and secure build, with default configuration that might be more reasonable than the default. (But then again, apt install python3 gets you a fairly mediocre build.)

For the Python dockerization project, my requirements are fairly simple. The Docker container only needs Python, a venv with dependencies installed, and all data files of the app. The database exists outside of Docker, and I’ve already configured PostgreSQL to listen on an address accessible from within Docker (but of course, not from the public Internet). Because Django and Python have abysmal performance, static files must be served by nginx. Since I don’t want a dedicated nginx in a Docker container, the easiest solution is to mount a folder as a volume: Django runs collectstatic inside the container to write static files there, and the host nginx serves them.

What should be in Docker?

There are four things that we need to put in our Docker container: Linux, Python, a venv, and a WSGI server.

Linux and Python (base image)

The choice of a base image can affect a few things about the Docker experience. For Python, the most commonly used image is the one prepared by Docker, Inc. simply named python. That image has three versions, or tags in Docker parlance:

• python:3.14 (the default), which is based on Debian (1.12GB)
• python:3.14-slim, which is based on Debian but with less cruft (119MB)
• python:3.14-alpine, which is bvased on Alpine Linux (47.4MB)

Alpine Linux images are really small, but with the caveat that they are based on the musl libc instead of GNU glibc, which means most binaries, including manylinux binary wheels, do not work, and special builds (musllinux binary wheels in this case) are required. I started with the Debian-based images (the default one for build, the slim one for production), but I switched to python:3.14-alpine, as the only binary dependency I have is psycopg2, which I build from source, but there are musllinux wheels of psycopg2-binary available.

Virtual environments and dependency management

Python packaging is still a mess. I don’t feel like using the VC-backed uv, and the other big tools (like poetry or pipenv) introduce too much magic and bloat. All I need is a requirements.txt file I can install with pip into a venv, but without having to manually track version numbers. For that, pip-compile from pip-tools is a great option. It takes a requirements.in file with package names and optional version ranges, and produces a requirements.txt with all dependencies (including transitive dependencies) pinned to exact versions. It doesn’t get much simpler than that.

There is one issue: the requirements.txt files produced by pip-compile are specific to the environment in which it was executed. So if you want a requirements.txt for Linux and Python 3.14, you must run pip-compile on Linux with Python 3.14. While this does not matter much for this project (it has very simple dependencies), I wanted to ensure the tool runs with the same Python version the container will use, and to allow building the image without having pip-compile installed on the development machine.

So, I quickly hacked together a tool unoriginally named docker-pip-compile. It’s a five-line Dockerfile and a slightly longer shell script to help run it. That way, dependencies can be updated and the entire project can be built even without a functional system Python. The only catch here (and the reason for the hackiest line in the Dockerfile) is the fact that the package must be buildable in the environment where pip-compile runs, so I had to install libpq (the PostgreSQL client library) there.

WSGI server

The old post used uWSGI (it’s even mentioned in the title). Sadly, uWSGI has been in maintenance mode since 2022. On the other hand, gunicorn is doing pretty well, so I used that. I also decided to add uvicorn to the mix, because why not.

Scripts and configuration files

You might be able to find a more up-to-date version of those scripts in the nikola-users repository.

Dockerfile

The Dockerfile is pretty straightforward. To save a little disk space, I use a multi-stage build. The build stage sets up a virtual environment, installs packages into it, and copies files into /app. The final stage installs libpq (the PostgreSQL client library, needed for psycopg2) and copies /venv and /app from the build stage. (The disk space savings come from not having build-base and libpq-dev in the final image.)

docker-entrypoint.sh

The entrypoint is fairly simple as well. Before starting gunicorn, we need to run migrations and collect static files. To avoid repeating this on container restarts, we create a marker file inside the container to indicate whether setup has already completed. I use three workers, which should be enough for those sites.

docker-compose.yml

I mentioned that only one service runs inside Docker, since nginx and PostgreSQL live outside. Docker Compose may feel unnecessary with just one service, but it is still a convenient way to keep the required configuration in a file.

nginx

The nginx configuration is as simple as it gets:

Conclusion

In just two evenings, I got rid of the venv and system Python maintenance burden. When I upgrade to Ubuntu 26.04 in a few months, my Python apps will just work with no extra steps needed. Docker is a lot of fun.

The following is a comprehensive guide on how to accomplish that, on multiple Linux-based operating systems, using nginx and uWSGI Emperor. It doesn’t force you to use any specific web framework — Flask, Django, Pyramid, Bottle will all work. Written for Ubuntu, Debian, Fedora, CentOS 7, Alma Linux, Rocky Linux and Arch Linux (should be helpful for other systems, too). Now with an Ansible Playbook.

Revision 8 (2022-02-20): works with Fedora 35, AlmaLinux 8, RockyLinux 8

While this guide is still valid, in 2026 I switched to Docker and Gunicorn for my Python web app deployments. Check out Deploying Python Web Applications with Docker for more details.

CI status for the associated Ansible Playbook:

For easy linking, I set up some aliases: https://go.chriswarrick.com/pyweb and https://go.chriswarrick.com/uwsgi-tut.

apt install python3 python3-venv uwsgi uwsgi-emperor uwsgi-plugin-python3 nginx-full git

dnf install python3 uwsgi uwsgi-plugin-python3 uwsgi-logger-file nginx git

yum install epel-release
yum install python36 uwsgi uwsgi-plugin-python36 uwsgi-logger-file nginx git wget

dnf install epel-release
dnf install python36 uwsgi uwsgi-plugin-python3 uwsgi-logger-file nginx git wget

pacman -S python uwsgi uwsgi-plugin-python nginx git

mkdir /srv/myapp
python3 -m venv --prompt myapp /srv/myapp/venv

cd /srv/myapp
git clone https://github.com/Kwpolska/flask-demo-app appdata
venv/bin/pip install -r appdata/requirements.txt

chown -R www-data:www-data /srv/myapp

chown -R uwsgi:nginx /srv/myapp

chown -R http:http /srv/myapp

systemctl enable nginx emperor.uwsgi
systemctl start nginx emperor.uwsgi

systemctl enable nginx uwsgi
systemctl start nginx uwsgi

setenforce 0
chcon -R system_u:system_r:httpd_t:s0 /srv/myapp/appdata/static
setenforce 1

semodule -i nginx-uwsgi.pp

systemctl stop uwsgi-emperor
systemctl disable uwsgi-emperor

ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi-emperor/emperor.ini

systemctl daemon-reload
systemctl enable nginx emperor.uwsgi
systemctl reload nginx
systemctl start emperor.uwsgi

End result

Your web service should now be running at http://localhost/ (or wherever you set up server to listen).

If you used the demo application, you should see something like this (complete with the favicon and image greeting):

If you want to test with cURL:

curl -v http://localhost/
curl -I http://localhost/favicon.ico
curl -I http://localhost/static/hello.png

Troubleshooting

Hopefully, everything works. If it doesn’t:

• Check your nginx, system (journalctl, systemctl status SERVICE) and uwsgi (/srv/myapp/uwsgi.log) logs.

• Make sure you followed all instructions.

• If you get a default site, disable that site in nginx config (/etc/nginx/nginx.conf or your sites directory).

• If you have a firewall installed, make sure to open the ports your web server runs on (typically 80/443). For firewalld (Fedora, CentOS, EL8):

firewall-cmd --add-service http
firewall-cmd --add-service https

• If it still does not work, feel free to ask in the comments, mentioning your distribution, installation method, and what doesn’t work.