🚀 Dockerized Full-Stack FastAPI Application

A hands-on multi-container backend application built to understand how FastAPI, PostgreSQL, Redis, Nginx, and pgAdmin work together using Docker Compose.

📌 Table of Contents

📖 Project Overview
🎯 Objectives
✨ Features
🏗️ Architecture
🔄 Request Flow
🧩 Services
🧰 Technology Stack
📂 Project Structure
⚙️ Prerequisites
🚀 Getting Started
🔐 Environment Variables
🐳 Docker Commands
🌐 Application URLs
📡 API Endpoints
🗄️ PostgreSQL & pgAdmin
⚡ Redis Caching
🌐 Nginx Reverse Proxy
💾 Docker Volumes
🔗 Docker Networks
❤️ Health Checks
🔐 Security Considerations
🧪 Testing
🔍 Troubleshooting
🎥 Project Demonstration
📚 What I Learned
🔮 Future Improvements
🧠 Key Takeaways
👨‍💻 Author
⭐ Final Note

📖 Project Overview

This project demonstrates how a backend application can be split into multiple services and run together using Docker Compose.

The application contains:

FastAPI → REST API and core application logic
PostgreSQL → Persistent relational database
Redis → In-memory caching layer
Nginx → Reverse proxy and public application entry point
pgAdmin → Web-based PostgreSQL administration interface

The project was built as a hands-on learning exercise to understand:

Docker containerization
Multi-container application architecture
Service-to-service communication
Docker networking & isolation
Persistent volume storage
Environment-based configuration
Caching strategies & invalidation
Reverse proxy configurations
Container health checks

The architecture is intentionally production-inspired, while remaining lightweight enough to spin up locally with a single command.

🎯 Objectives

The primary goals of this project are:

Containerize a FastAPI application using a production-ready Dockerfile
Run multiple independent services in sync using Docker Compose
Connect FastAPI with PostgreSQL using an asynchronous driver/ORM
Implement Redis caching for read-heavy operations
Configure Nginx as a reverse proxy entry point
Attach Docker volumes for persistent database storage
Manage secrets and parameters using environment files
Isolate traffic across dedicated frontend and backend Docker networks
Implement container health checks to ensure proper boot sequencing
Master container-to-container communication using internal DNS

✨ Features

✅ FastAPI REST API: Asynchronous, high-performance web API
✅ PostgreSQL Database: Robust relational data storage
✅ SQLModel Integration: Unified ORM and Pydantic validation
✅ Psycopg Driver: Modern Python driver for PostgreSQL
✅ Redis Caching: Fast key-value retrieval for repeated queries
✅ Cache Invalidation: Automatic Redis cache purges upon user mutations
✅ Nginx Reverse Proxy: Traffic routing, header management, and isolation
✅ pgAdmin Web UI: Visual database dashboard for monitoring data
✅ Production-Style Dockerfile: Multi-stage build support
✅ Docker Compose Orchestration: Declarative multi-service setup
✅ Persistent Volumes: Data survives container lifecycles
✅ Network Segregation: Distinct frontend and backend bridge networks
✅ Health Checks: Container startup dependencies tied to service readiness
✅ Interactive Docs: Out-of-the-box Swagger UI via /docs

🏗️ Architecture

The application follows a decoupled multi-tier architecture:

                         ┌─────────────────┐
                         │     Browser     │
                         └────────┬────────┘
                                  │
                           localhost:8080
                                  │
                                  ▼
                         ┌─────────────────┐
                         │      Nginx      │
                         │ Reverse Proxy   │
                         └────────┬────────┘
                                  │
                         frontend network
                                  │
                                  ▼
                         ┌─────────────────┐
                         │     FastAPI     │
                         │    Backend      │
                         └───────┬─┬───────┘
                                 │ │
                         backend │ │ network
                    ┌────────────┘ └────────────┐
                    ▼                           ▼
             ┌─────────────┐             ┌─────────────┐
             │ PostgreSQL  │             │    Redis    │
             │  Database   │             │    Cache    │
             └─────────────┘             └─────────────┘
                    ▲
                    │
             ┌──────┴──────┐
             │   pgAdmin   │
             │ DB Manager  │
             └─────────────┘

Why These Components?

Component	Why It Exists
FastAPI	Provides the core backend REST API and business logic
PostgreSQL	Stores relational application data persistently
Redis	Provides ultra-fast temporary/cache storage
Nginx	Acts as a reverse proxy, security barrier, and entry point
pgAdmin	Provides a browser-based management interface for PostgreSQL
Docker	Packages applications and dependencies into reproducible containers
Docker Compose	Declares, connects, and orchestrates all containers together

🔄 Request Flow

1. GET `/users` (Read Flow)

Client
   │
   ▼
Nginx :8080
   │
   ▼
FastAPI :8000
   │
   ▼
Check Redis
   │
   ├──────── Cache Hit ────────► Return Cached Users
   │
   └──────── Cache Miss
                │
                ▼
           PostgreSQL
                │
                ▼
         Store Result in Redis
                │
                ▼
          Return Users

Why cache? Avoids querying PostgreSQL every time repeated, non-mutated data is requested, dramatically reducing database load.

2. POST `/users` (Write Flow)

Client
   │
   ▼
Nginx
   │
   ▼
FastAPI
   │
   ▼
PostgreSQL (Write record)
   │
   ▼
Invalidate Redis "users" Cache
   │
   ▼
Return Created User

Why invalidate? Ensures clients never receive stale user lists on subsequent reads after an insert.

🧩 Services

Service	Purpose	Container Port	Host Port	Network
fastapi	REST API Backend	`8000`	`8000` (optional)	frontend, backend
postgres	Database	`5432`	Not exposed	backend
redis	In-Memory Cache	`6379`	Not exposed	backend
nginx	Reverse Proxy	`80`	`8080`	frontend
pgadmin	Database UI	`80`	`5050`	backend

Core Concept: Port Forwarding

Host ports and container ports do not need to match:

ports:
  - "8080:80"

Host Machine (localhost:8080)
    │
    ▼
Nginx Container (port 80)

🧰 Technology Stack

Technology	Purpose
Python	Core programming language
FastAPI	High-performance backend web framework
SQLModel	ORM layer combining SQLAlchemy and Pydantic
Psycopg	Modern Python driver for PostgreSQL
PostgreSQL	Primary relational database
Redis	In-memory key-value cache
Nginx	Reverse proxy and HTTP gateway
pgAdmin	PostgreSQL management GUI
Docker	Containerization platform
Docker Compose	Multi-container coordination

📂 Project Structure

.
├── main.py              # FastAPI application and API endpoints
├── database.py          # Database connection, SQLModel engine, session dependencies
├── models.py            # SQLModel data models & schemas
├── requirements.txt     # Python application dependencies
│
├── Dockerfile           # FastAPI container image definition
├── docker-compose.yml   # Multi-service composition configuration
├── nginx.conf           # Reverse proxy configuration
│
├── .env                 # Local secrets and config (do NOT commit)
├── .env.example         # Template for environment variables
├── .gitignore           # Git untracked file rules
├── .dockerignore         # Docker context exclusions
│
└── README.md            # Comprehensive project documentation

⚙️ Prerequisites

Ensure you have the following installed locally:

Docker Desktop (Docker Engine ≥ 24.x, Docker Compose v2)
Git

Verify installations:

docker --version
docker compose version

🚀 Getting Started

1. Clone the Repository

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd <PROJECT_FOLDER>

2. Configure Environment Variables

Copy the sample environment file:

cp .env.example .env

Update credentials inside .env:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=myapp
PGADMIN_DEFAULT_EMAIL[email protected]
PGADMIN_DEFAULT_PASSWORD=your_password

3. Build & Run

Run all services using Docker Compose:

docker compose up --build -d

4. Verify Status

docker compose ps
docker compose logs -f

🔐 Environment Variables

Variable	Description
`POSTGRES_USER`	PostgreSQL superuser username
`POSTGRES_PASSWORD`	PostgreSQL superuser password
`POSTGRES_DB`	Application database name
`PGADMIN_DEFAULT_EMAIL`	Web login username/email for pgAdmin
`PGADMIN_DEFAULT_PASSWORD`	Web login password for pgAdmin

Internal Service Discovery

Inside Docker Compose networks, service names act as internal hostnames:

Database URL: postgresql+psycopg://postgres:your_password@postgres:5432/myapp
Redis URL: redis://redis:6379

🐳 Docker Commands

Action	Command
Start in background	`docker compose up -d`
Rebuild images & start	`docker compose up --build -d`
List container statuses	`docker compose ps`
Follow all logs	`docker compose logs -f`
Follow service logs	`docker compose logs -f <fastapi
Stop containers	`docker compose stop`
Tear down containers	`docker compose down`
Tear down & delete volumes	`docker compose down -v` ⚠️

🌐 Application URLs

Service	URL	Notes
Nginx → FastAPI	http://localhost:8080	Public Entry Point
FastAPI Direct	http://localhost:8000	Internal/Host debugging
Swagger UI Docs	http://localhost:8080/docs	Interactive API exploration
Health Check	http://localhost:8080/health	Uptime check
Redis Cache Test	http://localhost:8080/redis_test	Redis sanity endpoint
pgAdmin Web UI	http://localhost:5050	Database administration

📡 API Endpoints

1. Health Check

Endpoint: GET /health
Response:
```
{
  "status": "healthy"
}
```

2. Create User

Endpoint: POST /users

Payload:

{
  "name": "Vijay",
  "email": "[email protected]"
}

Action: Inserts user into PostgreSQL and clears the cached user list from Redis.

3. Get All Users

Endpoint: GET /users
Action: Fetches from Redis cache if available; queries PostgreSQL and populates cache on miss.

4. Test Redis Connectivity

Endpoint: GET /redis_test
Response:
```
{
  "redis_msg": "hello from redis"
}
```

🗄️ PostgreSQL & pgAdmin

FastAPI connects to PostgreSQL across the internal Docker bridge network using postgres:5432.

Accessing pgAdmin

Open http://localhost:5050.
Authenticate with PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD.
Add a new server connection using:
- Host name/address: postgres
- Port: 5432
- Maintenance database: myapp
- Username: postgres
- Password: <POSTGRES_PASSWORD>

⚡ Redis Caching

Redis acts as a low-latency read-through cache layer:

GET /users
      │
      ▼
 Check Redis
      │
 ┌────┴────┐
 │         │
Hit       Miss
 │         │
 ▼         ▼
Return   PostgreSQL
Data        │
            ▼
        Store in Redis
            │
            ▼
        Return Data

Cache invalidation occurs immediately when data changes:

POST /users ──► PostgreSQL ──► Delete "users" Redis Key

🌐 Nginx Reverse Proxy

Nginx acts as the single public gateway on port 8080:

Browser ──► Nginx (:80) ──► FastAPI (:8000)

Configuration snippet from nginx.conf:

events {}
http {
    server {
        listen 80;
        location / {
            proxy_pass http://fastapi:8000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

💾 Docker Volumes

PostgreSQL uses a named volume to ensure persistence across container removals:

volumes:
  postgres_data:

Mounted to:

/var/lib/postgresql/data

Key Takeaway: Stopping or recreating a container does not delete stored records. Data persists safely inside postgres_data until wiped with docker compose down -v.

🔗 Docker Networks

Network isolation ensures backend services are never directly reachable from the host machine or public internet.

                 frontend
                    │
                  Nginx
                    │
                 FastAPI
                    │
                 backend
             ┌──────┼──────┐
             │      │      │
        PostgreSQL Redis  pgAdmin

Frontend Network: Accessible by Nginx and FastAPI.
Backend Network: Accessible by FastAPI, PostgreSQL, Redis, and pgAdmin.

❤️ Health Checks

Container startup does not guarantee application readiness. Health checks ensure services only accept connections when fully booted:

PostgreSQL: Checked via pg_isready
Redis: Checked via redis-cli ping
FastAPI: Checked via GET /health

In docker-compose.yml:

depends_on:
  postgres:
    condition: service_healthy
  redis:
    condition: service_healthy

🔐 Security Considerations

This project focuses on architectural fundamentals. Good practices implemented:

Credentials managed via .env and excluded from source control via .gitignore
.env excluded from image layers via .dockerignore
Database and Cache ports (5432, 6379) are unexposed to the host
All internal communication happens within isolated private bridge networks

Recommended for Production

SSL/TLS Termination via Let's Encrypt / Certbot on Nginx
HashiCorp Vault or AWS Secrets Manager for credential storage
Rate limiting and WAF rules via Nginx
JWT-based authentication & role-based authorization
Automated database backup cron jobs to external storage (e.g., AWS S3)

🧪 Testing

The system was verified across key integration layers:

FastAPI: Verified endpoints (/health, /users, /docs) via Swagger and curl
Redis: Confirmed cache hits and invalidation logic with /redis_test and /users
PostgreSQL: Validated persistent data storage after container restarts
Nginx: Confirmed reverse proxy forwarding to upstream FastAPI containers
Docker: Monitored real-time system logs using docker compose logs

🔍 Troubleshooting

❌ PostgreSQL password authentication failed

PostgreSQL sets credentials on initial database creation. If .env is updated after the volume has already been initialized, the password won't change automatically.

Development Fix:

docker compose down -v
docker compose up --build -d

⚠️ Note: This deletes the database volume and all existing data.

❌ FastAPI cannot connect to PostgreSQL

Do not use localhost:5432 from inside a container. Use the Docker service name:

DATABASE_URL = "postgresql+psycopg://postgres:password@postgres:5432/myapp"

❌ FastAPI cannot connect to Redis

Use the Redis container service name:

REDIS_URL = "redis://redis:6379"

❌ Nginx cannot reach FastAPI

Verify that both services share the frontend network and that proxy_pass points to http://fastapi:8000;. Check logs:

docker compose logs nginx
docker compose logs fastapi

❌ Host port 8080 already in use

Change the host mapping in docker-compose.yml:

ports:
  - "8081:80"

❌ Stale or inconsistent Redis cache data

Restart the Redis container to flush memory:

docker compose restart redis

🎥 Project Demonstration

Key concepts verified during live testing:

Docker Images & Multi-Stage Builds: Creating lean application runtime layers.
Container Lifecycle: Running multi-service topologies in detached mode.
Volume Persistence: Proving data survival across container destructions.
Service Discovery: Validating name resolution via Docker internal DNS.
End-to-End Traffic Routing: Tracing requests from client browser through Nginx to FastAPI, PostgreSQL, and Redis.

📚 What I Learned

Docker Fundamentals: Images vs. containers, bind mounts vs. named volumes, bridge networks.
Service Orchestration: Coordinating dependencies and health status with Docker Compose.
Backend Architecture: Structuring production-ready APIs with FastAPI, SQLModel, and Psycopg.
Caching Mechanics: Handling read-through patterns and mitigating cache staleness.
Network Boundaries: Segmenting public-facing proxies from private backend databases.

🔮 Future Improvements

Automated database migrations using Alembic
Redis key expiration policies (TTL)
Unit & integration test suites run via Pytest in CI/CD
Centralized metric monitoring using Prometheus & Grafana
Cloud deployment via Kubernetes & Terraform
SSL/TLS automation using Let's Encrypt

🧠 Key Takeaways

Application ──► FastAPI ──┬──► PostgreSQL
                          └──► Redis
                             ▲
                             │
                           Nginx
                             ▲
                             │
                           Client

Understanding how individual services communicate, isolate, and persist data is far more valuable than simply knowing how to run docker compose up. Fundamentals compound.

👨‍💻 Author

Vijay Rangvani
IT Engineer | Backend & Cloud Explorer

Focus Areas: Python, FastAPI, Docker, Kubernetes, Cloud Architecture

⭐ Final Note

"Small steps look ordinary today, but they build the foundations for tomorrow."

Name		Name	Last commit message	Last commit date
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
database.py		database.py
docker-compose.yml		docker-compose.yml
main.py		main.py
models.py		models.py
nginx.conf		nginx.conf
redis_client.py		redis_client.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation