How do I run MatCraft with Docker?

Docker is the recommended way to run the full MatCraft platform locally or in production. We provide pre-built images and a Docker Compose configuration that sets up all services.

Quick Start with Docker Compose

# Clone the repository
git clone https://github.com/matcraft/matcraft.git
cd matcraft

# Copy and configure environment
cp .env.example .env
# Edit .env with your preferred settings (or use defaults for local dev)

# Start all services
docker compose up -d

This starts five containers:

| Service | Port | Description | |————-|———|——————-| | matcraft-api | 8000 | FastAPI backend | | matcraft-frontend | 3000 | Next.js dashboard | | matcraft-worker | — | Celery task worker | | matcraft-db | 5432 | PostgreSQL database | | matcraft-redis | 6379 | Redis for task queue |

Docker Compose File

The docker-compose.yml includes sensible defaults:

services:
  api:
    build: ./backend
    ports: ["8000:8000"]
    env_file: .env
    depends_on: [db, redis]
  frontend:
    build: ./frontend
    ports: ["3000:3000"]
    environment:
      NEXT_PUBLIC_API_URL: http://api:8000
  worker:
    build: ./backend
    command: celery -A materia.tasks worker --loglevel=info --concurrency=4
    env_file: .env
    depends_on: [db, redis]
  db:
    image: postgres:16-alpine
    volumes: [pgdata:/var/lib/postgresql/data]
    environment:
      POSTGRES_DB: matcraft
      POSTGRES_USER: matcraft
      POSTGRES_PASSWORD: matcraft
  redis:
    image: redis:7-alpine

GPU Support

For GPU-accelerated surrogate training, use the NVIDIA Container Toolkit:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

Production Considerations

• Mount a persistent volume for PostgreSQL data.
• Use a managed PostgreSQL service (RDS, Cloud SQL) for production workloads.
• Set strong passwords and a secure SECRET_KEY in your .env file.
• Configure a reverse proxy (nginx, Traefik) with TLS termination in front of the API and frontend.
• Scale workers horizontally by increasing the —concurrency flag or running multiple worker containers.