1. Project Setup and Requirements#

Assume a standard Python project structure, including a requirements.txt file listing dependencies.

1
my_python_app/
2
├── app.py
3
└── requirements.txt

requirements.txt might look like:

1
Flask==2.2.2
2
gunicorn==20.1.0

app.py could be a simple Flask application:

1
from flask import Flask
2

3
app = Flask(__name__)
4

5
@app.route('/')
6
def hello():
7
    return 'Hello, Docker!'
8

9
if __name__ == '__main__':
10
    app.run(host='0.0.0.0', port=5000)

2. Creating the Dockerfile#

Create a file named Dockerfile in the root of the project directory.

1
# Use an official Python runtime as a parent image
2
FROM python:3.9-slim
3

4
# Set the working directory in the container
5
WORKDIR /app
6

7
# Copy the requirements file into the container at /app
8
COPY requirements.txt .
9

10
# Install any needed packages specified in requirements.txt
11
RUN pip install --no-cache-dir -r requirements.txt
12

13
# Copy the rest of the application code into the container
14
COPY . .
15

16
# Make port 5000 available to the world outside this container
17
EXPOSE 5000
18

19
# Run the application using Gunicorn (a production-ready WSGI server)
20
# Replace 'app:app' with your application's entry point if different
21
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

Explanation of Dockerfile Instructions:

• FROM python:3.9-slim: Selects the base image. Using a slim version (-slim) is recommended as it reduces image size by including only essential components, leading to faster builds, smaller storage footprints, and potentially fewer security vulnerabilities compared to full versions.
• WORKDIR /app: Sets the current working directory inside the container. Subsequent commands like COPY and RUN will execute relative to this directory.
• COPY requirements.txt .: Copies the requirements.txt file from the host machine (where the Docker build command is run) to the /app directory inside the container. This is done before copying the rest of the code to leverage Docker’s layer caching. If only requirements.txt changes, Docker can use a cached layer for the RUN pip install step, significantly speeding up subsequent builds.
• RUN pip install --no-cache-dir -r requirements.txt: Executes the pip installation command inside the container. --no-cache-dir is used to prevent pip from storing cache data, further reducing the image size.
• COPY . .: Copies the remaining files from the current directory on the host (the application code) into the /app directory inside the container.
• EXPOSE 5000: Informs Docker that the container listens on port 5000 at runtime. This is documentation; it does not actually publish the port. Port mapping is done when running the container.
• CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]: Specifies the command to run when the container starts. Using a production-grade WSGI server like Gunicorn or uWSGI is standard practice for Python web applications in production, as they handle requests more robustly than Flask’s built-in server. 0.0.0.0 binds to all available network interfaces inside the container. app:app refers to the Flask application instance named app within the app.py module.

3. Building the Docker Image#

Navigate to the project directory in the terminal and execute the build command:

1
docker build -t my-python-app:latest .

• docker build: The command to build a Docker image.
• -t my-python-app:latest: Tags the image with a name (my-python-app) and a tag (latest). Tags are useful for versioning images.
• .: Specifies the build context – the set of files located in the specified path (. means the current directory) that the Docker daemon can access.

This process reads the Dockerfile and executes each instruction, creating layers that compose the final image.

4. Running the Docker Container (Local Development)#

To run the application locally in a container:

1
docker run -p 5000:5000 my-python-app:latest

• docker run: Command to start a container from an image.
• -p 5000:5000: Maps port 5000 on the host machine to port 5000 inside the container. Accessing http://localhost:5000 on the host machine will forward the request to the container.
• my-python-app:latest: The image to run.

The application should now be accessible via a web browser at http://localhost:5000.

5. Using Docker Compose for Local Development#

For applications with multiple services (like a web app and a database), Docker Compose simplifies the local development environment.

Create a docker-compose.yml file in the project root:

1
version: '3.8'
2

3
services:
4
  web:
5
    build: .
6
    ports:
7
      - "5000:5000"
8
    volumes:
9
      # Mount the current directory into the container's workdir
10
      # This allows code changes on the host to reflect instantly in the container (useful for development)
11
      - .:/app
12
    # Override the command to run the Flask development server
13
    # This is less robust than Gunicorn but provides auto-reloading during development
14
    command: python app.py
15
    environment:
16
      # Example: pass environment variables for local dev
17
      FLASK_ENV: development
18
      DATABASE_URL: postgres://user:password@db:5432/mydatabase # Example URL
19

20
  # Example database service
21
  db:
22
    image: postgres:13-alpine
23
    environment:
24
      POSTGRES_DB: mydatabase
25
      POSTGRES_USER: user
26
      POSTGRES_PASSWORD: password
27
    volumes:
28
      # Persist database data
29
      - db_data:/var/lib/postgresql/data
30

31
volumes:
32
  db_data:

• version: '3.8': Specifies the Docker Compose file format version.
• services: Defines the containers (services) that make up the application.
• web: Defines the web application service.
  • build: .: Tells Compose to build the image using the Dockerfile in the current directory (.).
  • ports: - "5000:5000": Maps host port 5000 to container port 5000.
  • volumes: - .:/app: Crucial for local development. This binds the current host directory (.) to the /app directory inside the container. Changes made to code on the host are immediately visible inside the container without rebuilding the image. This volume mount should typically be removed or changed for production deployments.
  • command: python app.py: Overrides the Dockerfile’s CMD to run the Flask development server, which often includes features like code auto-reloading.
  • environment: Sets environment variables inside the container.
• db: Defines a database service using a standard PostgreSQL image.
  • image: postgres:13-alpine: Specifies the image to use. alpine variants are small and efficient.
  • environment: Sets environment variables required by the PostgreSQL image to initialize the database.
  • volumes: - db_data:/var/lib/postgresql/data: Mounts a named volume (db_data) to the standard PostgreSQL data directory inside the container. This ensures that the database data persists even if the db container is removed and recreated.
• volumes: Declares the named volumes used.

Run the multi-container application:

1
docker-compose up --build

• docker-compose up: Starts the services defined in docker-compose.yml.
• --build: Builds images if they don’t exist or have changed.

For running in detached mode (in the background):

1
docker-compose up --build -d

To stop the services:

1
docker-compose down

6. Transitioning to Production#

Deploying the containerized Python application to production involves different considerations compared to local development.

• Image Tagging: Use meaningful tags (e.g., Git commit hash, version number) instead of latest for production deployments to ensure deploying a specific, known version.
• Production Dockerfile: While a single Dockerfile can sometimes suffice, using a multi-stage build can create a smaller, more secure final image by separating build-time dependencies from runtime dependencies. Alternatively, ensure the production Dockerfile doesn’t include dev-only tools or debug configurations.
• Removing Development Volumes: The code volume mount (.:/app) used for local development should not be used in production. The production image should contain the application code copied via the COPY . . instruction.
• Configuration Management: Environment variables are the standard way to pass configuration (database credentials, API keys, settings) to containers in production. Avoid hardcoding sensitive information in the Dockerfile or application code. Utilize secret management systems provided by orchestration platforms or cloud providers.
• Persistent Storage: For stateful services like databases, persistent storage is critical. Production deployments typically use managed database services (like AWS RDS, Google Cloud SQL) or persistent volumes managed by an orchestration platform (like Kubernetes Persistent Volumes) rather than Docker named volumes managed by a single Docker Compose file on a single host.
• Orchestration: For scaling, high availability, automated deployments, and management of containerized applications in production, container orchestration platforms are essential. Popular choices include:
  • Kubernetes: A powerful, open-source system for automating deployment, scaling, and management of containerized applications.
  • Docker Swarm: Docker’s native clustering and orchestration solution, simpler than Kubernetes but less feature-rich.
  • Cloud Provider Services: Amazon Elastic Container Service (ECS), Amazon Elastic Kubernetes Service (EKS), Google Kubernetes Engine (GKE), Azure Kubernetes Service (AKS) provide managed orchestration.
• Image Registry: Push the production-ready image to a container registry accessible by the production environment.

1
docker tag my-python-app:latest myregistry/my-python-app:v1.0.0
2
docker push myregistry/my-python-app:v1.0.0

The orchestration platform or deployment script on the production server then pulls myregistry/my-python-app:v1.0.0 to deploy it.