docker.recipes

Flask + PostgreSQL

intermediate

Python Flask microframework with PostgreSQL and Celery.

Overview

Flask is a lightweight Python microframework designed for building web applications and APIs with minimal boilerplate code. Created by Armin Ronacher in 2010, Flask follows the WSGI standard and embraces a 'micro' philosophy that provides core functionality while allowing developers to choose their preferred extensions and libraries. Its simplicity and flexibility have made it a popular choice for everything from simple web services to complex enterprise applications. This stack combines Flask's lightweight web framework with PostgreSQL's enterprise-grade relational database and Redis-powered Celery for asynchronous task processing. PostgreSQL provides ACID-compliant data storage with advanced features like JSON support and full-text search, while Redis serves as both a message broker for Celery workers and a high-performance cache. The Celery integration allows Flask applications to offload time-consuming operations like email sending, image processing, or report generation to background workers. This configuration is ideal for development teams building scalable web applications that need reliable data persistence, background job processing, and the flexibility to grow from prototype to production. Startups building SaaS platforms, development agencies creating client applications, and enterprises modernizing legacy systems will find this stack provides the right balance of simplicity and power without the complexity of larger frameworks like Django.

Key Features

  • Flask Blueprint architecture for modular application structure and reusable components
  • PostgreSQL 16 with JSON/JSONB support for hybrid relational-document data models
  • Celery worker processes for handling background tasks like email delivery and data processing
  • Redis-based message brokering with sub-millisecond task queuing performance
  • Flask-SQLAlchemy ORM integration with PostgreSQL for database operations and migrations
  • Multi-container architecture separating web server, database, cache, and worker concerns
  • Alpine Linux base images for minimal attack surface and faster container startup
  • PostgreSQL connection pooling support for handling concurrent database requests

Common Use Cases

  • 1SaaS applications requiring user authentication, billing, and background email processing
  • 2E-commerce platforms with product catalogs, inventory tracking, and order processing workflows
  • 3Content management systems with PostgreSQL's full-text search and JSON metadata storage
  • 4Data analytics dashboards with Celery handling report generation and PostgreSQL aggregations
  • 5API backends for mobile applications requiring real-time features and offline sync
  • 6Internal business tools with form processing, file uploads, and automated notifications
  • 7Prototype-to-production web applications that need to scale without framework migration

Prerequisites

  • Docker Desktop with 2GB+ available RAM for PostgreSQL and Redis operations
  • Python development knowledge including decorators, context managers, and package management
  • Basic SQL understanding for database schema design and query optimization
  • Environment file (.env) with DB_NAME, DB_USER, and DB_PASSWORD variables configured
  • Port 5000 available for Flask development server access
  • Understanding of asynchronous task concepts for effective Celery worker utilization

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  web: 
3    build: .
4    container_name: flask
5    environment: 
6      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
7      CELERY_BROKER_URL: redis://redis:6379/0
8    ports: 
9      - "5000:5000"
10    depends_on: 
11      - postgres
12      - redis
13    networks: 
14      - flask
15
16  postgres: 
17    image: postgres:16-alpine
18    container_name: postgres
19    environment: 
20      POSTGRES_DB: ${DB_NAME}
21      POSTGRES_USER: ${DB_USER}
22      POSTGRES_PASSWORD: ${DB_PASSWORD}
23    volumes: 
24      - postgres_data:/var/lib/postgresql/data
25    networks: 
26      - flask
27
28  redis: 
29    image: redis:alpine
30    container_name: redis
31    networks: 
32      - flask
33
34  celery: 
35    build: .
36    command: celery -A tasks worker --loglevel=info
37    environment: 
38      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
39      CELERY_BROKER_URL: redis://redis:6379/0
40    depends_on: 
41      - redis
42    networks: 
43      - flask
44
45volumes: 
46  postgres_data: 
47
48networks: 
49  flask: 
50    driver: bridge

.env Template

.env
1DB_NAME=flask
2DB_USER=flask
3DB_PASSWORD=changeme

Usage Notes

  1. 1Docs: https://flask.palletsprojects.com/
  2. 2Create Dockerfile with Python + gunicorn/uwsgi
  3. 3Access API at http://localhost:5000
  4. 4Celery worker handles async tasks (emails, processing)
  5. 5Flask-Migrate for database migrations: flask db upgrade
  6. 6Use Flask-SQLAlchemy for ORM

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

web
web:
  build: .
  container_name: flask
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    CELERY_BROKER_URL: redis://redis:6379/0
  ports:
    - "5000:5000"
  depends_on:
    - postgres
    - redis
  networks:
    - flask
postgres
postgres:
  image: postgres:16-alpine
  container_name: postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - flask
redis
redis:
  image: redis:alpine
  container_name: redis
  networks:
    - flask
celery
celery:
  build: .
  command: celery -A tasks worker --loglevel=info
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    CELERY_BROKER_URL: redis://redis:6379/0
  depends_on:
    - redis
  networks:
    - flask

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  web:
5    build: .
6    container_name: flask
7    environment:
8      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
9      CELERY_BROKER_URL: redis://redis:6379/0
10    ports:
11      - "5000:5000"
12    depends_on:
13      - postgres
14      - redis
15    networks:
16      - flask
17
18  postgres:
19    image: postgres:16-alpine
20    container_name: postgres
21    environment:
22      POSTGRES_DB: ${DB_NAME}
23      POSTGRES_USER: ${DB_USER}
24      POSTGRES_PASSWORD: ${DB_PASSWORD}
25    volumes:
26      - postgres_data:/var/lib/postgresql/data
27    networks:
28      - flask
29
30  redis:
31    image: redis:alpine
32    container_name: redis
33    networks:
34      - flask
35
36  celery:
37    build: .
38    command: celery -A tasks worker --loglevel=info
39    environment:
40      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
41      CELERY_BROKER_URL: redis://redis:6379/0
42    depends_on:
43      - redis
44    networks:
45      - flask
46
47volumes:
48  postgres_data:
49
50networks:
51  flask:
52    driver: bridge
53EOF
54
55# 2. Create the .env file
56cat > .env << 'EOF'
57DB_NAME=flask
58DB_USER=flask
59DB_PASSWORD=changeme
60EOF
61
62# 3. Start the services
63docker compose up -d
64
65# 4. View logs
66docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/flask-postgres/run | bash

Troubleshooting

  • ImportError for Flask extensions: Install requirements.txt dependencies in Dockerfile and rebuild container
  • Celery worker not processing tasks: Verify Redis connectivity and ensure task functions are properly decorated with @celery.task
  • PostgreSQL connection refused: Check database container startup order and verify DATABASE_URL environment variable format
  • Flask-Migrate version conflicts: Pin specific Flask-Migrate version in requirements.txt and ensure db folder is in COPY directive
  • Redis memory usage warnings: Configure Redis maxmemory policy in redis.conf or add command parameters to docker-compose
  • Static files not loading: Configure Flask static_folder path and ensure proper volume mounting for development

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

flaskpostgresredis

Tags

#flask#python#postgres#celery

Category

Full Web Stacks

Related Recipes

Ad Space