diff --git a/surfsense_web/app/auth/callback/loading.tsx b/surfsense_web/app/auth/callback/loading.tsx index 24d1891b4..676ca3632 100644 --- a/surfsense_web/app/auth/callback/loading.tsx +++ b/surfsense_web/app/auth/callback/loading.tsx @@ -1,3 +1,5 @@ +"use client"; + import { useTranslations } from "next-intl"; import { Spinner } from "@/components/ui/spinner"; diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/bookstack-connect-form.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/bookstack-connect-form.tsx index 2b7123d78..789e23787 100644 --- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/bookstack-connect-form.tsx +++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/bookstack-connect-form.tsx @@ -6,12 +6,6 @@ import type { FC } from "react"; import { useRef, useState } from "react"; import { useForm } from "react-hook-form"; import * as z from "zod"; -import { - Accordion, - AccordionContent, - AccordionItem, - AccordionTrigger, -} from "@/components/ui/accordion"; import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"; import { Form, @@ -85,6 +79,7 @@ export const BookStackConnectForm: FC = ({ onSubmit, isSubmitt BOOKSTACK_TOKEN_SECRET: values.token_secret, }, is_indexable: true, + is_active: true, last_indexed_at: null, periodic_indexing_enabled: periodicEnabled, indexing_frequency_minutes: periodicEnabled ? parseInt(frequencyMinutes, 10) : null, @@ -302,123 +297,6 @@ export const BookStackConnectForm: FC = ({ onSubmit, isSubmitt )} - {/* Documentation Section */} - - - - Documentation - - -
-

How it works

-

- The BookStack connector uses the BookStack REST API to fetch all pages from your - BookStack instance that your account has access to. -

-
    -
  • - For follow up indexing runs, the connector retrieves pages that have been updated - since the last indexing attempt. -
    • -
  • - Indexing is configured to run periodically, so updates should appear in your - search results within minutes. -
    • -
-
- -
-
-

Authorization

- - - API Token Required - - You need to create an API token from your BookStack instance. The token requires - "Access System API" permission. - - - -
-
-

- Step 1: Create an API Token -

-
    -
  1. Log in to your BookStack instance
    2. -
  2. Click on your profile icon → Edit Profile
    3. -
  3. Navigate to the "API Tokens" tab
    4. -
  4. Click "Create Token" and give it a name
    5. -
  5. Copy both the Token ID and Token Secret
    6. -
  6. Paste them in the form above
    7. -
-
- -
-

- Step 2: Grant necessary access -

-

- Your user account must have "Access System API" permission. The connector will - only index content your account can view. -

- - - Rate Limiting - - BookStack API has a rate limit of 180 requests per minute. The connector - automatically handles rate limiting to ensure reliable indexing. - - -
-
-
-
- -
-
-

Indexing

-
    -
  1. - Navigate to the Connector Dashboard and select the BookStack{" "} - Connector. -
    2. -
  2. - Enter your BookStack Instance URL (e.g., - https://docs.example.com) -
    3. -
  3. - Enter your Token ID and Token Secret from your - BookStack API token. -
    4. -
  4. - Click Connect to establish the connection. -
    5. -
  5. Once connected, your BookStack pages will be indexed automatically.
    6. -
- - - - What Gets Indexed - -

The BookStack connector indexes the following data:

-
    -
  • All pages from your BookStack instance
    • -
  • Page content in Markdown format
    • -
  • Page titles and metadata
    • -
  • Book and chapter hierarchy information
    • -
- - -
-
- - - ); }; diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/luma-connect-form.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/luma-connect-form.tsx index daa2e2615..2804dbba8 100644 --- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/luma-connect-form.tsx +++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/luma-connect-form.tsx @@ -6,12 +6,6 @@ import type { FC } from "react"; import { useRef, useState } from "react"; import { useForm } from "react-hook-form"; import * as z from "zod"; -import { - Accordion, - AccordionContent, - AccordionItem, - AccordionTrigger, -} from "@/components/ui/accordion"; import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"; import { Form, @@ -253,131 +247,6 @@ export const LumaConnectForm: FC = ({ onSubmit, isSubmitting } )} - - {/* Documentation Section */} - - - - Documentation - - -
-

How it works

-

- The Luma connector uses the Luma API to fetch all events that your API key has - access to. -

-
    -
  • - For follow up indexing runs, the connector retrieves events that have been updated - since the last indexing attempt. -
    • -
  • - Indexing is configured to run periodically, so updates should appear in your - search results within minutes. -
    • -
-
- -
-
-

Authorization

- - - API Key Required - - You need a Luma API key to use this connector. The key will be used to read your - Luma events with read-only permissions. - - - -
-
-

- Step 1: Get Your API Key -

-
    -
  1. Log into your Luma account
    2. -
  2. Navigate to your account settings
    3. -
  3. Go to API settings or Developer settings
    4. -
  4. Generate a new API key
    5. -
  5. Copy the generated API key
    6. -
  6. - You can also visit{" "} - - Luma API Settings - {" "} - for more information. -
    7. -
-
- -
-

- Step 2: Grant necessary access -

-

- The API key will have access to all events that your user account can see. - Make sure your account has appropriate permissions for the events you want to - index. -

- - - Data Privacy - - Only event details, descriptions, and attendee information will be indexed. - Event attachments and linked files are not indexed by this connector. - - -
-
-
-
- -
-
-

Indexing

-
    -
  1. - Navigate to the Connector Dashboard and select the Luma{" "} - Connector. -
    2. -
  2. - Place your API Key in the form field. -
    3. -
  3. - Click Connect to establish the connection. -
    4. -
  4. Once connected, your Luma events will be indexed automatically.
    5. -
- - - - What Gets Indexed - -

The Luma connector indexes the following data:

-
    -
  • Event titles and descriptions
    • -
  • Event details and metadata
    • -
  • Attendee information
    • -
  • Event dates and locations
    • -
- - -
-
- - - ); }; diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/obsidian-connect-form.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/obsidian-connect-form.tsx index 94839b03b..3c4b64090 100644 --- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/obsidian-connect-form.tsx +++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/obsidian-connect-form.tsx @@ -6,12 +6,6 @@ import type { FC } from "react"; import { useRef, useState } from "react"; import { useForm } from "react-hook-form"; import * as z from "zod"; -import { - Accordion, - AccordionContent, - AccordionItem, - AccordionTrigger, -} from "@/components/ui/accordion"; import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"; import { Form, @@ -320,145 +314,6 @@ export const ObsidianConnectForm: FC = ({ onSubmit, isSubmitti )} - - {/* Documentation Section */} - - - - Documentation - - -
-

How it works

-

- The Obsidian connector scans your local Obsidian vault directory and indexes all - Markdown files. It preserves your note structure and extracts metadata from YAML - frontmatter. -

-
    -
  • - The connector parses frontmatter metadata (title, tags, aliases, dates, etc.) -
    • -
  • Wiki-style links ([[note]]) are extracted and preserved
    • -
  • Inline tags (#tag) are recognized and indexed
    • -
  • Content is chunked intelligently for optimal search results
    • -
  • - Subsequent indexing runs use content hashing to skip unchanged files for faster - sync -
    • -
-
- -
-
-

Setup

- - - - File System Access Required - - - The SurfSense backend must have read access to your Obsidian vault directory. - For Docker deployments, mount your vault as a volume. - - - -
-
-

- Step 1: Locate your vault -

-
    -
  1. - macOS/Linux: Right-click any note in Obsidian → "Reveal in - Finder" to see the vault folder -
    2. -
  2. - Windows: Right-click any note → "Show in system explorer" -
    3. -
  3. - Or: Click the vault switcher (bottom-left icon) → "Open - folder" next to your vault name -
    4. -
-
- -
-

- Step 2: Enter the path -

-

- Running locally (no Docker): Use the direct path to your - vault: -

- 
-											{`/Users/yourname/Documents/MyObsidianVault`}
-
-

- Running in Docker: Mount your vault as a volume in - docker-compose.yml: -

- 
-											{`volumes:
-  - /path/to/your/vault:/app/obsidian_vaults/my-vault:ro`}
-
-

- Then use /app/obsidian_vaults/my-vault as your vault path. -

-
- -
-

- Step 3: Configure exclusions -

-

- Common folders to exclude: -

-
    -
  • - .obsidian - Obsidian config (always recommended) -
    • -
  • - .trash - Obsidian's trash folder -
    • -
  • - templates - If you have a templates folder -
    • -
  • - daily-notes - If you want to exclude daily notes -
    • -
-
-
-
-
- -
-
-

What Gets Indexed

- - - Indexed Content - -

The Obsidian connector indexes:

-
    -
  • All Markdown files (.md) in your vault
    • -
  • YAML frontmatter metadata (title, tags, aliases, dates)
    • -
  • Wiki-style links between notes
    • -
  • Inline tags throughout your notes
    • -
  • Full note content with proper chunking
    • -
- - -
-
- - - ); }; diff --git a/surfsense_web/content/docs/connectors/airtable.mdx b/surfsense_web/content/docs/connectors/airtable.mdx index 366a6e8e5..db7fe3ac0 100644 --- a/surfsense_web/content/docs/connectors/airtable.mdx +++ b/surfsense_web/content/docs/connectors/airtable.mdx @@ -36,20 +36,20 @@ After registration, configure the required scopes (permissions) for your integra | Scope | Description | |-------|-------------| -| ✅ `data.recordComments:read` | See comments in records | -| ✅ `data.records:read` | See the data in records | +| `data.recordComments:read` | See comments in records | +| `data.records:read` | See the data in records | ### Base schema | Scope | Description | |-------|-------------| -| ✅ `schema.bases:read` | See the structure of a base, like table names or field types | +| `schema.bases:read` | See the structure of a base, like table names or field types | ### User metadata | Scope | Description | |-------|-------------| -| ✅ `user.email:read` | See the user's email address | +| `user.email:read` | See the user's email address | ![Scopes Configuration](/docs/connectors/airtable/airtable-scopes.png) @@ -80,7 +80,9 @@ After saving, you'll find your OAuth credentials on the integration page: 1. Copy your **Client ID** 2. Copy your **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + --- diff --git a/surfsense_web/content/docs/connectors/bookstack.mdx b/surfsense_web/content/docs/connectors/bookstack.mdx index 8ee581948..f1f695e11 100644 --- a/surfsense_web/content/docs/connectors/bookstack.mdx +++ b/surfsense_web/content/docs/connectors/bookstack.mdx @@ -3,4 +3,70 @@ title: Bookstack description: Connect your Bookstack instance to SurfSense --- -# Documentation in progress \ No newline at end of file +# BookStack Integration Setup Guide + +This guide walks you through connecting your BookStack instance to SurfSense. + +## How it works + +The BookStack connector uses the BookStack REST API to fetch all pages from your BookStack instance that your account has access to. + +- For follow up indexing runs, the connector retrieves pages that have been updated since the last indexing attempt. +- Indexing should be configured to run periodically, so updates should appear in your search results within minutes. + +--- + +## Authorization + + +You need to create an API token from your BookStack instance. The token requires "Access System API" permission. + + +### Step 1: Create an API Token + +1. Log in to your BookStack instance +2. Click on your profile icon → Edit Profile +3. Navigate to the "API Tokens" tab +4. Click "Create Token" and give it a name +5. Copy both the **Token ID** and **Token Secret** +6. Paste them in the connector form + +### Step 2: Grant necessary access + +Your user account must have "Access System API" permission. The connector will only index content your account can view. + + +BookStack API has a rate limit of 180 requests per minute. The connector automatically handles rate limiting to ensure reliable indexing. + + + +Enable periodic sync to automatically re-index pages when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly. + + +--- + +## Connecting to SurfSense + +1. Navigate to the Connector Dashboard and select the **BookStack** Connector. +2. Fill in the required fields: + +| Field | Description | Example | +|-------|-------------|---------| +| **Connector Name** | A friendly name to identify this connector | `My BookStack Connector` | +| **BookStack Base URL** | The full URL of your BookStack instance | `https://docs.example.com` | +| **Token ID** | Your API Token ID from BookStack | | +| **Token Secret** | Your API Token Secret from BookStack | | + +3. Click **Connect** to establish the connection. +4. Once connected, your BookStack pages will be indexed automatically. + +### What Gets Indexed + +The BookStack connector indexes the following data: + +| Data Type | Description | +|-----------|-------------| +| Pages | All pages from your BookStack instance | +| Content | Page content in Markdown format | +| Metadata | Page titles and metadata | +| Structure | Book and chapter hierarchy information | diff --git a/surfsense_web/content/docs/connectors/circleback.mdx b/surfsense_web/content/docs/connectors/circleback.mdx index a5c90a28f..709e35f45 100644 --- a/surfsense_web/content/docs/connectors/circleback.mdx +++ b/surfsense_web/content/docs/connectors/circleback.mdx @@ -1,8 +1,133 @@ --- title: Circleback -description: Connect your circleback to SurfSense +description: Connect your Circleback meetings to SurfSense --- -# Documentation in progress +# Circleback Integration Setup Guide +This guide walks you through connecting your Circleback meetings to SurfSense for meeting search and AI-powered insights. +## How it works + +The Circleback connector uses a **webhook-based integration**. Unlike other connectors that pull data from APIs, Circleback automatically pushes meeting data to SurfSense when meetings are processed. + +- Meetings are sent to SurfSense immediately after Circleback processes them +- No API keys or credentials required +- No periodic indexing needed - data arrives in real-time +- Each meeting is stored with its notes, transcript, action items, and insights + +--- + +## What Gets Indexed + +| Content Type | Description | +|--------------|-------------| +| Meeting Notes | AI-generated meeting notes in Markdown format | +| Transcript | Full meeting transcript with speaker identification and timestamps | +| Action Items | Tasks with assignees and status | +| Attendees | Names and emails of meeting participants | +| Insights | Custom insights extracted from the meeting | +| Metadata | Date, duration, tags, meeting URL, and Circleback link | + + + Meeting recordings are not stored in SurfSense, but a link to the recording (valid for 24 hours from Circleback) is included in the indexed document. + + +--- + +## Setup Guide + +### Step 1: Create the Connector in SurfSense + +1. Navigate to **Connectors** → **Add Connector** → **Circleback** +2. Enter a connector name (e.g., `My Circleback Meetings`) +3. Click **Connect** to create the connector + + +Circleback uses webhooks, so no API key or authentication is required. The webhook URL is unique to your search space. + + +### Step 2: Copy Your Webhook URL + +After creating the connector: + +1. Open the connector settings +2. Find the **Webhook URL** field +3. Click **Copy** to copy the URL to your clipboard + +The webhook URL looks like: +``` +https://your-surfsense-url/api/v1/webhooks/circleback/{search_space_id} +``` + +### Step 3: Configure Circleback Automation + +1. Log into your [Circleback account](https://app.circleback.ai) +2. Go to **Automations** (in the main navigation) +3. Click **Create automation** +4. Add conditions to filter which meetings trigger the webhook (optional): + - Specific calendar(s) + - Meeting tags + - Meeting participants +5. Select **Send webhook request** as the action +6. Enter your SurfSense webhook URL +7. Select the meeting outcomes to include (notes, action items, transcript, insights) +8. Optionally test with your most recent meeting +9. Name and save the automation + +For detailed instructions, see [Circleback's official webhook documentation](https://circleback.ai/docs/webhook-integration). + + + Make sure your SurfSense backend is accessible from the internet for Circleback to send webhooks. If self-hosting, you may need to configure a reverse proxy or use a tunneling service. + + +--- + +## Connector Configuration + +| Field | Description | Required | +|-------|-------------|----------| +| **Connector Name** | A friendly name to identify this connector | Yes | + + + Unlike other connectors, Circleback doesn't support periodic indexing since it's webhook-based. Meetings are automatically pushed to SurfSense when processed by Circleback. + + +--- + +## Verifying the Integration + +Once configured, new meetings will automatically appear in SurfSense after Circleback processes them. To verify: + +1. Attend or process a meeting with Circleback +2. Wait for Circleback to complete processing (usually a few minutes after the meeting ends) +3. Check your SurfSense search space for the new meeting document + +Each meeting document includes: +- A direct link to view the meeting on Circleback +- Full searchable transcript +- Extracted action items with assignees +- Meeting metadata and insights + +--- + +## Troubleshooting + +**Meetings not appearing** +- Verify the webhook URL is correctly configured in Circleback +- Check that your SurfSense backend is accessible from the internet +- Look for errors in your SurfSense backend logs + +**Webhook URL not showing** +- Refresh the connector configuration page +- Ensure the connector was created successfully +- Check that your backend is running + +**Duplicate meetings** +- Each meeting is uniquely identified by its Circleback meeting ID +- If content changes, the existing document is updated rather than duplicated + +**Delayed indexing** +- Meeting data is processed asynchronously +- Documents should appear within a minute of receiving the webhook +- Check the task queue if experiencing longer delays diff --git a/surfsense_web/content/docs/connectors/clickup.mdx b/surfsense_web/content/docs/connectors/clickup.mdx index 1b732c968..960b88370 100644 --- a/surfsense_web/content/docs/connectors/clickup.mdx +++ b/surfsense_web/content/docs/connectors/clickup.mdx @@ -36,7 +36,9 @@ After creating the app, you'll see your credentials: 1. Copy your **Client ID** 2. Copy your **Client Secret** (click "Show" to reveal, or "Regenerate" if needed) -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + --- diff --git a/surfsense_web/content/docs/connectors/confluence.mdx b/surfsense_web/content/docs/connectors/confluence.mdx index fad9f3e3d..57116cf29 100644 --- a/surfsense_web/content/docs/connectors/confluence.mdx +++ b/surfsense_web/content/docs/connectors/confluence.mdx @@ -28,7 +28,9 @@ This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration 2. Check the box to agree to Atlassian's developer terms 3. Click **"Create"** -> ℹ️ New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse. + + New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse. + ![Create New Integration Form](/docs/connectors/atlassian/atlassian-name-integration.png) @@ -41,7 +43,9 @@ This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration ``` 3. Click **"Save changes"** -> ℹ️ You can enter up to 10 redirect URIs, one per line. + + You can enter up to 10 redirect URIs, one per line. + ![Authorization Callback URLs](/docs/connectors/atlassian/atlassian-authorization.png) @@ -62,7 +66,7 @@ Select the **"Classic scopes"** tab and enable: | Scope Name | Code | Description | |------------|------|-------------| -| ✅ Read user | `read:confluence-user` | View user information in Confluence that you have access to, including usernames, email addresses and profile pictures | +| Read user | `read:confluence-user` | View user information in Confluence that you have access to, including usernames, email addresses and profile pictures | ![Confluence API Classic Scopes](/docs/connectors/atlassian/confluence/atlassian-confluence-classic-scopes.png) @@ -72,9 +76,9 @@ Select the **"Granular scopes"** tab and enable: | Scope Name | Code | Description | |------------|------|-------------| -| ✅ View pages | `read:page:confluence` | View page content | -| ✅ View comments | `read:comment:confluence` | View comments on pages or blogposts | -| ✅ View spaces | `read:space:confluence` | View space details | +| View pages | `read:page:confluence` | View page content | +| View comments | `read:comment:confluence` | View comments on pages or blogposts | +| View spaces | `read:space:confluence` | View space details | 4. Click **"Save"** @@ -85,7 +89,9 @@ Select the **"Granular scopes"** tab and enable: 1. In the left sidebar, click **"Settings"** 2. Copy your **Client ID** and **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + --- diff --git a/surfsense_web/content/docs/connectors/discord.mdx b/surfsense_web/content/docs/connectors/discord.mdx index 6bb64e7e7..a90bcfe87 100644 --- a/surfsense_web/content/docs/connectors/discord.mdx +++ b/surfsense_web/content/docs/connectors/discord.mdx @@ -38,7 +38,9 @@ You'll also see your **Application ID** and **Public Key** on this page. http://localhost:8000/api/v1/auth/discord/connector/callback ``` -> ⚠️ Keep **Public Client** disabled (off) since SurfSense uses a server to make requests. + + Keep **Public Client** disabled (off) since SurfSense uses a server to make requests. + ![OAuth2 Configuration](/docs/connectors/discord/discord-oauth2.png) @@ -46,13 +48,15 @@ You'll also see your **Application ID** and **Public Key** on this page. 1. In the left sidebar, click **"Bot"** 2. Configure the **Authorization Flow**: - - ✅ **Public Bot** - Enable to allow anyone to add the bot to servers + - **Public Bot** - Enable to allow anyone to add the bot to servers 3. Enable **Privileged Gateway Intents**: - - ✅ **Server Members Intent** - Required to receive GUILD_MEMBERS events - - ✅ **Message Content Intent** - Required to receive message content + - **Server Members Intent** - Required to receive GUILD_MEMBERS events + - **Message Content Intent** - Required to receive message content -> ⚠️ Once your bot reaches 100+ servers, these intents will require verification and approval. + + Once your bot reaches 100+ servers, these intents will require verification and approval. + ![Bot Settings](/docs/connectors/discord/discord-bot-settings.png) diff --git a/surfsense_web/content/docs/connectors/elasticsearch.mdx b/surfsense_web/content/docs/connectors/elasticsearch.mdx index ac43cca4e..f2615a9c6 100644 --- a/surfsense_web/content/docs/connectors/elasticsearch.mdx +++ b/surfsense_web/content/docs/connectors/elasticsearch.mdx @@ -3,4 +3,115 @@ title: Elasticsearch description: Connect your Elasticsearch cluster to SurfSense --- -# Documentation in progress \ No newline at end of file +# Elasticsearch Integration Setup Guide + +This guide walks you through connecting your Elasticsearch cluster to SurfSense. + +## How it works + +The Elasticsearch connector allows you to search and retrieve documents from your Elasticsearch cluster. Configure connection details, select specific indices, and set search parameters to make your existing data searchable within SurfSense. + +- For follow-up indexing runs, the connector retrieves documents that have been updated since the last indexing attempt. +- Indexing should be configured to run periodically, so updates should appear in your search results within minutes. + +--- + +## Authorization + + +Elasticsearch requires authentication. You can use either an API key or username/password authentication. + + +### Step 1: Get Your Elasticsearch Endpoint + +You'll need the endpoint URL for your Elasticsearch cluster. This typically looks like: + +- **Cloud:** `https://your-cluster.es.region.aws.com:443` +- **Self-hosted:** `https://elasticsearch.example.com:9200` + +### Step 2: Configure Authentication + +Elasticsearch requires authentication. You can use either: + +**API Key:** A base64-encoded API key. You can create one in Elasticsearch by running: + +```bash +POST /_security/api_key +``` + +**Username & Password:** Basic authentication using your Elasticsearch username and password. + +### Step 3: Select Indices + +Specify which indices to search. You can: + +- Use wildcards: `logs-*` to match multiple indices +- List specific indices: `logs-2024, documents-2024` +- Leave empty to search all accessible indices (not recommended for performance) + + +Enable periodic sync to automatically re-index documents when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly. + + +--- + +## Connecting to SurfSense + +1. Navigate to the Connector Dashboard and select the **Elasticsearch** Connector. +2. Fill in the required fields: + +| Field | Description | Example | +|-------|-------------|---------| +| **Connector Name** | A friendly name to identify this connector | `My Elasticsearch Connector` | +| **Elasticsearch Endpoint URL** | The full URL of your Elasticsearch cluster | `https://your-cluster.es.region.aws.com:443` | +| **API Key** | Your base64-encoded API key (if using API key auth) | | +| **Username** | Your Elasticsearch username (if using basic auth) | | +| **Password** | Your Elasticsearch password (if using basic auth) | | +| **Indices** | Comma-separated list of indices to search | `logs-*, documents-2024` | + +3. Click **Connect** to establish the connection. +4. Once connected, your Elasticsearch documents will be indexed automatically. + +--- + +## Advanced Configuration + +### Search Query + +The default query used for searches. Use `*` to match all documents, or specify a more complex Elasticsearch query. + +### Search Fields + +Limit searches to specific fields for better performance. Common fields include: + +- `title` - Document titles +- `content` - Main content +- `description` - Descriptions + +Leave empty to search all fields in your documents. + +### Maximum Documents + +Set a limit on the number of documents retrieved per search (1-10,000). This helps control response times and resource usage. Leave empty to use Elasticsearch's default limit. + +--- + +## Troubleshooting + +### Connection Issues + +- **Invalid URL:** Ensure your endpoint URL includes the protocol (https://) and port number if required. +- **SSL/TLS Errors:** Verify that your cluster uses HTTPS and the certificate is valid. Self-signed certificates may require additional configuration. +- **Connection Timeout:** Check your network connectivity and firewall settings. Ensure the Elasticsearch cluster is accessible from SurfSense servers. + +### Authentication Issues + +- **Invalid Credentials:** Double-check your username/password or API key. API keys must be base64-encoded. +- **Permission Denied:** Ensure your API key or user account has read permissions for the indices you want to search. +- **API Key Format:** Elasticsearch API keys are typically base64-encoded strings. Make sure you're using the full key value. + +### Search Issues + +- **No Results:** Verify that your index selection matches existing indices. Use wildcards carefully. +- **Slow Searches:** Limit the number of indices or use specific index names instead of wildcards. Reduce the maximum documents limit. +- **Field Not Found:** Ensure the search fields you specify actually exist in your Elasticsearch documents. diff --git a/surfsense_web/content/docs/connectors/github.mdx b/surfsense_web/content/docs/connectors/github.mdx index 6a4574ec4..ce60d2a32 100644 --- a/surfsense_web/content/docs/connectors/github.mdx +++ b/surfsense_web/content/docs/connectors/github.mdx @@ -3,9 +3,18 @@ title: GitHub description: Connect your GitHub repositories to SurfSense --- -# GitHub Connector +# GitHub Integration Setup Guide -Connect your GitHub repositories to SurfSense for code search and AI-powered insights. The connector uses [gitingest](https://gitingest.com) to efficiently index entire codebases. +This guide walks you through connecting your GitHub repositories to SurfSense for code search and AI-powered insights. + +## How it works + +The GitHub connector uses [gitingest](https://gitingest.com) to fetch and process repository contents from GitHub. + +- For follow-up indexing runs, the connector retrieves the latest repository state and updates changed files. +- Indexing should be configured to run periodically, so updates should appear in your search results within minutes. + +--- ## What Gets Indexed @@ -15,7 +24,9 @@ Connect your GitHub repositories to SurfSense for code search and AI-powered ins | Documentation | README files, Markdown documents, text files | | Configuration | JSON, YAML, TOML, .env examples, Dockerfiles | -> ⚠️ Binary files and files larger than 5MB are automatically excluded. + + Binary files and files larger than 5MB are automatically excluded. + --- @@ -39,7 +50,13 @@ For private repos, you need a GitHub Personal Access Token (PAT). 2. Set an expiration 3. Click **Generate token** and copy it -> ⚠️ The token starts with `ghp_`. Store it securely. + + The token starts with `ghp_`. Store it securely. + + + +Enable periodic sync to automatically re-index repositories when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly. + --- @@ -53,21 +70,6 @@ For private repos, you need a GitHub Personal Access Token (PAT). --- -## Periodic Sync - -Enable periodic sync to automatically re-index repositories when content changes: - -| Frequency | Use Case | -|-----------|----------| -| Every 5 minutes | Active development | -| Every 15 minutes | Frequent commits | -| Every hour | Regular workflow | -| Every 6 hours | Less active repos | -| Daily | Reference repositories | -| Weekly | Stable codebases | - ---- - ## Troubleshooting **Repository not found** diff --git a/surfsense_web/content/docs/connectors/gmail.mdx b/surfsense_web/content/docs/connectors/gmail.mdx index 434e6ae4d..2b514f89e 100644 --- a/surfsense_web/content/docs/connectors/gmail.mdx +++ b/surfsense_web/content/docs/connectors/gmail.mdx @@ -60,7 +60,9 @@ This guide walks you through setting up a Google OAuth 2.0 integration for SurfS 1. After creating the OAuth client, you'll see a dialog with your credentials 2. Copy your **Client ID** and **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + ![Google Developer Console Config](/docs/connectors/google/google_oauth_config.png) diff --git a/surfsense_web/content/docs/connectors/google-calendar.mdx b/surfsense_web/content/docs/connectors/google-calendar.mdx index cc1eae545..7919d0361 100644 --- a/surfsense_web/content/docs/connectors/google-calendar.mdx +++ b/surfsense_web/content/docs/connectors/google-calendar.mdx @@ -59,7 +59,9 @@ This guide walks you through setting up a Google OAuth 2.0 integration for SurfS 1. After creating the OAuth client, you'll see a dialog with your credentials 2. Copy your **Client ID** and **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + ![Google Developer Console Config](/docs/connectors/google/google_oauth_config.png) diff --git a/surfsense_web/content/docs/connectors/google-drive.mdx b/surfsense_web/content/docs/connectors/google-drive.mdx index 00ea2f610..402b25566 100644 --- a/surfsense_web/content/docs/connectors/google-drive.mdx +++ b/surfsense_web/content/docs/connectors/google-drive.mdx @@ -60,7 +60,9 @@ This guide walks you through setting up a Google OAuth 2.0 integration for SurfS 1. After creating the OAuth client, you'll see a dialog with your credentials 2. Copy your **Client ID** and **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + ![Google Developer Console Config](/docs/connectors/google/google_oauth_config.png) diff --git a/surfsense_web/content/docs/connectors/jira.mdx b/surfsense_web/content/docs/connectors/jira.mdx index ebe639d6d..c6b5a26e1 100644 --- a/surfsense_web/content/docs/connectors/jira.mdx +++ b/surfsense_web/content/docs/connectors/jira.mdx @@ -28,7 +28,9 @@ This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration 2. Check the box to agree to Atlassian's developer terms 3. Click **"Create"** -> ℹ️ New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse. + + New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse. + ![Create New Integration Form](/docs/connectors/atlassian/atlassian-name-integration.png) @@ -41,7 +43,9 @@ This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration ``` 3. Click **"Save changes"** -> ℹ️ You can enter up to 10 redirect URIs, one per line. + + You can enter up to 10 redirect URIs, one per line. + ![Authorization Callback URLs](/docs/connectors/atlassian/atlassian-authorization.png) @@ -60,8 +64,8 @@ This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration | Scope Name | Code | Description | |------------|------|-------------| -| ✅ View Jira issue data | `read:jira-work` | Read Jira project and issue data, search for issues, and objects associated with issues like attachments and worklogs | -| ✅ View user profiles | `read:jira-user` | View user information in Jira that the user has access to, including usernames, email addresses, and avatars | +| View Jira issue data | `read:jira-work` | Read Jira project and issue data, search for issues, and objects associated with issues like attachments and worklogs | +| View user profiles | `read:jira-user` | View user information in Jira that the user has access to, including usernames, email addresses, and avatars | 4. Click **"Save"** @@ -72,7 +76,9 @@ This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration 1. In the left sidebar, click **"Settings"** 2. Copy your **Client ID** and **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + --- diff --git a/surfsense_web/content/docs/connectors/linear.mdx b/surfsense_web/content/docs/connectors/linear.mdx index f9dc9a62b..5fb7bc8c5 100644 --- a/surfsense_web/content/docs/connectors/linear.mdx +++ b/surfsense_web/content/docs/connectors/linear.mdx @@ -30,7 +30,7 @@ Fill in the application details: ### Settings -- ✅ **Public** - Enable this to allow the application to be installed by other workspaces +- **Public** - Enable this to allow the application to be installed by other workspaces Click **Create** to create the application. @@ -43,7 +43,9 @@ After creating the application, you'll see your OAuth credentials: 1. Copy your **Client ID** 2. Copy your **Client Secret** -> ⚠️ Never share your client secret publicly. + + Never share your client secret publicly. + ![OAuth Credentials](/docs/connectors/linear/linear-oauth-credentials.png) diff --git a/surfsense_web/content/docs/connectors/luma.mdx b/surfsense_web/content/docs/connectors/luma.mdx index e16e5a949..a218be46b 100644 --- a/surfsense_web/content/docs/connectors/luma.mdx +++ b/surfsense_web/content/docs/connectors/luma.mdx @@ -3,4 +3,68 @@ title: Luma description: Connect your Luma events to SurfSense --- -# Documentation in progress \ No newline at end of file +# Luma Integration Setup Guide + +This guide walks you through connecting your Luma events to SurfSense for event search and AI-powered insights. + +## How it works + +The Luma connector uses the Luma API to fetch all events that your API key has access to. + +- For follow-up indexing runs, the connector retrieves events that have been updated since the last indexing attempt. +- Indexing should be configured to run periodically, so updates should appear in your search results within minutes. + +--- + +## Authorization + + +You need a Luma API key to use this connector. The key will be used to read your Luma events with read-only permissions. + + +### Step 1: Get Your API Key + +1. Log into your Luma account +2. Navigate to your account settings +3. Go to API settings or Developer settings +4. Generate a new API key +5. Copy the generated API key + +You can also visit [Luma API Docs](https://docs.luma.com/reference/getting-started-with-your-api) for more information. + +### Step 2: Grant Necessary Access + +The API key will have access to all events that your user account can see. Make sure your account has appropriate permissions for the events you want to index. + + +Enable periodic sync to automatically re-index events when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly. + + +--- + +## Connecting to SurfSense + +1. Navigate to the Connector Dashboard and select the **Luma** Connector. +2. Fill in the required fields: + +| Field | Description | Example | +|-------|-------------|---------| +| **Connector Name** | A friendly name to identify this connector | `My Luma Connector` | +| **Luma API Key** | Your Luma API key (will be encrypted and stored securely) | | + +3. Click **Connect** to establish the connection. +4. Once connected, your Luma events will be indexed automatically. + +### What Gets Indexed + +The Luma connector indexes the following data: + +| Data Type | Description | +|-----------|-------------| +| Event Details | Titles, descriptions, metadata | +| Attendee Info | Attendee information and lists | +| Event Metadata | Dates, locations, settings | + + + Event attachments and linked files are not indexed by this connector. + diff --git a/surfsense_web/content/docs/connectors/meta.json b/surfsense_web/content/docs/connectors/meta.json index b41e92ab9..c6f7ab383 100644 --- a/surfsense_web/content/docs/connectors/meta.json +++ b/surfsense_web/content/docs/connectors/meta.json @@ -17,7 +17,8 @@ "luma", "circleback", "elasticsearch", - "bookstack" + "bookstack", + "obsidian" ], "defaultOpen": false } diff --git a/surfsense_web/content/docs/connectors/microsoft-teams.mdx b/surfsense_web/content/docs/connectors/microsoft-teams.mdx index daa6eb375..53f36c249 100644 --- a/surfsense_web/content/docs/connectors/microsoft-teams.mdx +++ b/surfsense_web/content/docs/connectors/microsoft-teams.mdx @@ -58,7 +58,9 @@ After registration, you'll be taken to the app's **Overview** page. Here you'll ![Certificates & Secrets - Created](/docs/connectors/microsoft-teams/azure-certificates-created.png) -> ⚠️ Never share your client secret publicly or include it in code repositories. + + Never share your client secret publicly or include it in code repositories. + ## Step 6: Configure API Permissions @@ -78,7 +80,9 @@ After registration, you'll be taken to the app's **Overview** page. Here you'll 6. Click **"Add permissions"** -> ⚠️ The `ChannelMessage.Read.All` permission requires admin consent. An admin will need to click **"Grant admin consent for [Directory]"** for full functionality. + + The `ChannelMessage.Read.All` permission requires admin consent. An admin will need to click **"Grant admin consent for [Directory]"** for full functionality. + ![API Permissions](/docs/connectors/microsoft-teams/azure-api-permissions.png) diff --git a/surfsense_web/content/docs/connectors/notion.mdx b/surfsense_web/content/docs/connectors/notion.mdx index 936972f7e..0612c4f4f 100644 --- a/surfsense_web/content/docs/connectors/notion.mdx +++ b/surfsense_web/content/docs/connectors/notion.mdx @@ -52,14 +52,13 @@ After creating the integration, you'll see the configuration page with your cred ### Set Required Capabilities -Under **Content Capabilities**, enable: -- ✅ Read content +Enable the following capabilities: -Under **Comment Capabilities**, enable: -- ✅ Read comments - -Under **User Capabilities**, select: -- 🔘 Read user information including email addresses +| Capability Type | Required Setting | +|----------------|------------------| +| **Content Capabilities** | Read content | +| **Comment Capabilities** | Read comments | +| **User Capabilities** | Read user information including email addresses | Click **Save** to apply the capabilities. diff --git a/surfsense_web/content/docs/connectors/obsidian.mdx b/surfsense_web/content/docs/connectors/obsidian.mdx new file mode 100644 index 000000000..c8475c97f --- /dev/null +++ b/surfsense_web/content/docs/connectors/obsidian.mdx @@ -0,0 +1,143 @@ +--- +title: Obsidian +description: Connect your Obsidian vault to SurfSense +--- + +# Obsidian Integration Setup Guide + +This guide walks you through connecting your Obsidian vault to SurfSense for note search and AI-powered insights. + + + This connector requires direct file system access and only works with self-hosted SurfSense installations. + + +## How it works + +The Obsidian connector scans your local Obsidian vault directory and indexes all Markdown files. It preserves your note structure and extracts metadata from YAML frontmatter. + +- For follow-up indexing runs, the connector uses content hashing to skip unchanged files for faster sync. +- Indexing should be configured to run periodically, so updates should appear in your search results within minutes. + +--- + +## What Gets Indexed + +| Content Type | Description | +|--------------|-------------| +| Markdown Files | All `.md` files in your vault | +| Frontmatter | YAML metadata (title, tags, aliases, dates) | +| Wiki Links | Links between notes (`[[note]]`) | +| Inline Tags | Tags throughout your notes (`#tag`) | +| Note Content | Full content with intelligent chunking | + + + Binary files and attachments are not indexed by default. Enable "Include Attachments" to index embedded files. + + +--- + +## Quick Start (Local Installation) + +1. Navigate to **Connectors** → **Add Connector** → **Obsidian** +2. Enter your vault path: `/Users/yourname/Documents/MyVault` +3. Enter a vault name (e.g., `Personal Notes`) +4. Click **Connect Obsidian** + + + Find your vault path: In Obsidian, right-click any note → "Reveal in Finder" (macOS) or "Show in Explorer" (Windows). + + + +Enable periodic sync to automatically re-index notes when content changes. Available frequencies: Every 5 minutes, 15 minutes, hourly, every 6 hours, daily, or weekly. + + +--- + +## Docker Setup + +For Docker deployments, you need to mount your Obsidian vault as a volume. + +### Step 1: Update docker-compose.yml + +Add your vault as a volume mount to the SurfSense backend service: + +```yaml +services: + surfsense: + # ... other config + volumes: + - /path/to/your/obsidian/vault:/app/obsidian_vaults/my-vault:ro +``` + + + The `:ro` flag mounts the vault as read-only, which is recommended for security. + + +### Step 2: Configure the Connector + +Use the **container path** (not your local path) when setting up the connector: + +| Your Local Path | Container Path (use this) | +|-----------------|---------------------------| +| `/Users/john/Documents/MyVault` | `/app/obsidian_vaults/my-vault` | +| `C:\Users\john\Documents\MyVault` | `/app/obsidian_vaults/my-vault` | + +### Example: Multiple Vaults + +```yaml +volumes: + - /Users/john/Documents/PersonalNotes:/app/obsidian_vaults/personal:ro + - /Users/john/Documents/WorkNotes:/app/obsidian_vaults/work:ro +``` + +Then create separate connectors for each vault using `/app/obsidian_vaults/personal` and `/app/obsidian_vaults/work`. + +--- + +## Connector Configuration + +| Field | Description | Required | +|-------|-------------|----------| +| **Connector Name** | A friendly name to identify this connector | Yes | +| **Vault Path** | Absolute path to your vault (container path for Docker) | Yes | +| **Vault Name** | Display name for your vault in search results | Yes | +| **Exclude Folders** | Comma-separated folder names to skip | No | +| **Include Attachments** | Index embedded files (images, PDFs) | No | + +--- + +## Recommended Exclusions + +Common folders to exclude from indexing: + +| Folder | Reason | +|--------|--------| +| `.obsidian` | Obsidian config files (always exclude) | +| `.trash` | Obsidian's trash folder | +| `templates` | Template files you don't want searchable | +| `daily-notes` | If you want to exclude daily notes | +| `attachments` | If not using "Include Attachments" | + +Default exclusions: `.obsidian,.trash` + +--- + +## Troubleshooting + +**Vault not found / Permission denied** +- Verify the path exists and is accessible +- For Docker: ensure the volume is mounted correctly in `docker-compose.yml` +- Check file permissions: SurfSense needs read access to the vault directory + +**No notes indexed** +- Ensure your vault contains `.md` files +- Check that notes aren't in excluded folders +- Verify the path points to the vault root (contains `.obsidian` folder) + +**Changes not appearing** +- Wait for the next sync cycle, or manually trigger re-indexing +- For Docker: restart the container if you modified volume mounts + +**Docker: "path not found" error** +- Use the container path (`/app/obsidian_vaults/...`), not your local path +- Verify the volume mount in `docker-compose.yml` matches diff --git a/surfsense_web/content/docs/connectors/slack.mdx b/surfsense_web/content/docs/connectors/slack.mdx index ccabe6f9e..072b83343 100644 --- a/surfsense_web/content/docs/connectors/slack.mdx +++ b/surfsense_web/content/docs/connectors/slack.mdx @@ -21,7 +21,9 @@ This guide walks you through setting up a Slack OAuth integration for SurfSense. 2. Select the workspace to develop your app in 3. Click **"Create App"** -> ⚠️ You won't be able to change the workspace later. The workspace will control the app even if you leave it. + + You won't be able to change the workspace later. The workspace will control the app even if you leave it. + ![Name App & Choose Workspace](/docs/connectors/slack/slack-name-workspace.png) @@ -32,7 +34,9 @@ After creating the app, you'll be taken to the **Basic Information** page. Here 1. Copy your **Client ID** 2. Copy your **Client Secret** (click Show to reveal) -> ⚠️ Never share your app credentials publicly. + + Never share your app credentials publicly. + ![Basic Information - App Credentials](/docs/connectors/slack/slack-app-credentials.png)