SurfSense

https://www.surfsense.com/docs
Admin
SurfSense is a platform that facilitates data extraction, transformation, and loading (ETL) for...
Tokens:16,786
Snippets:191
Trust Score:7
Update:8 months ago
Show doc for...
Tokens:
Raw
### Start the Backend Application

Source: https://www.surfsense.com/docs/how-to/electric-sql

This command starts the backend application using `uv`. Ensure you are in the correct directory and all dependencies are installed.

```bash
uv run main.py
```

--------------------------------

### Copy Environment Files (Windows PowerShell)

Source: https://www.surfsense.com/docs/docker-installation

Copies example environment configuration files to active `.env` files using the `Copy-Item` cmdlet in Windows PowerShell. This method is used for environment setup in PowerShell environments on 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
```

--------------------------------

### Quick Start Docker Installation (Linux/macOS)

Source: https://www.surfsense.com/docs/docker-installation

Installs and runs SurfSense using a single Docker command on Linux or macOS. It maps ports, mounts a data volume for persistence, and sets the container to restart automatically. A secure SECRET_KEY is generated and persisted.

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

--------------------------------

### Install Frontend Dependencies (Linux/macOS/Windows)

Source: https://www.surfsense.com/docs/manual-installation

Installs frontend dependencies using pnpm. It first ensures pnpm is installed globally and then installs the project's dependencies.

```bash
# Install pnpm if you don't have it
npm install -g pnpm

# Install dependencies
pnpm install
```

--------------------------------

### Quick Start with Docker Compose

Source: https://www.surfsense.com/docs/docker-installation

Sets up SurfSense using Docker Compose for easier management, especially with environment files. It downloads a compose file, optionally creates a .env file for custom configurations, and starts SurfSense in detached mode.

```bash
# 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
```

--------------------------------

### Quick Start Docker Installation (Windows PowerShell)

Source: https://www.surfsense.com/docs/docker-installation

Installs and runs SurfSense using a single Docker command in Windows PowerShell. It maps ports, mounts a data volume for persistence, and sets the container to restart automatically. A secure SECRET_KEY is generated and persisted.

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

--------------------------------

### Copy Environment Files (Linux/macOS)

Source: https://www.surfsense.com/docs/docker-installation

Copies the example environment configuration files to active `.env` files for the backend, web, and Docker configurations using the `cp` command. This is typically done to set up the project's environment variables.

```bash
cp surfsense_backend/.env.example surfsense_backend/.env
cp surfsense_web/.env.example surfsense_web/.env
cp .env.example .env
```

--------------------------------

### Install Backend Dependencies with uv (Windows PowerShell)

Source: https://www.surfsense.com/docs/manual-installation

Installs the 'uv' package manager and then synchronizes backend dependencies for the project on Windows systems using PowerShell. This command fetches and installs all necessary libraries for the backend.

```powershell
# Install uv if you don't have it
iwr -useb https://astral.sh/uv/install.ps1 | iex

# Install dependencies
uv sync
```

--------------------------------

### Start Docker Compose Services for PostgreSQL and Electric SQL

Source: https://www.surfsense.com/docs/how-to/electric-sql

This command initiates the PostgreSQL database and Electric SQL services using Docker Compose. It's a prerequisite for running SurfSense with a Docker-managed PostgreSQL instance and requires the `docker-compose.yml` file to be present in the current directory.

```bash
docker-compose up -d db electric
```

--------------------------------

### Configure Frontend Environment (Linux/macOS)

Source: https://www.surfsense.com/docs/manual-installation

Copies the example environment file to a new file and changes the directory to 'surfsense_web' on Linux or macOS.

```bash
cd surfsense_web
cp .env.example .env
```

--------------------------------

### Start Electric SQL Service

Source: https://www.surfsense.com/docs/how-to/electric-sql

This command uses Docker Compose to start the Electric SQL service in detached mode (`-d`). Ensure your `docker-compose.yml` file is correctly configured.

```bash
docker-compose up -d electric
```

--------------------------------

### Install Backend Dependencies with uv (Windows Command Prompt)

Source: https://www.surfsense.com/docs/manual-installation

Synchronizes backend dependencies for the project using the 'uv' package manager in the Windows Command Prompt. This command assumes 'uv' has already been installed.

```batch
# Install dependencies with uv (after installing uv)
uv sync
```

--------------------------------

### Configure Frontend Environment (Windows Command Prompt)

Source: https://www.surfsense.com/docs/manual-installation

Copies the example environment file to a new file and changes the directory to 'surfsense_web' using Windows Command Prompt.

```cmd
cd surfsense_web
copy .env.example .env
```

--------------------------------

### Custom Docker Installation with Environment Variables

Source: https://www.surfsense.com/docs/docker-installation

Runs SurfSense with Docker, allowing customization through environment variables. This example configures embedding models, API keys for OpenAI and LlamaCloud, and Google OAuth credentials. Ensure to replace placeholders with your actual keys and IDs.

```bash
docker run -d -p 3000:3000 -p 8000:8000 -p 5133:5133 \
  -v surfsense-data:/data \
  -e EMBEDDING_MODEL=openai://text-embedding-ada-002 \
  -e OPENAI_API_KEY=your_openai_api_key \
  -e AUTH_TYPE=GOOGLE \
  -e GOOGLE_OAUTH_CLIENT_ID=your_google_client_id \
  -e GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret \
  -e ETL_SERVICE=LLAMACLOUD \
  -e LLAMA_CLOUD_API_KEY=your_llama_cloud_key \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Copy Environment Files (Windows Command Prompt)

Source: https://www.surfsense.com/docs/docker-installation

Copies example environment configuration files to active `.env` files using the `copy` command in the Windows Command Prompt. This process is essential for setting up project-specific environment variables on Windows.

```batch
copy surfsense_backend\.env.example surfsense_backend\.env
copy surfsense_web\.env.example surfsense_web\.env
copy .env.example .env
```

--------------------------------

### Configure Frontend Environment (Windows PowerShell)

Source: https://www.surfsense.com/docs/manual-installation

Copies the example environment file to a new file and changes the directory to 'surfsense_web' using Windows PowerShell.

```powershell
cd surfsense_web
Copy-Item -Path .env.example -Destination .env
```

--------------------------------

### Run SurfSense with Electric SQL using Docker (All-in-One)

Source: https://www.surfsense.com/docs/how-to/electric-sql

This command starts the SurfSense application using a single Docker container that includes PostgreSQL, Redis, Electric SQL, the backend API, and the frontend. It maps necessary ports and mounts a volume for persistent data. Access the application at http://localhost:3000.

```bash
docker run -d \
  -p 3000:3000 \
  -p 8000:8000 \
  -p 5133:5133 \
  -v surfsense-data:/data \
  --name surfsense \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Run Backend Server (uv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the backend server using 'uv'. Provides options for running with or without hot reloading, which is useful for development.

```bash
# Run without hot reloading
uv run main.py

# Or with hot reloading for development
uv run main.py --reload
```

--------------------------------

### Enable Logical Replication in PostgreSQL

Source: https://www.surfsense.com/docs/how-to/electric-sql

This section provides instructions on how to enable logical replication in a PostgreSQL instance by modifying the `postgresql.conf` file. Logical replication is a requirement for Electric SQL to detect and stream database changes to the frontend. The example shows how to open the configuration file using `vim` and lists common file locations.

```bash
# Common locations:
# macOS (Homebrew): /opt/homebrew/var/postgresql@15/postgresql.conf
# Linux: /etc/postgresql/15/main/postgresql.conf
# Windows: C:\\Program Files\\PostgreSQL\\15\\data\\postgresql.conf

sudo vim /path/to/postgresql.conf

# Add the following settings:

```

--------------------------------

### Install Backend Dependencies with uv (Linux/macOS)

Source: https://www.surfsense.com/docs/manual-installation

Installs the 'uv' package manager and then synchronizes backend dependencies for the project on Linux and macOS systems. This ensures all required libraries are available for the backend to run.

```bash
# Install uv if you don't have it
curl -fsSL https://astral.sh/uv/install.sh | bash

# Install dependencies
uv sync
```

--------------------------------

### Run SurfSense with Jira Connector using Docker

Source: https://www.surfsense.com/docs/connectors/jira

This Docker command starts the SurfSense application with the Jira connector enabled. It maps ports, mounts a volume for data persistence, and sets essential Atlassian environment variables for authentication.

```bash
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Jira Connector
  -e ATLASSIAN_CLIENT_ID=your_atlassian_client_id \
  -e ATLASSIAN_CLIENT_SECRET=your_atlassian_client_secret \
  -e JIRA_REDIRECT_URI=http://localhost:8000/api/v1/auth/jira/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Run Backend Server (pip/venv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the backend server using Python and a virtual environment. Includes instructions for activating the environment and running with or without hot reloading.

```bash
# Activate virtual environment if not already activated
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

# Run without hot reloading
python main.py

# Or with hot reloading for development
python main.py --reload
```

--------------------------------

### Run Frontend Development Server

Source: https://www.surfsense.com/docs/manual-installation

Starts the Next.js development server for the frontend application. This command is cross-platform compatible.

```bash
pnpm run dev
```

--------------------------------

### Useful Docker Management Commands

Source: https://www.surfsense.com/docs/docker-installation

Provides essential Docker commands for managing the SurfSense container. Includes viewing logs, stopping, starting, removing the container, and removing both the container and its associated data volume.

```bash
# 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
```

--------------------------------

### Start Redis Server (Linux)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Redis server on Linux systems using systemctl. Redis is a required component for the Celery task queue used in the project.

```bash
# Start Redis server
sudo systemctl start redis
```

--------------------------------

### Start Celery Flower (uv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Celery Flower monitoring tool using 'uv'. This allows you to visualize and manage Celery tasks from a web interface.

```bash
# If using uv
uv run celery -A celery_worker.celery_app flower --port=5555
```

--------------------------------

### Copy Environment File (Windows Command Prompt)

Source: https://www.surfsense.com/docs/manual-installation

Copies the example environment file to a new file named .env using the command prompt on Windows. This prepares the environment for variable configuration.

```batch
cd surfsense_backend
copy .env.example .env
```

--------------------------------

### Run Database Migrations for SurfSense Backend

Source: https://www.surfsense.com/docs/how-to/electric-sql

This command executes database migrations for the SurfSense backend using Alembic. It ensures that the database schema is up-to-date with the latest changes required by the application. This step is necessary after starting the database and Electric SQL services.

```bash
cd surfsense_backend
uv run alembic upgrade head
```

--------------------------------

### Start and Manage Redis Server

Source: https://www.surfsense.com/docs/manual-installation

Commands to start, stop, and manage the Redis server on different operating systems and using Docker. This includes using package managers, direct execution, and Docker containers.

```bash
# macOS: If installed via Homebrew
brew services start redis

# macOS: Or run directly
redis-server

# Windows: If using Redis on Windows (via WSL or Windows port)
redis-server

# Windows: If installed as a Windows service
net start Redis

# Docker: Pull and run Redis container
docker run -d --name redis -p 6379:6379 redis:latest

# Docker: To stop Redis
docker stop redis

# Docker: To start Redis again
docker start redis

# Docker: To remove Redis container
docker rm -f redis
```

--------------------------------

### Verify Electric SQL Health Check

Source: https://www.surfsense.com/docs/how-to/electric-sql

This `curl` command sends a GET request to the Electric SQL health endpoint. A successful response indicates that Electric SQL is running and accessible.

```bash
curl http://localhost:5133/v1/health
```

--------------------------------

### Copy Environment File (Linux/macOS)

Source: https://www.surfsense.com/docs/manual-installation

Copies the example environment file to a new file named .env on Linux and macOS systems. This is the first step in configuring the project's environment variables.

```bash
cd surfsense_backend
cp .env.example .env
```

--------------------------------

### Start Celery Flower (pip/venv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Celery Flower monitoring tool using a Python virtual environment. Ensure the virtual environment is activated before running this command.

```bash
# If using pip/venv (activate venv first)
celery -A celery_worker.celery_app flower --port=5555
```

--------------------------------

### Start Celery Beat (uv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Celery Beat scheduler using 'uv'. This is essential for running periodic tasks defined in your Celery application.

```bash
# Make sure you're in the surfsense_backend directory
cd surfsense_backend

# Start Celery Beat
uv run celery -A celery_worker.celery_app beat --loglevel=info
```

--------------------------------

### Configure ClickUp Connector Environment Variables for Docker

Source: https://www.surfsense.com/docs/connectors/clickup

This command demonstrates how to set the necessary environment variables for the ClickUp connector when running SurfSense via Docker. It includes placeholders for your ClickUp Client ID, Client Secret, and the Redirect URI, which are essential for establishing the OAuth connection.

```bash
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # ClickUp Connector
  -e CLICKUP_CLIENT_ID=your_clickup_client_id \
  -e CLICKUP_CLIENT_SECRET=your_clickup_client_secret \
  -e CLICKUP_REDIRECT_URI=http://localhost:8000/api/v1/auth/clickup/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Start Celery Beat (pip/venv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Celery Beat scheduler using a Python virtual environment. This command requires the virtual environment to be activated.

```bash
# Make sure you're in the surfsense_backend directory
cd surfsense_backend

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

# Start Celery Beat
celery -A celery_worker.celery_app beat --loglevel=info
```

--------------------------------

### Configure Airtable Environment Variables for Docker

Source: https://www.surfsense.com/docs/connectors/airtable

This command demonstrates how to run the SurfSense Docker container with the necessary environment variables for the Airtable connector. It includes placeholders for your Airtable Client ID, Client Secret, and Redirect URI.

```bash
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Airtable Connector
  -e AIRTABLE_CLIENT_ID=your_airtable_client_id \
  -e AIRTABLE_CLIENT_SECRET=your_airtable_client_secret \
  -e AIRTABLE_REDIRECT_URI=http://localhost:8000/api/v1/auth/airtable/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Configure Jira API Scopes for SurfSense

Source: https://www.surfsense.com/docs/connectors/jira

These scopes define the level of access the SurfSense integration will have to your Jira data. 'read:jira-work' allows reading issue data, while 'read:jira-user' allows viewing user profiles.

```text
read:jira-work
read:jira-user
```

--------------------------------

### Start Celery Worker (uv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Celery worker using the 'uv' Python package manager. This command assumes you are in the 'surfsense_backend' directory and need to handle background tasks.

```bash
# Make sure you're in the surfsense_backend directory
cd surfsense_backend

# Start Celery worker
uv run celery -A celery_worker.celery_app worker --loglevel=info --concurrency=1 --pool=solo
```

--------------------------------

### Run SurfSense with Custom Electric SQL Credentials via Docker

Source: https://www.surfsense.com/docs/how-to/electric-sql

This command launches the SurfSense Docker container with custom credentials for Electric SQL. It allows you to specify the database user and password using environment variables, overriding the defaults. Ensure the specified user and password match your PostgreSQL setup.

```bash
docker run -d \
  -p 3000:3000 \
  -p 8000:8000 \
  -p 5133:5133 \
  -v surfsense-data:/data \
  -e ELECTRIC_DB_USER=your_electric_user \
  -e ELECTRIC_DB_PASSWORD=your_electric_password \
  --name surfsense \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Copy Environment File (Windows PowerShell)

Source: https://www.surfsense.com/docs/manual-installation

Copies the example environment file to a new file named .env using PowerShell on Windows. This command is used to set up the project's environment variables.

```powershell
cd surfsense_backend
Copy-Item -Path .env.example -Destination .env
```

--------------------------------

### Configure PostgreSQL for Logical Replication

Source: https://www.surfsense.com/docs/how-to/electric-sql

These settings in the PostgreSQL configuration file (`postgresql.conf`) are required for Electric SQL to function correctly. They enable logical replication and set limits for replication slots and WAL senders.

```ini
wal_level = logical
max_replication_slots = 10
max_wal_senders = 10
```

--------------------------------

### Configure Electric SQL Service in Docker Compose

Source: https://www.surfsense.com/docs/how-to/electric-sql

This configuration snippet defines the Electric SQL service within a Docker Compose setup. It specifies the Docker image, port mappings, and environment variables for database connection and Electric SQL settings like `ELECTRIC_INSECURE` and `ELECTRIC_WRITE_TO_PG_MODE`. It also includes a health check for the service.

```yaml
electric:
  image: electricsql/electric:latest
  ports:
    - "${ELECTRIC_PORT:-5133}:3000"
  environment:
    - DATABASE_URL=${ELECTRIC_DATABASE_URL:-postgresql://${ELECTRIC_DB_USER:-electric}:${ELECTRIC_DB_PASSWORD:-electric_password}@${POSTGRES_HOST:-db}:${POSTGRES_PORT:-5432}/${POSTGRES_DB:-surfsense}?sslmode=disable}
    - ELECTRIC_INSECURE=true
    - ELECTRIC_WRITE_TO_PG_MODE=direct
  restart: unless-stopped
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:3000/v1/health"]
    interval: 10s
    timeout: 5s
    retries: 5
```

--------------------------------

### Start Celery Worker (pip/venv)

Source: https://www.surfsense.com/docs/manual-installation

Starts the Celery worker using a Python virtual environment managed by pip. This command includes steps to activate the virtual environment on Linux/macOS and Windows.

```bash
# Make sure you're in the surfsense_backend directory
cd surfsense_backend

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

# Start Celery worker
celery -A celery_worker.celery_app worker --loglevel=info --concurrency=1 --pool=solo
```

--------------------------------

### Run SurfSense with Notion Connector (Docker)

Source: https://www.surfsense.com/docs/connectors/notion

Command to run the SurfSense application with the Notion connector enabled using Docker. It includes necessary environment variables for Notion OAuth integration and port mappings.

```docker
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Notion Connector
  -e NOTION_OAUTH_CLIENT_ID=your_notion_client_id \
  -e NOTION_OAUTH_CLIENT_SECRET=your_notion_client_secret \
  -e NOTION_REDIRECT_URI=http://localhost:8000/api/v1/auth/notion/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Configure Environment Variables for Electric SQL

Source: https://www.surfsense.com/docs/how-to/electric-sql

These environment variables are crucial for configuring Electric SQL and its connection to PostgreSQL within the SurfSense project. The root `.env` file sets global variables like ports and database credentials, while the frontend `.env` specifies the URL for the client-side connection.

```dotenv
ELECTRIC_PORT=5133
POSTGRES_HOST=host.docker.internal  # Use 'db' for Docker PostgreSQL instance
ELECTRIC_DB_USER=electric
ELECTRIC_DB_PASSWORD=electric_password
NEXT_PUBLIC_ELECTRIC_URL=http://localhost:5133
```

```dotenv
NEXT_PUBLIC_ELECTRIC_URL=http://localhost:5133
NEXT_PUBLIC_ELECTRIC_AUTH_MODE=insecure
```

--------------------------------

### Update Environment Variable for PostgreSQL Host

Source: https://www.surfsense.com/docs/how-to/electric-sql

This step involves setting the `POSTGRES_HOST` environment variable in your root `.env` file. This tells the application how to connect to the PostgreSQL database, using `host.docker.internal` when running locally within Docker.

```env
POSTGRES_HOST=host.docker.internal
```

--------------------------------

### Set Up Google Drive Connector Redirect URI

Source: https://www.surfsense.com/docs/connectors/google-drive

This step details the configuration of the Authorized redirect URIs for the OAuth client ID. This URI is where Google will send the user back after they have authorized the application.

```text
Under **Authorized redirect URIs** , add:
```
http://localhost:8000/api/v1/auth/google/drive/connector/callback
```
```

--------------------------------

### Run SurfSense with Confluence Connector

Source: https://www.surfsense.com/docs/connectors/confluence

Launches the SurfSense Docker container with environment variables required for the Confluence connector. This includes the Atlassian Client ID, Client Secret, and the Confluence redirect URI.

```bash
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  -e ATLASSIAN_CLIENT_ID=your_atlassian_client_id \
  -e ATLASSIAN_CLIENT_SECRET=your_atlassian_client_secret \
  -e CONFLUENCE_REDIRECT_URI=http://localhost:8000/api/v1/auth/confluence/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Run SurfSense with Google Drive Connector

Source: https://www.surfsense.com/docs/connectors/google-drive

This Docker command demonstrates how to run the SurfSense application with the Google Drive connector enabled. It includes the necessary environment variables for Google OAuth credentials and the redirect URI.

```docker
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Google Drive Connector
  -e GOOGLE_OAUTH_CLIENT_ID=your_google_client_id \
  -e GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret \
  -e GOOGLE_DRIVE_REDIRECT_URI=http://localhost:8000/api/v1/auth/google/drive/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Run SurfSense with Discord Connector (Docker)

Source: https://www.surfsense.com/docs/connectors/discord

This Docker run command demonstrates how to start the SurfSense application with the Discord connector enabled. It includes essential environment variables for Discord authentication and volume mounting for data persistence.

```docker
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Discord Connector
  -e DISCORD_CLIENT_ID=your_discord_client_id \
  -e DISCORD_CLIENT_SECRET=your_discord_client_secret \
  -e DISCORD_REDIRECT_URI=http://localhost:8000/api/v1/auth/discord/connector/callback \
  -e DISCORD_BOT_TOKEN=http://localhost:8000/api/v1/auth/discord/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Configure OAuth Consent Screen Scopes

Source: https://www.surfsense.com/docs/connectors/google-drive

This section outlines the scopes required for the OAuth consent screen. These scopes define the level of access SurfSense will have to the user's Google Drive and email information.

```text
1. Click **Add or Remove Scopes**
2. Add the following scopes: 
   * `https://www.googleapis.com/auth/drive.readonly` - Read-only access to Google Drive
   * `https://www.googleapis.com/auth/userinfo.email` - View user email address
```

--------------------------------

### Enable Google Drive and People APIs

Source: https://www.surfsense.com/docs/connectors/google-drive

This step involves enabling the Google Drive API and the People API within the Google Cloud Console. These APIs are essential for SurfSense to interact with Google Drive and retrieve user information for authentication.

```text
1. Go to **APIs & Services** > **Library**
2. Search for and enable the following APIs: 
   * **People API** (required for Google OAuth)
   * **Google Drive API** (required for Drive connector)
```

--------------------------------

### Configure Notion OAuth Redirect URI

Source: https://www.surfsense.com/docs/connectors/notion

Sets the Redirect URI for the Notion OAuth integration. This URI is where Notion will send the authorization code after a user grants permission. Ensure this matches your application's callback endpoint.

```text
http://localhost:8000/api/v1/auth/notion/connector/callback
```

--------------------------------

### Configure Jira Connector Callback URL

Source: https://www.surfsense.com/docs/connectors/jira

This is the redirect URI that Atlassian will use to send authorization codes back to your SurfSense application after a user authorizes the integration. Ensure this matches the URI configured in your application.

```text
http://localhost:8000/api/v1/auth/jira/connector/callback
```

--------------------------------

### Run SurfSense with Linear Connector (Docker)

Source: https://www.surfsense.com/docs/connectors/linear

This command demonstrates how to run the SurfSense application with the Linear connector enabled. It includes port mappings, volume mounting for data persistence, and essential environment variables for Linear OAuth integration. Ensure you replace `your_linear_client_id` and `your_linear_client_secret` with your actual credentials.

```bash
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Linear Connector
  -e LINEAR_CLIENT_ID=your_linear_client_id \
  -e LINEAR_CLIENT_SECRET=your_linear_client_secret \
  -e LINEAR_REDIRECT_URI=http://localhost:8000/api/v1/auth/linear/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```

--------------------------------

### Expected Health Check Response

Source: https://www.surfsense.com/docs/how-to/electric-sql

This is the expected JSON response when the Electric SQL health check is successful. It confirms the service is active and operational.

```json
{"status":"active"}
```

--------------------------------

### Configure Confluence API Scopes

Source: https://www.surfsense.com/docs/connectors/confluence

Defines the permissions granted to the SurfSense application for accessing Confluence data. Both classic and granular scopes can be enabled to control the level of access.

```text
read:confluence-user
read:page:confluence
read:comment:confluence
read:space:confluence
```

--------------------------------

### Run SurfSense with Slack Connector (Docker)

Source: https://www.surfsense.com/docs/connectors/slack

This command demonstrates how to run the SurfSense Docker container with the necessary environment variables for the Slack connector. It maps ports, mounts a volume for data, and sets Slack API credentials and redirect URI.

```bash
docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Slack Connector
  -e SLACK_CLIENT_ID=your_slack_client_id \
  -e SLACK_CLIENT_SECRET=your_slack_client_secret \
  -e SLACK_REDIRECT_URI=https://localhost:8000/api/v1/auth/slack/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest
```
Tokens:
Raw