Known Limitations

⚠️ Important Note: Currently, the following features have limited functionality when running in Docker:

• Ollama integration: Local Ollama models do not work when running SurfSense in Docker. Please use other LLM providers like OpenAI or Gemini instead.
• Web crawler functionality: The web crawler feature currently doesn't work properly within the Docker environment.

We're actively working to resolve these limitations in future releases.

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:
  • PGVector setup
  • File Processing ETL Service (choose one):
    • Unstructured.io API key (Supports 34+ formats)
    • LlamaIndex API key (enhanced parsing, supports 50+ formats)
  • 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

Backend Environment Variables:

Optional Backend LangSmith Observability:

Backend Uvicorn Server Configuration:

For more details, see the Uvicorn documentation.

Frontend Environment Variables

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

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.