Docker deployment

Overview

Docker provides a consistent, portable deployment environment for SKU Semantic Search. The included Docker Compose configuration sets up both the FastAPI application and PostgreSQL database with a single command.

Prerequisites

Docker: Version 20.10 or higher
Docker Compose: Version 2.0 or higher

Linux
macOS
Windows

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group (optional, avoids sudo)
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker-compose --version

Download Docker Desktop for Mac
Install the .dmg file
Start Docker Desktop

Verify:

docker --version
docker-compose --version

Download Docker Desktop for Windows
Install and enable WSL 2
Start Docker Desktop

Verify in PowerShell:

docker --version
docker-compose --version

Docker Compose configuration

The project includes a complete docker-compose.yml file:

services:
  api:
    build: .
    container_name: retail_rag_api
    ports:
      - "8000:8000"
    volumes:
      - .:/app  # Sync local code with container for live reloading
    environment:
      - DATABASE_URL=postgresql://postgres:db_pass@db:5435/retail_rag
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - JWT_SECRET=una_clave_secreta_muy_segura_para_el_mvp
    depends_on:
      db:
        condition: service_healthy
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

  db:
    image: pgvector/pgvector:pg16
    container_name: retail_rag_db
    ports:
      - "5435:5432"
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=db_pass
      - POSTGRES_DB=retail_rag
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Configuration breakdown

API service

Build context: . (current directory)

Uses the included Dockerfile to build the application image

Port mapping: 8000:8000

Exposes FastAPI on port 8000 of the host machine

Volume mount: .:/app

Syncs local code changes into the container
Enables live reloading during development

Environment variables:

DATABASE_URL: Uses db as hostname (Docker Compose service name)
GEMINI_API_KEY: Loaded from host .env file
JWT_SECRET: Hardcoded for demo (use secrets in production)

Dependencies:

depends_on with condition: service_healthy ensures PostgreSQL is ready before starting the API

Command:

--reload enables auto-restart on code changes (remove in production)

Database service

Image: pgvector/pgvector:pg16

Pre-built image with PostgreSQL 16 and pgvector extension

Port mapping: 5435:5432

External port 5435 avoids conflicts with local PostgreSQL
Internal port 5432 is standard PostgreSQL

Environment variables:

POSTGRES_USER: Superuser name
POSTGRES_PASSWORD: Superuser password (change in production!)
POSTGRES_DB: Default database to create

Volume: postgres_data

Named volume persists data across container restarts
Stored in Docker’s volume directory

Health check:

Runs pg_isready every 10 seconds
API service waits until this returns healthy

Volumes

postgres_data:

Named volume for database persistence
Survives docker-compose down
Deleted only with docker-compose down -v

Location:

# View volume details
docker volume inspect sku-semantic-search_postgres_data

Dockerfile

The application uses a multi-stage Dockerfile for efficient builds (Dockerfile:1):

# Use official lightweight Python image
FROM python:3.11-slim

# Prevent Python from writing .pyc files and force unbuffered output
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

# Set working directory
WORKDIR /app

# Install system dependencies for PostgreSQL
RUN apt-get update \
    && apt-get install -y gcc libpq-dev \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements first for better layer caching
COPY requirements.txt .

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

# Copy project code
COPY . .

# Expose FastAPI port
EXPOSE 8000

# Default startup command
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Optimization features:

Slim base image: python:3.11-slim reduces image size
Layer caching: Copying requirements.txt first allows Docker to cache dependencies
No cache: --no-cache-dir reduces image size by not storing pip cache
System dependencies: gcc and libpq-dev are needed to compile psycopg2-binary

Deployment steps

Clone repository

git clone https://github.com/your-username/sku-semantic-search.git
cd sku-semantic-search

Configure environment variables

Create a .env file in the project root:

# .env
GEMINI_API_KEY=your_gemini_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

Docker Compose automatically loads .env files. The GEMINI_API_KEY variable is passed to the container using ${GEMINI_API_KEY} syntax.

Build and start services

docker-compose up -d

This command:

Builds the API image from the Dockerfile
Pulls the pgvector PostgreSQL image
Creates a network for service communication
Starts both containers in detached mode

First run: Building the image takes 2-5 minutes depending on your connection.

Verify deployment

# Check container status
docker-compose ps

Expected output:

NAME                IMAGE                           STATUS
retail_rag_api      sku-semantic-search-api         Up
retail_rag_db       pgvector/pgvector:pg16          Up (healthy)

Both containers should show “Up” status.

View logs

# All services
docker-compose logs -f

# API only
docker-compose logs -f api

# Database only
docker-compose logs -f db

Press Ctrl+C to stop following logs.

Seed the database

docker-compose exec api python seed_data.py

This runs the seed script inside the API container, populating the database with sample products.

Access the API

The API is now available at:

Docker Compose commands

# Start in foreground (see logs)
docker-compose up

# Start in background (detached)
docker-compose up -d

# Rebuild images before starting
docker-compose up --build

Production deployment

For production environments, modify the configuration:

Production docker-compose.yml

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile.prod  # Production-optimized Dockerfile
    restart: always
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://sku_user:${DB_PASSWORD}@db:5432/sku_prod
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - JWT_SECRET=${JWT_SECRET}
    depends_on:
      db:
        condition: service_healthy
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
    # Remove volume mount for code sync

  db:
    image: pgvector/pgvector:pg16
    restart: always
    ports:
      - "5432:5432"  # Use standard port
    environment:
      - POSTGRES_USER=sku_user
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=sku_prod
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backups:/backups  # Backup directory
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sku_user"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  postgres_data:

Key changes for production:

restart: always - Containers restart on failure
--workers 4 - Multiple Uvicorn workers for concurrency
Removed --reload - No auto-restart on file changes
Removed code volume mount - Bakes code into image
All secrets loaded from environment (not hardcoded)
Backup volume for database dumps

Production Dockerfile

# Build stage
FROM python:3.11-slim AS builder

WORKDIR /app

RUN apt-get update && apt-get install -y gcc libpq-dev

COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# Runtime stage
FROM python:3.11-slim

WORKDIR /app

RUN apt-get update && apt-get install -y libpq5 && rm -rf /var/lib/apt/lists/*

# Copy dependencies from builder
COPY --from=builder /root/.local /root/.local

# Copy application
COPY app ./app

ENV PATH=/root/.local/bin:$PATH

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

Multi-stage benefits:

Smaller final image (build tools not included)
Faster deployments
Better security (no compilers in production)

Reverse proxy with Nginx

For production, place Nginx in front of the API:

services:
  nginx:
    image: nginx:alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - api

  api:
    # ... existing config
    expose:
      - "8000"  # Not published to host

nginx.conf:

upstream fastapi {
    server api:8000;
}

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://fastapi;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Monitoring and logging

View container metrics

# Real-time resource usage
docker stats retail_rag_api retail_rag_db

# Container inspection
docker inspect retail_rag_api

Centralized logging

Configure Docker to use a logging driver:

services:
  api:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

For production, consider:

ELK Stack: Elasticsearch, Logstash, Kibana
Loki: Grafana Loki for log aggregation
CloudWatch: AWS CloudWatch Logs

Troubleshooting

Port already in use

Error: Bind for 0.0.0.0:8000 failed: port is already allocatedSolution:

# Find process using port 8000
sudo lsof -i :8000  # Linux/macOS
netstat -ano | findstr :8000  # Windows

# Kill the process or change port in docker-compose.yml
ports:
  - "8001:8000"  # Use 8001 externally

Database connection fails

Error: psycopg2.OperationalError: could not connect to serverSolution:

Check database is healthy: docker-compose ps
View database logs: docker-compose logs db
Verify DATABASE_URL uses db as hostname (not localhost)
Wait for health check: API starts only when DB is ready

Image build fails

Error: During docker-compose up --buildSolution:

Check Dockerfile syntax
Ensure requirements.txt exists and is valid
Clear build cache: docker-compose build --no-cache
Check disk space: docker system df

Changes not reflected

Symptoms: Code changes don’t appear in running containerSolution:

Verify volume mount exists: - .:/app
Check --reload flag is present in command
For Dockerfile changes, rebuild: docker-compose up --build
Restart services: docker-compose restart api

Next steps

Environment setup

Configure environment variables for Docker

Database setup

Optimize PostgreSQL for production

Architecture overview

Understand the deployed system architecture

Quickstart

Test the deployed API

Get Started

Architecture

Guides

Overview

Prerequisites

Docker Compose configuration

Configuration breakdown

Dockerfile

Deployment steps

Docker Compose commands

Production deployment

Production docker-compose.yml

Production Dockerfile

Reverse proxy with Nginx

Monitoring and logging

View container metrics

Centralized logging

Troubleshooting

Next steps

Environment setup

Database setup

Architecture overview

Quickstart

Build docs developers (and LLMs) love

Get Started

Architecture

Guides

​Overview

​Prerequisites

​Docker Compose configuration

​Configuration breakdown

​Dockerfile

​Deployment steps

​Docker Compose commands

​Production deployment

​Production docker-compose.yml

​Production Dockerfile

​Reverse proxy with Nginx

​Monitoring and logging

​View container metrics

​Centralized logging

​Troubleshooting

​Next steps

Environment setup

Database setup

Architecture overview

Quickstart

Build docs developers (and LLMs) love

Overview

Prerequisites

Docker Compose configuration

Configuration breakdown

Dockerfile

Deployment steps

Docker Compose commands

Production deployment

Production docker-compose.yml

Production Dockerfile

Reverse proxy with Nginx

Monitoring and logging

View container metrics

Centralized logging

Troubleshooting

Next steps