← All posts

9 min read

How to Deploy a Python App in Docker: Full Guide

Key takeaways

  • One Dockerfile pattern covers Flask, Django, and FastAPI: a slim base image, cached pip install, and a gunicorn or uvicorn command bound to 0.0.0.0.
  • Binding to 127.0.0.1 instead of 0.0.0.0 is the most common reason a container builds fine locally but serves nothing in production.
  • A .dockerignore listing .git, venv, and pycache keeps build context small and keeps secrets out of your image.
  • For solo developers, a git-push PaaS or a registry plus a cheap VPS beats Kubernetes, which adds ops overhead most side projects never need.
  • Django apps need collectstatic at build time and migrations at deploy time, while FastAPI swaps gunicorn's sync worker for uvicorn or UvicornWorker.

To deploy python app in docker, write one Dockerfile that runs your app with gunicorn or uvicorn on port 8080 bound to 0.0.0.0, test it locally with docker run, then push the image or repo to a PaaS that gives you a git-push-to-deploy path with automatic HTTPS. This guide covers that full path for Flask, Django, and FastAPI.

What does it mean to deploy a Python app in Docker?

Deploying a Python app in Docker means packing your code, its Python version, and every dependency into a single image that runs identically on your laptop and on a server. You write a Dockerfile, build it, and hand the resulting container to a host instead of installing packages over SSH and hoping nothing drifts.

Why bother? Bare-metal deploys break when the server's Python or system libraries differ from yours, and they make rollback painful. A container fixes both, and it is the format most modern hosts accept: git push to deploy platforms like Render and Omeganodes build your repo into an image for you. The Dockerfile reference is the source of truth for the syntax.

The payoff is a live HTTPS URL from one repeatable artifact, not a pile of setup scripts. The same pattern carries from a side project to your first paying SaaS users.

How do you write a production Dockerfile for a Python web app?

The shared Dockerfile pattern

One Dockerfile pattern covers Flask, Django and FastAPI. Copy this and adjust the last two lines:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["gunicorn", "-w", "2", "-b", "0.0.0.0:8000", "app:app"]

Every line earns its place. python:3.12-slim keeps the image under a few hundred MB instead of the full image's 1 GB-plus. Copying requirements.txt before the rest of the code means Docker caches your installed dependencies and skips reinstalling them on every code change.

Binding to 0.0.0.0 matters more than it looks: bind to 127.0.0.1 and your container will build fine, pass local tests, then serve nothing when deployed, because nothing outside the container can reach it. For Django, swap the CMD to gunicorn myproject.wsgi; for FastAPI, use uvicorn app:app --host 0.0.0.0 --port 8000. This is the same pattern Omeganodes expects when you push a repo with a Dockerfile, and it is what lets one file serve all three frameworks without Kubernetes or YAML files to maintain.

Why slim base images and .dockerignore matter

Add a .dockerignore next to your Dockerfile and list __pycache__, .git, venv, and .env. Without it, Docker sends your whole folder as build context, so each git push to deploy uploads megabytes you never needed and risks copying secrets into the image. Slim images plus a lean context mean faster builds, smaller deploys, and cheaper bandwidth, which counts when you are paying in shillings or cedis for data.

How do you deploy a Flask app in Docker step by step?

The Flask app and requirements.txt

Start with the smallest possible project: three files in one folder.

app.py

from flask import Flask
app = Flask(__name__)

@app.route("/")
def home():
    return "Flask in Docker is live"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

requirements.txt

flask==3.0.3
gunicorn==22.0.0

Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]

Gunicorn is the production server here. It binds to 0.0.0.0 so the container accepts connections from outside itself, not just localhost. The Gunicorn docs cover the -b flag and worker settings in detail.

Build and run the container

From the project folder, run:

docker build -t flask-app .
docker run -p 8000:8000 flask-app

The -p 8000:8000 maps your machine's port 8000 to the container's port 8000. Open http://localhost:8000 and you should see the response string. If you want this same image live on an HTTPS URL without touching servers, a push-to-deploy platform like Omeganodes handles the build from your repo (why we built it).

What changes for Django and FastAPI apps in Docker?

The Dockerfile pattern stays the same. Three details change: the command that starts your server, the module path you point it at, and a couple of Django-only build steps.

Django specifics

Django runs through WSGI, so your CMD targets the module containing wsgi.py, usually myproject.wsgi:application. If you use Gunicorn, the command looks like gunicorn myproject.wsgi:application --bind 0.0.0.0:8000. Two build-time additions: run python manage.py collectstatic --noinput so static files land in STATIC_ROOT, and bake python manage.py migrate into your release step rather than the image build, since migrations belong at deploy time against a live database. Set DJANGO_SETTINGS_MODULE and ALLOWED_HOSTS as environment variables so one image works across staging and production.

FastAPI specifics

FastAPI is ASGI, so swap Gunicorn's sync worker for Uvicorn: uvicorn main:app --host 0.0.0.0 --port 8000. The module path is filename:app, not a dotted WSGI path, and a typo there is the most common startup failure. If you want worker processes, use gunicorn -k uvicorn.workers.UvicornWorker main:app.

Either framework deploys the same way once the image builds: push the repo to Omeganodes and it runs the container, handles HTTPS, and gives you a URL, with no Kubernetes or YAML.

How do you run and test your Dockerized Python app locally?

Build once, then run the same image you plan to push:

docker build -t myapp .
docker run -p 8000:8000 myapp

Open http://localhost:8000 in your browser or hit it with curl. If the page loads, the container serves traffic exactly as it will on a host like Omeganodes or the platforms compared at our Ziploy comparison.

Running on Windows and macOS

Docker Desktop handles both, but watch the port flag: -p 8000:8000 maps host to container, and the order trips people up. On Windows, run commands from PowerShell or WSL, and make sure the file uses LF line endings or shell scripts inside the container will fail. On macOS with Apple Silicon, images build as ARM by default; add --platform linux/amd64 if your host runs x86 servers.

Checking logs and health

Run docker logs -f myapp to follow output and spot startup errors fast. For FastAPI, confirm your bind address: --host 0.0.0.0 is required inside a container, or nothing outside it connects, per the Uvicorn documentation.

How do you push a Dockerized Python app to a hosting platform?

You have three realistic paths: a git-push PaaS that builds your image for you, a registry plus a VPS you manage yourself, or Kubernetes. For a solo developer running a side project or first SaaS app, Kubernetes is overkill: you would spend more time on ingress controllers and node pools than on your app. Hacker News threads on Heroku alternatives keep circling the same point: people want someone else to handle routing, TLS, and restarts.

Git-push PaaS vs registry + VPS vs Kubernetes

PathWhat you doBest when
Git-push PaaSgit push, platform builds and deploysSolo devs, no infra maintenance
Registry + VPSPush image to a registry, run it on a $5 serverYou want full control and lowest cost
KubernetesManifests, clusters, YAMLTeams with dedicated ops capacity

Whichever path you choose, add a .dockerignore before your first push so build context stays small and secrets stay out of the image. The Docker build context docs cover the syntax.

Paying from East Africa: mobile money and regional pricing

The catch for many Kenyan and Ugandan developers is not deploying, it is paying. Render, Railway, and Fly.io all bill in USD by card, which locks out MTN Mobile Money and Airtel Money users who have no international card. That means the deploy works perfectly, the image builds, the URL goes live, and then the trial ends and you cannot hand over a payment method the platform accepts. Before you commit to any host, check the payment methods page first, because a PaaS you cannot pay for is not an alternative no matter how good its free tier looks. Regional-priced options that accept mobile money close this gap, and the fair-price question matters as much as the deploy question. If your card works, ignore this section entirely; if it does not, filter your platform search by payment method before you filter by features, uptime, or framework support.

Why won't my Python Docker container start or serve traffic?

Port binding: 0.0.0.0 vs 127.0.0.1

The container builds fine, the platform says it's live, but the URL times out. Nine times out of ten your app is listening on 127.0.0.1 inside the container, so nothing outside can reach it. Bind to 0.0.0.0 and the container's port instead: gunicorn -b 0.0.0.0:8000 or uvicorn main:app --host 0.0.0.0 --port 8000. Then check that your EXPOSE and platform port settings match. Most PaaS providers, including Omeganodes, inject a PORT variable — read it rather than hardcoding 8000.

Missing gunicorn or uvicorn in the image

The app runs locally with flask run or uvicorn, then crashes in production with "command not found". Your dev server tool was never installed in the image. Add gunicorn or uvicorn to requirements.txt and set the start command in your Dockerfile's CMD or ENTRYPOINT. Never rely on the platform guessing the command.

Shrinking a bloated image

A 2 GB image slows every deploy and can exceed platform limits. Pin a slim base like python:3.12-slim, copy requirements first so pip layers cache, and add a .dockerignore for .git, venv and __pycache__. Multi-stage builds (build wheels in one stage, copy them into a clean stage) typically cut the final image by more than half.

FAQ

Can I deploy a Python app in Docker without a credit card?

Yes, but your options narrow. Most major platforms, including Render, Railway, and Fly.io, bill in USD by card, which excludes developers paying with MTN Mobile Money or Airtel Money. Look for hosts with regional pricing that accept mobile money, or run the image yourself on a VPS you rent with a local payment method.

How much RAM does a Dockerized Python app need in production?

A small Flask or FastAPI container with Gunicorn or Uvicorn runs comfortably in 256 to 512 MB. Django with migrations and static files typically wants 512 MB or more. Add headroom for worker processes: each Gunicorn worker holds its own memory, so two workers roughly double the footprint of one.

Do I need Kubernetes to deploy a Dockerized Python app?

No. For a solo developer or a first SaaS app, Kubernetes is overkill: you would spend more time on ingress controllers and node pools than on your app. A git-push PaaS that builds your Dockerfile, or a registry plus a cheap VPS, covers everything most side projects and early products need.

How do I connect a custom domain and HTTPS to my Docker container?

Point your domain's DNS records at your host, then let the platform handle certificates. Most git-push PaaS providers issue and renew TLS certificates automatically once the domain verifies. On a VPS you manage yourself, you run the certificate setup and renewal yourself, typically with a reverse proxy in front of the container.

Can I deploy a Python Docker app from Windows?

Yes. Docker Desktop handles builds on Windows, but run commands from PowerShell or WSL and make sure files use LF line endings, or shell scripts inside the container will fail. Remember that -p 8000:8000 maps host port to container port, an order that trips up plenty of first-time deploys.

Deploy at the speed of Africa

World-class hosting, open to every developer, wherever you build and however you pay. Start free in a couple of minutes — no credit card, no lock-in.