Docker Installation

This guide explains how to run SurfSense using Docker Compose, which is the preferred and recommended method for deployment.

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.