Python Backend Docker Deployment Templates

A collection of pragmatic and efficient Docker configurations for Python backend applications, specifically tailored for Django and Litestar projects. These templates are designed for rapid local development, ease of deployment, and efficient multi-process management using multi-stage builds and Docker Compose.

Table of Contents

• Why This Approach?
• Features
• Directory Structure
• Getting Started
  • Prerequisites
  • Usage
• Environment Variables
• Troubleshooting Common Issues

---

Why This Approach?

In modern Python web development, efficiency and reproducibility are key. This repository provides Docker configurations that prioritize:

• Simplicity: A standardized compose.yml that sets up everything you need for development.
• Efficiency: Utilizes uv for lightning-fast dependency management and multi-stage Docker builds to keep final images small and secure.
• Completeness: Includes out-of-the-box configurations for PostgreSQL, PgBouncer, PgAdmin, and Celery (Worker & Beat).
• Flexibility: Allows running your application alongside all its dependencies in a cohesive environment, making local development closer to production.

Features

• Framework-Specific Templates: Dedicated Dockerfiles and Compose files for Django and Litestar.
• Multi-stage Builds: Optimized Dockerfiles using uv to minimize image size and build times.
• Comprehensive Infrastructure:
  • PostgreSQL: Reliable relational database.
  • PgBouncer: Connection pooler to efficiently manage database connections.
  • PgAdmin: Web-based GUI to interact with the database.
  • Celery & Celery Beat: Background task processing and scheduling.
• Docker Compose: Seamless orchestration of the web application, workers, database, and admin tools.

Directory Structure

├── django/
│   ├── .dockerignore
│   ├── compose.yml
│   ├── Dockerfile
│   ├── entrypoint.sh
│   ├── supervisord.conf
│   └── env/
│       ├── backend.env
│       ├── pgadmin.env
│       ├── pgbouncer.env
│       └── postgres.env
└── litestar/
    ├── .dockerignore
    ├── compose.yml
    ├── Dockerfile
    ├── supervisord.conf
    └── env/
        ├── backend.env
        ├── pgadmin.env
        ├── pgbouncer.env
        └── postgres.env

Each framework directory contains:

• Dockerfile: A multi-stage build file using uv for installing dependencies and setting up the runtime environment.
• compose.yml: A Docker Compose file defining all services (backend, celery, postgres, pgbouncer, pgadmin).
• supervisord.conf: (Optional) Supervisor configuration if you prefer running multiple processes within a single container.
• env/: A directory containing environment variable files for each service, separated for clarity and security during development.

Getting Started

Prerequisites

• Docker: Ensure Docker Engine and Docker Compose are installed on your system.
• Your Python project (Django or Litestar) with pyproject.toml and uv.lock files.

Usage

1. Choose your framework's directory (django/ or litestar/).

2. Copy the necessary files (Dockerfile, compose.yml, env/, and .dockerignore) from that directory into the root of your specific project.

3. Configure Environment Variables: Review and update the .env files located in the env/ directory to match your project's needs (e.g., database credentials, secret keys).

4. Build and Run: Navigate to your project's root directory in your terminal and run:

   docker compose up --build -d

5. Access the Services:

   • Backend API: http://localhost:8000
   • PgAdmin (Database GUI): http://localhost:5050
   • Database (via PgBouncer): Accessible internally via the pgbouncer host on port 6432.

6. Check Status and Logs:

   • View running services: docker compose ps
   • Stream logs from all services: docker compose logs -f
   • Stream logs from a specific service: docker compose logs -f backend

7. Stop Services:

   • To stop services: docker compose stop
   • To stop and remove containers/networks: docker compose down
   • To also remove named volumes (clearing database data): docker compose down -v

Environment Variables

We use dedicated .env files inside the env/ directory for better organization:

• env/backend.env: Configuration for the main web framework and Celery (e.g., DATABASE_URL, CELERY_BROKER_URL).
• env/postgres.env: Superuser password and initialization settings for PostgreSQL.
• env/pgbouncer.env: Connection pooling limits and authentication settings.
• env/pgadmin.env: Login credentials for the PgAdmin web interface.

Note: These .env files are included here for local development and learning purposes. For production, ensure you use a secure secret manager or inject variables securely at runtime.

Troubleshooting Common Issues

• Ports are not available: ... address already in use This means the port Docker is trying to expose (e.g., 8000 or 5050) is used by another application on your machine.

  • Solution: In your compose.yml, change the host port mapping. For example, change ports: - "8000:8000" to ports: - "8080:8000".

• Container Exits Immediately/Doesn't Start:

  • Check container logs: docker compose logs <service_name>
  • Look for errors related to missing dependencies, incorrect commands, or application startup failures (e.g., invalid database URL).
  • Ensure all necessary files (like uv.lock, pyproject.toml, application code) are correctly copied into the image based on the .dockerignore.

• Database Connection Refused:

  • Ensure the postgres service is healthy. The backend and pgbouncer services depend on it via the service_healthy condition.
  • Verify that the DATABASE_URL in env/backend.env matches the credentials set in env/postgres.env and env/pgbouncer.env.