Docker Installation

This guide explains how to run SurfSense using Docker, with options ranging from quick single-command deployment to full production setups.

Quick Start with Docker 🐳

Get SurfSense running in seconds with a single command:

One-Line Installation

Linux/macOS:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest

Windows (PowerShell):

docker run -d -p 3000:3000 -p 8000:8000 `
  -v surfsense-data:/data `
  --name surfsense `
  --restart unless-stopped `
  ghcr.io/modsetter/surfsense:latest

Note: A secure SECRET_KEY is automatically generated and persisted in the data volume on first run.

With Custom Configuration

Using OpenAI Embeddings:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  -e EMBEDDING_MODEL=openai://text-embedding-ada-002 \
  -e OPENAI_API_KEY=your_openai_api_key \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest

With Google OAuth:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  -e AUTH_TYPE=GOOGLE \
  -e GOOGLE_OAUTH_CLIENT_ID=your_client_id \
  -e GOOGLE_OAUTH_CLIENT_SECRET=your_client_secret \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest

Quick Start with Docker Compose

For easier management with environment files:

# Download the quick start compose file
curl -o docker-compose.yml https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker-compose.quickstart.yml

# Create .env file (optional - for custom configuration)
cat > .env << EOF
# EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
# ETL_SERVICE=DOCLING
# SECRET_KEY=your_custom_secret_key  # Auto-generated if not set
EOF

# Start SurfSense
docker compose up -d

After starting, access SurfSense at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Quick Start Environment Variables

Useful Commands

# View logs
docker logs -f surfsense

# Stop SurfSense
docker stop surfsense

# Start SurfSense
docker start surfsense

# Remove container (data preserved in volume)
docker rm surfsense

# Remove container AND data
docker rm surfsense && docker volume rm surfsense-data

Full Docker Compose Setup (Production)

For production deployments with separate services and more control, use the full Docker Compose setup below.

Prerequisites

Before you begin, ensure you have:

• Docker and Docker Compose installed on your machine
• Git (to clone the repository)
• Completed all the prerequisite setup steps including:
  • Auth setup
  • File Processing ETL Service (choose one):
    • Unstructured.io API key (Supports 34+ formats)
    • LlamaIndex API key (enhanced parsing, supports 50+ formats)
    • Docling (local processing, no API key required, supports PDF, Office docs, images, HTML, CSV)
  • Other required API keys

Installation Steps

1. Configure Environment Variables Set up the necessary environment variables:

   Linux/macOS:

   # Copy example environment files
   cp surfsense_backend/.env.example surfsense_backend/.env
   cp surfsense_web/.env.example surfsense_web/.env
   cp .env.example .env  # For Docker-specific settings

   Windows (Command Prompt):

   copy surfsense_backend\.env.example surfsense_backend\.env
   copy surfsense_web\.env.example surfsense_web\.env
   copy .env.example .env

   Windows (PowerShell):

   Copy-Item -Path surfsense_backend\.env.example -Destination surfsense_backend\.env
   Copy-Item -Path surfsense_web\.env.example -Destination surfsense_web\.env
   Copy-Item -Path .env.example -Destination .env

   Edit all .env files and fill in the required values:

Docker-Specific Environment Variables (Optional)

Note: Frontend environment variables with the NEXT_PUBLIC_ prefix are embedded into the Next.js production build at build time. Since the frontend now runs as a production build in Docker, these variables must be set in the root .env file (Docker-specific configuration) and will be passed as build arguments during the Docker build process.

Backend Environment Variables:

Optional Backend LangSmith Observability:

Backend Uvicorn Server Configuration:

For more details, see the Uvicorn documentation.

Frontend Environment Variables

Important: Frontend environment variables are now configured in the Docker-Specific Environment Variables section above since the Next.js application runs as a production build in Docker. The following NEXT_PUBLIC_* variables should be set in your root .env file:

• NEXT_PUBLIC_FASTAPI_BACKEND_URL - URL of the backend service
• NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE - Authentication method (LOCAL or GOOGLE)
• NEXT_PUBLIC_ETL_SERVICE - Document parsing service (should match backend ETL_SERVICE)

These variables are embedded into the application during the Docker build process and affect the frontend's behavior and available features.

2. Build and Start Containers

   Start the Docker containers:

   Linux/macOS/Windows:

   docker compose up --build

   To run in detached mode (in the background):

   Linux/macOS/Windows:

   docker compose up -d

   Note for Windows users: If you're using older Docker Desktop versions, you might need to use docker compose (with a space) instead of docker compose.

3. Access the Applications

   Once the containers are running, you can access:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs
   • pgAdmin: http://localhost:5050

Docker Services Overview

The Docker setup includes several services that work together:

• Backend: FastAPI application server
• Frontend: Next.js web application
• PostgreSQL (db): Database with pgvector extension
• Redis: Message broker for Celery
• Celery Worker: Handles background tasks (document processing, indexing, etc.)
• Celery Beat: Scheduler for periodic tasks (enables scheduled connector indexing)
  • The schedule interval can be configured using the SCHEDULE_CHECKER_INTERVAL environment variable in your backend .env file
  • Default: checks every minute for connectors that need indexing
• pgAdmin: Database management interface

All services start automatically with docker compose up. The Celery Beat service ensures that periodic indexing functionality works out of the box.

Using pgAdmin

pgAdmin is included in the Docker setup to help manage your PostgreSQL database. To connect:

1. Open pgAdmin at http://localhost:5050
2. Login with the credentials from your .env file (default: admin@surfsense.com / surfsense)
3. Right-click "Servers" > "Create" > "Server"
4. In the "General" tab, name your connection (e.g., "SurfSense DB")
5. In the "Connection" tab:
   • Host: db
   • Port: 5432
   • Maintenance database: surfsense
   • Username: postgres (or your custom POSTGRES_USER)
   • Password: postgres (or your custom POSTGRES_PASSWORD)
6. Click "Save" to connect

Useful Docker Commands

Container Management

• Stop containers:

  Linux/macOS/Windows:

  docker compose down

• View logs:

  Linux/macOS/Windows:

  # All services
  docker compose logs -f
  
  # Specific service
  docker compose logs -f backend
  docker compose logs -f frontend
  docker compose logs -f db

• Restart a specific service:

  Linux/macOS/Windows:

  docker compose restart backend

• Execute commands in a running container:

  Linux/macOS/Windows:

  # Backend
  docker compose exec backend python -m pytest
  
  # Frontend
  docker compose exec frontend pnpm lint

Troubleshooting

• Linux/macOS: If you encounter permission errors, you may need to run the docker commands with sudo.
• Windows: If you see access denied errors, make sure you're running Command Prompt or PowerShell as Administrator.
• If ports are already in use, modify the port mappings in the docker-compose.yml file.
• For backend dependency issues, check the Dockerfile in the backend directory.
• For frontend dependency issues, check the Dockerfile in the frontend directory.
• Windows-specific: If you encounter line ending issues (CRLF vs LF), configure Git to handle line endings properly with git config --global core.autocrlf true before cloning the repository.

Next Steps

Once your installation is complete, you can start using SurfSense! Navigate to the frontend URL and log in using your Google account.