Build and Deploy a Flask App Using Docker

Why Containerize Flask Applications with Docker?

Containerizing Flask applications with Docker has become an essential skill for modern Python developers. Docker provides a consistent environment for your applications, eliminating the "works on my machine" problem and simplifying deployment across different platforms. Whether you're building a simple API or a complex web application, Dockerizing your Flask app ensures reliable, reproducible deployments from development to production.

This comprehensive guide walks you through the entire process of containerizing a Flask application, from creating your first Dockerfile to deploying a production-ready multi-container setup. You'll learn the fundamental concepts of Docker containers, how to write efficient Dockerfiles, and how to use Docker Compose to manage complex applications with databases and other services.

What You'll Learn

• Docker fundamentals and key concepts for Flask development
• Creating efficient Dockerfiles for Python applications
• Building and running Flask containers
• Managing multi-container applications with Docker Compose
• Production deployment best practices
• Advanced Docker patterns for Flask applications

Key Docker Concepts for Flask Development

Understanding Docker requires familiarity with several core concepts that work together to enable containerized applications.

Docker Images

Docker images serve as the templates for creating containers. An image contains the file system snapshot and configuration needed to run your application. Images are built from instructions in a Dockerfile and can be stored in registries like Docker Hub for easy sharing and distribution.

For Flask applications, you'll typically start with an official Python image that provides the Python interpreter and basic runtime environment. The official Python Docker images are well-maintained and include security updates.

Docker Containers

Docker containers are running instances of Docker images. When you run a container, Docker creates an isolated filesystem where your application executes. The container has its own network interfaces, process space, and filesystem, separate from the host system and other containers. This isolation prevents conflicts between applications and enhances security.

Dockerfiles

Dockerfiles are text files containing instructions for building Docker images. Each instruction in a Dockerfile creates a layer in the image, and Docker uses a layered filesystem that makes builds efficient and images compact. Learning to write efficient Dockerfiles is crucial for maintainable Flask deployments.

Docker Compose

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services, then start everything with a single command. For Flask applications that require databases, message queues, or other services, Docker Compose simplifies orchestration significantly. This approach is particularly valuable when working with our Python development services where complex backends are common.

Setting Up Your Flask Application for Docker

Before creating Docker configuration files, ensure your Flask application is structured appropriately for containerization. A well-organized project structure makes Docker builds more efficient and your application more maintainable.

Recommended Flask Project Structure

flask-docker-app/
├── app.py # Main Flask application
├── requirements.txt # Python dependencies
├── Dockerfile # Docker image build instructions
├── docker-compose.yml # Multi-container configuration
└── .dockerignore # Files to exclude from build context

The main Flask application file typically defines routes and application logic. For Docker deployment, ensure your application listens on all network interfaces by setting host="0.0.0.0" when running the Flask development server, though you'll use Gunicorn in production containers.

Managing Python Dependencies

The requirements.txt file lists all Python packages your application needs. This file is crucial for Docker builds because it determines what gets installed in your container. Create this file by running pip freeze > requirements.txt in your development environment.

For Flask applications, your requirements file should include Flask itself and any extensions you use:

Flask==3.0.0
gunicorn==21.2.0
psycopg2-binary==2.9.9

For production deployments, include production servers like Gunicorn, database adapters, and any other runtime dependencies. Keep development dependencies separate if you want smaller production images.

Configuring Flask for Containerized Environments

Flask applications in containers typically receive configuration through environment variables rather than hardcoded values. This approach allows the same Docker image to be configured differently for development, testing, and production environments:

import os

class Config:
 SECRET_KEY = os.environ.get('SECRET_KEY', 'default-dev-key')
 DATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///app.db')
 DEBUG = os.environ.get('DEBUG', 'False').lower() == 'true'

This configuration pattern enables you to pass different values when running containers, making your Docker images portable and secure. This pattern aligns with best practices for API development services where configuration management is critical.

Creating an Effective Dockerfile

The Dockerfile is the heart of your Docker-based Flask deployment. Writing an efficient Dockerfile reduces build times, minimizes image size, and improves security. This section details each component of a production-ready Flask Dockerfile.

Choosing a Base Image

FROM python:3.11-slim

The Python slim variant offers a good balance between size and convenience for most Flask applications. It includes Python and pip but omits many development tools, resulting in a smaller image. For even smaller images, consider python:3.11-alpine, though some packages may require additional system dependencies.

Installing Dependencies Efficiently

# Copy requirements first for better caching
COPY requirements.txt /tmp/requirements.txt

# Install Python dependencies
RUN pip install --no-cache-dir -r /tmp/requirements.txt

Docker builds images in layers, and understanding layer ordering optimizes your builds. Install dependencies before copying application code so that dependency installation is cached unless your requirements change. The --no-cache-dir flag prevents pip from caching downloaded packages, reducing image size.

Copying Application Files

WORKDIR /app
COPY . /app

The WORKDIR instruction sets the working directory for subsequent instructions and becomes the default location where your application runs. The COPY instruction transfers files from your build context into the container filesystem.

Configuring the Entry Point

EXPOSE 5000

ENTRYPOINT ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "app:app"]

The EXPOSE instruction documents the port your application listens on. Gunicorn is recommended for production because it's a robust, well-tested WSGI server that handles multiple worker processes efficiently.

Building and Running Your Flask Container

With your Dockerfile ready, you can build a Docker image and run containers. This section covers the essential Docker commands for working with Flask applications.

Building the Docker Image

docker build -t flask-app:latest .

The -t flag tags your image with a name and optionally a version. The . at the end specifies the build context--the directory Docker uses when processing the Dockerfile. Tagging your images with meaningful names helps manage multiple images and versions.

After building, verify the image exists with docker images, which shows all locally stored images along with their sizes and creation dates.

Running the Flask Container

docker run -p 8000:5000 -e FLASK_APP=app.py flask-app:latest

The -p 8000:5000 flag maps port 8000 on your host to port 5000 inside the container, making your application accessible at http://localhost:8000. The -e flag sets environment variables inside the container, which Flask uses to configure application behavior.

To run the container in the background (detached mode), add the -d flag:

docker run -d -p 8000:5000 flask-app:latest

Use docker ps to see running containers and docker logs <container-id> to view application output.

Container Lifecycle Management

Managing containers involves starting, stopping, and cleaning up containers and images:

• docker ps - View running containers
• docker stop <container-id> - Stop a running container
• docker rm <container-id> - Remove a stopped container
• docker logs <container-id> - View container logs
• docker exec -it <container-id> /bin/bash - Access shell inside container

For development workflows, the --rm flag automatically removes the container when it exits, keeping your environment clean. This approach is particularly useful during development when containers are started and stopped frequently.

Using Docker Compose for Multi-Container Applications

Production Flask applications often require databases, caches, message queues, or other services. Docker Compose simplifies running multi-container applications by defining all services in a single configuration file.

Introduction to Docker Compose

Docker Compose uses a YAML file to define services, networks, and volumes. With Compose, you describe your entire application stack declaratively, then start everything with a single command. This approach ensures consistent environments across development, testing, and production.

The docker-compose.yml file defines each service, including how to build or pull its image, what ports to expose, what environment variables to set, and what volumes to mount. Compose handles networking between services automatically, allowing containers to communicate using service names as hostnames.

Flask with PostgreSQL Example

A common Flask deployment pattern uses PostgreSQL as the database. Docker Compose orchestrates both the Flask application and the database container:

version: '3.8'

services:
 web:
 build: .
 ports:
 - "8000:5000"
 environment:
 - DATABASE_URL=postgresql://user:pass@db/mydb
 depends_on:
 - db

 db:
 image: postgres:15
 environment:
 - POSTGRES_USER=user
 - POSTGRES_PASSWORD=pass
 - POSTGRES_DB=mydb
 volumes:
 - postgres_data:/var/lib/postgresql/data

volumes:
 postgres_data:

The depends_on directive ensures the database starts before the Flask application. The volumes section creates persistent storage for the database, surviving container restarts. Service names become DNS names, so your Flask application connects to db at the DATABASE_URL.

Managing Multi-Container Applications

Docker Compose commands operate on your entire application stack:

• docker-compose up -d - Start all services in detached mode
• docker-compose logs - View logs from all services
• docker-compose logs -f - Follow logs in real-time
• docker-compose down - Stop and remove containers
• docker-compose down -v - Also remove volumes
• docker-compose down --build - Rebuild and restart containers

Production Deployment Considerations

Deploying Flask applications with Docker in production requires additional considerations beyond development workflows. Production environments demand reliability, security, and scalability.

Using Gunicorn for Production

Flask's built-in development server is unsuitable for production because it doesn't handle concurrent requests efficiently and lacks security hardening. Gunicorn (Green Unicorn) is the recommended WSGI server for Flask applications in production environments.

Gunicorn runs as your container's entry point, managing worker processes that handle HTTP requests. Configure Gunicorn with multiple workers based on your server's CPU cores and memory:

gunicorn --bind 0.0.0.0:5000 --workers 4 --access-logfile - --error-logfile - app:app

The --workers flag specifies how many worker processes handle requests. A common starting point is (2 * CPU cores) + 1, though this depends on your application's characteristics and available memory. For our enterprise web applications, proper worker configuration is essential for handling high traffic loads.

Health Checks and Container Orchestration

Production deployments benefit from health checks that monitor application health and enable automatic recovery. Docker and container orchestration platforms use health checks to determine when to restart unhealthy containers:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
 CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:5000/health')" || exit 1

This health check runs every 30 seconds, timing out after 10 seconds, with a 5-second initial grace period. If the check fails three consecutive times, Docker restarts the container.

Security Best Practices

Container security involves multiple layers, from the base image to running processes:

• Use specific image tags rather than latest to ensure reproducible builds
• Run containers as non-root users when possible
• Keep base images updated by rebuilding periodically
• Use Docker's image scanning tools to identify vulnerabilities
• Pin exact versions in your Dockerfile for production stability

FROM python:3.11.7-slim

RUN groupadd -r appgroup && useradd -r -g appgroup appuser
USER appuser

Advanced Docker Patterns for Flask

Beyond basic containerization, several advanced patterns enhance Flask application deployment with Docker.

Multi-Stage Builds for Smaller Images

Multi-stage builds separate the build environment from the runtime environment, producing smaller production images. This technique is particularly useful for applications with compilation dependencies:

# Build stage
FROM python:3.11 AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip wheel --no-cache-dir --no-deps -r requirements.txt

# Runtime stage
FROM python:3.11-slim
COPY --from=builder /build /usr/local/lib/python3.11/site-packages
COPY . /app
WORKDIR /app

The final image contains only the built packages and application code, without build tools, source files, or intermediate build artifacts. This approach can reduce image sizes by 50% or more.

Environment-Specific Configurations

Docker Compose supports multiple configuration files for different environments. Create docker-compose.yml for common configuration, docker-compose.override.yml for development overrides, and environment-specific files like docker-compose.production.yml:

# Development
docker-compose up

# Production
docker-compose -f docker-compose.yml -f docker-compose.production.yml up -d

This pattern keeps configurations maintainable while supporting different deployment scenarios.

CI/CD Integration

Docker integrates smoothly with continuous integration and continuous deployment pipelines. Build your Docker image in CI, push it to a container registry, then deploy to your target environment. This approach ensures consistent builds and enables quick rollbacks by redeploying previous image versions. Our DevOps consulting services can help you implement robust CI/CD pipelines for your Flask applications.

Conclusion

Containerizing Flask applications with Docker provides consistent, reproducible deployments from development through production. By understanding Docker fundamentals, writing efficient Dockerfiles, and using Docker Compose for complex applications, you gain significant advantages in reliability and deployment confidence.

The patterns covered in this guide--efficient Dockerfile construction, proper dependency management, production WSGI servers, multi-container orchestration, and security practices--form a foundation for production-ready Flask deployments. Start with the basics, then progressively adopt advanced patterns as your application and deployment requirements evolve.

Docker's ecosystem continues evolving, with improved orchestration tools, security features, and deployment options. Stay current with Docker best practices by consulting the official Docker documentation and community resources. With containerization as a core skill, you're well-positioned to deploy Flask applications reliably at any scale.

If you're looking to modernize your web application infrastructure or need expert guidance on containerization strategies, our team specializes in building and deploying containerized Python applications using Docker and modern DevOps practices.

Sources

1. DigitalOcean - How To Build and Deploy a Flask Application Using Docker
2. GeeksforGeeks - Dockerize your Flask App
3. Miguel Grinberg - The Flask Mega-Tutorial, Part XIX: Deployment on Docker Containers