Local dev env for Python and Next.js with Docker

Python and JavaScript/TypeScript are the power tools in the AI ERA. Ace these, and you won't need any other programming language. Coming from a person who professionally uses/used Java, Kotlin, Go, Python, and C# in production.

I use Python as the backend and TypeScript (with Next.js) as the frontend technology stack for my AI boilerplate project, which focuses on AI-powered applications.

Docker Compose

Docker and Docker Compose make it easy to run the entire setup locally, providing seamless integration.

Here is the part of the Docker Compose file I use for running the AI kit locally (Makefile provided below):

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: aikit
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      LC_ALL: C.UTF-8
      LANG: C.UTF-8
      # PostgreSQL logging configuration
      POSTGRES_INITDB_ARGS: "-c log_line_prefix="
    command: ["postgres", "-c", "log_line_prefix="]
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d aikit"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    ports:
      - "8000:8000"
    volumes:
      - ./backend:/app
      - /app/__pycache__
      - backend_uploads:/app/uploads  # Volume for file uploads
    env_file:
      - .env
    environment:
      - ENVIRONMENT=development
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/aikit
      # JWT Configuration
      - SECRET_KEY=
      - ALGORITHM=
      - ACCESS_TOKEN_EXPIRE_MINUTES=
      # Supabase Configuration (optional, leave empty for local development)
      - SUPABASE_URL=${SUPABASE_URL:-}
      - SUPABASE_KEY=${SUPABASE_KEY:-}
      # S3 Configuration (will use S3 if all three are provided)
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
      - AWS_REGION=${AWS_REGION:-us-east-1}
      - S3_BUCKET_NAME=${S3_BUCKET_NAME:-}
      - S3_ENDPOINT_URL=${S3_ENDPOINT_URL:-}
      # Local storage (only used if no S3 or Supabase config is available)
      - LOCAL_STORAGE_PATH=/app/uploads
      - LOCAL_STORAGE_URL_PREFIX=http://localhost:8000/files
      # AI API Configurations
      - REPLICATE_API_TOKEN=${REPLICATE_API_TOKEN:-}
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    env_file:
      - ./frontend/.env.local
    depends_on:
      backend:
        condition: service_healthy

volumes:
  postgres_data:
  backend_uploads:

Docker files

Both the frontend and backend have their own Dockerfile for the development environment. These will be built when you execute docker-compose up.

Dockerfile for Python and FastAPI

FROM python:3.13-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    postgresql-client \
    curl \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

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

# Copy application code
COPY . .

# Create non-root user and uploads directory
RUN useradd --create-home --shell /bin/bash app
RUN mkdir -p /app/uploads
RUN chown -R app:app /app
USER app

EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

Dockerfile for Next.js and TypeScript

FROM node:24-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000

CMD ["npm", "run", "dev"]

I have enabled live reload for both systems.

Makefile

Makefile targets to start and stop the entire setup:

setup: ## Initial setup - copy env file and install dependencies
	@if [ ! -f .env ]; then \
		cp .env.example .env; \
		echo "Created .env file from .env.example"; \
		echo "Please edit .env file with your actual values"; \
	fi

build: ## Build all containers
	docker-compose build --no-cache

dev: setup ## Start development environment
	@echo "Starting development environment..."
	docker-compose up --build

up: ## Start all services in foreground
	docker-compose up

down: ## Stop all services
	docker-compose down