diff --git a/surfsense_web/content/docs/connectors/airtable.mdx b/surfsense_web/content/docs/connectors/airtable.mdx index 647208271..1fbe427ec 100644 --- a/surfsense_web/content/docs/connectors/airtable.mdx +++ b/surfsense_web/content/docs/connectors/airtable.mdx @@ -3,31 +3,4 @@ title: Airtable description: Connect your Airtable bases to SurfSense --- -# Airtable Connector - -Index your Airtable bases, tables, and records. - -## Prerequisites - -- An Airtable account -- API access to the bases you want to connect - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Airtable** from the list -4. Enter your Airtable API key -5. Select the bases and tables you want to index - -## What Gets Indexed - -- Table records -- Field values -- Attachments -- Linked records - -## Sync Frequency - -The Airtable connector supports scheduled syncing to keep your data up to date. - +# Documentation in progress diff --git a/surfsense_web/content/docs/connectors/bookstack.mdx b/surfsense_web/content/docs/connectors/bookstack.mdx index c05a6376b..8ee581948 100644 --- a/surfsense_web/content/docs/connectors/bookstack.mdx +++ b/surfsense_web/content/docs/connectors/bookstack.mdx @@ -3,31 +3,4 @@ title: Bookstack description: Connect your Bookstack instance to SurfSense --- -# Bookstack Connector - -Index your Bookstack books, chapters, and pages. - -## Prerequisites - -- A Bookstack instance -- API access credentials - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Bookstack** from the list -4. Enter your Bookstack instance URL and API credentials -5. Select the shelves and books you want to index - -## What Gets Indexed - -- Books and chapters -- Pages and content -- Attachments -- Tags and metadata - -## Sync Frequency - -The Bookstack connector supports scheduled syncing to keep your content up to date. - +# Documentation in progress \ No newline at end of file diff --git a/surfsense_web/content/docs/connectors/circleback.mdx b/surfsense_web/content/docs/connectors/circleback.mdx new file mode 100644 index 000000000..a5c90a28f --- /dev/null +++ b/surfsense_web/content/docs/connectors/circleback.mdx @@ -0,0 +1,8 @@ +--- +title: Circleback +description: Connect your circleback to SurfSense +--- + +# Documentation in progress + + diff --git a/surfsense_web/content/docs/connectors/clickup.mdx b/surfsense_web/content/docs/connectors/clickup.mdx index 90734555a..f59030788 100644 --- a/surfsense_web/content/docs/connectors/clickup.mdx +++ b/surfsense_web/content/docs/connectors/clickup.mdx @@ -3,31 +3,4 @@ title: ClickUp description: Connect your ClickUp workspace to SurfSense --- -# ClickUp Connector - -Sync your ClickUp tasks, docs, and content to SurfSense. - -## Prerequisites - -- A ClickUp account -- Access to the workspaces you want to connect - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **ClickUp** from the list -4. Authorize SurfSense to access your ClickUp workspace -5. Select the spaces and folders you want to index - -## What Gets Indexed - -- Tasks and subtasks -- Task descriptions and comments -- ClickUp Docs -- Custom fields - -## Sync Frequency - -The ClickUp connector supports scheduled syncing to keep your content up to date. - +# Documentation in progress \ No newline at end of file diff --git a/surfsense_web/content/docs/connectors/confluence.mdx b/surfsense_web/content/docs/connectors/confluence.mdx index 17643a86d..aa220fcbe 100644 --- a/surfsense_web/content/docs/connectors/confluence.mdx +++ b/surfsense_web/content/docs/connectors/confluence.mdx @@ -3,32 +3,104 @@ title: Confluence description: Connect your Confluence spaces to SurfSense --- -# Confluence Connector +# Confluence OAuth Integration Setup Guide -Index your Confluence pages, spaces, and documentation. +This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration for SurfSense to connect your Confluence spaces. -## Prerequisites +## Step 1: Access the Developer Console -- A Confluence account (Cloud or Data Center) -- Access to the spaces you want to connect +1. Navigate to [developer.atlassian.com](https://developer.atlassian.com) +2. Click your profile icon in the top-right corner +3. Select **"Developer console"** from the dropdown -## Setup +![Atlassian Developer Console Access](/docs/connectors/atlassian/atlassian-dev-console-access.png) -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Confluence** from the list -4. Enter your Confluence instance URL and credentials -5. Select the spaces you want to index +## Step 2: Create a New OAuth 2.0 Integration -## What Gets Indexed +1. In the Developer Console, under **My apps**, click the **"Create"** button +2. Select **"OAuth 2.0 integration"** from the dropdown -- Pages and blog posts -- Page comments -- Attachments -- Space documentation -- Page hierarchy +![Create OAuth 2.0 Integration](/docs/connectors/atlassian/atlassian-create-app.png) -## Sync Frequency +## Step 3: Name Your Integration -The Confluence connector supports scheduled syncing to keep your content up to date. +1. Enter **Name**: `SurfSense` +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. + +![Create New Integration Form](/docs/connectors/atlassian/atlassian-name-integration.png) + +## Step 4: Configure Callback URL + +1. In the left sidebar, click **"Authorization"** +2. Under **Callback URLs**, enter the redirect URI: + ``` + http://localhost:8000/api/v1/auth/confluence/connector/callback + ``` +3. Click **"Save changes"** + +> ℹ️ You can enter up to 10 redirect URIs, one per line. + +![Authorization Callback URLs](/docs/connectors/atlassian/atlassian-authorization.png) + +## Step 5: Configure API Permissions + +1. In the left sidebar, click **"Permissions"** +2. You'll see a list of available APIs including Confluence API + +![Permissions Overview](/docs/connectors/atlassian/atlassian-permissions.png) + +## Step 6: Configure Confluence API Scopes + +1. Click **"Configure"** next to **Confluence API** + +### Classic Scopes + +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 | + +![Confluence API Classic Scopes](/docs/connectors/atlassian/confluence/atlassian-confluence-classic-scopes.png) + +### Granular Scopes + +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 | + +4. Click **"Save"** + +![Confluence API Granular Scopes](/docs/connectors/atlassian/confluence/atlassian-confluence-granular-scopes.png) + +## Step 7: Get OAuth Credentials + +1. In the left sidebar, click **"Settings"** +2. Copy your **Client ID** and **Client Secret** + +> ⚠️ Never share your client secret publicly or include it in code repositories. + +--- + +## Running SurfSense with Confluence Connector + +Add the Atlassian environment variables to your Docker run command: + +```bash +docker run -d -p 3000:3000 -p 8000:8000 \ + -v surfsense-data:/data \ + # Confluence Connector + -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 +``` diff --git a/surfsense_web/content/docs/connectors/elasticsearch.mdx b/surfsense_web/content/docs/connectors/elasticsearch.mdx index 8fb003253..ac43cca4e 100644 --- a/surfsense_web/content/docs/connectors/elasticsearch.mdx +++ b/surfsense_web/content/docs/connectors/elasticsearch.mdx @@ -3,30 +3,4 @@ title: Elasticsearch description: Connect your Elasticsearch cluster to SurfSense --- -# Elasticsearch Connector - -Index data from your Elasticsearch cluster. - -## Prerequisites - -- An Elasticsearch cluster -- Access credentials - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Elasticsearch** from the list -4. Enter your Elasticsearch cluster URL and credentials -5. Configure the indices you want to index - -## What Gets Indexed - -- Documents from specified indices -- Custom field mappings -- Metadata - -## Sync Frequency - -The Elasticsearch connector supports scheduled syncing to keep your data up to date. - +# Documentation in progress \ No newline at end of file diff --git a/surfsense_web/content/docs/connectors/github.mdx b/surfsense_web/content/docs/connectors/github.mdx index 90bb91a96..bb2faca81 100644 --- a/surfsense_web/content/docs/connectors/github.mdx +++ b/surfsense_web/content/docs/connectors/github.mdx @@ -3,32 +3,4 @@ title: GitHub description: Connect your GitHub repositories to SurfSense --- -# GitHub Connector - -Index your GitHub repositories, issues, pull requests, and documentation. - -## Prerequisites - -- A GitHub account -- Access to the repositories you want to connect - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **GitHub** from the list -4. Authorize SurfSense to access your GitHub account -5. Select the repositories you want to index - -## What Gets Indexed - -- Repository README and documentation -- Issues and issue comments -- Pull requests and PR comments -- Code files (configurable) -- Discussions - -## Sync Frequency - -The GitHub connector supports scheduled syncing to keep your content up to date. - +# Documentation in progress \ No newline at end of file diff --git a/surfsense_web/content/docs/connectors/jira.mdx b/surfsense_web/content/docs/connectors/jira.mdx index 9c086d24b..9d00a56af 100644 --- a/surfsense_web/content/docs/connectors/jira.mdx +++ b/surfsense_web/content/docs/connectors/jira.mdx @@ -3,32 +3,91 @@ title: Jira description: Connect your Jira projects to SurfSense --- -# Jira Connector +# Jira OAuth Integration Setup Guide -Sync your Jira issues, projects, and documentation to SurfSense. +This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration for SurfSense to connect your Jira projects. -## Prerequisites +## Step 1: Access the Developer Console -- A Jira account (Cloud or Data Center) -- Access to the projects you want to connect +1. Navigate to [developer.atlassian.com](https://developer.atlassian.com) +2. Click your profile icon in the top-right corner +3. Select **"Developer console"** from the dropdown -## Setup +![Atlassian Developer Console Access](/docs/connectors/atlassian/atlassian-dev-console-access.png) -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Jira** from the list -4. Enter your Jira instance URL and credentials -5. Select the projects you want to index +## Step 2: Create a New OAuth 2.0 Integration -## What Gets Indexed +1. In the Developer Console, under **My apps**, click the **"Create"** button +2. Select **"OAuth 2.0 integration"** from the dropdown -- Issues and subtasks -- Issue descriptions and comments -- Attachments -- Custom fields -- Project documentation +![Create OAuth 2.0 Integration](/docs/connectors/atlassian/atlassian-create-app.png) -## Sync Frequency +## Step 3: Name Your Integration -The Jira connector supports scheduled syncing to keep your content up to date. +1. Enter **Name**: `SurfSense` +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. + +![Create New Integration Form](/docs/connectors/atlassian/atlassian-name-integration.png) + +## Step 4: Configure Callback URL + +1. In the left sidebar, click **"Authorization"** +2. Under **Callback URLs**, enter the redirect URI: + ``` + http://localhost:8000/api/v1/auth/jira/connector/callback + ``` +3. Click **"Save changes"** + +> ℹ️ You can enter up to 10 redirect URIs, one per line. + +![Authorization Callback URLs](/docs/connectors/atlassian/atlassian-authorization.png) + +## Step 5: Configure API Permissions + +1. In the left sidebar, click **"Permissions"** +2. You'll see a list of available APIs including Jira API + +![Permissions Overview](/docs/connectors/atlassian/atlassian-permissions.png) + +## Step 6: Configure Jira API Scopes + +1. Click **"Configure"** next to **Jira API** +2. Select the **"Classic scopes"** tab +3. Under **Jira platform REST API**, select the following scopes: + +| 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 | + +4. Click **"Save"** + +![Jira API Scopes](/docs/connectors/atlassian/jira/atlassian-jira-scopes.png) + +## Step 7: Get OAuth Credentials + +1. In the left sidebar, click **"Settings"** +2. Copy your **Client ID** and **Client Secret** + +> ⚠️ Never share your client secret publicly or include it in code repositories. + +--- + +## Running SurfSense with Jira Connector + +Add the Atlassian environment variables to your Docker run command: + +```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 +``` diff --git a/surfsense_web/content/docs/connectors/luma.mdx b/surfsense_web/content/docs/connectors/luma.mdx index 8a244df07..e16e5a949 100644 --- a/surfsense_web/content/docs/connectors/luma.mdx +++ b/surfsense_web/content/docs/connectors/luma.mdx @@ -3,31 +3,4 @@ title: Luma description: Connect your Luma events to SurfSense --- -# Luma Connector - -Index your Luma events and event content. - -## Prerequisites - -- A Luma account -- API access - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Luma** from the list -4. Authorize SurfSense to access your Luma account -5. Select the events you want to index - -## What Gets Indexed - -- Event details and descriptions -- Event schedules -- Attendee information (if authorized) -- Event updates - -## Sync Frequency - -The Luma connector supports scheduled syncing to keep your events up to date. - +# Documentation in progress \ No newline at end of file diff --git a/surfsense_web/content/docs/connectors/meta.json b/surfsense_web/content/docs/connectors/meta.json index 2515bc7d8..70635c6b3 100644 --- a/surfsense_web/content/docs/connectors/meta.json +++ b/surfsense_web/content/docs/connectors/meta.json @@ -1,22 +1,22 @@ { "title": "Connectors", "pages": [ - "notion", - "slack", - "discord", - "clickup", - "github", - "jira", - "linear", "google-drive", "gmail", "google-calendar", + "notion", + "slack", + "discord", + "jira", + "linear", "confluence", - "bookstack", "airtable", + "clickup", + "github", + "luma", + "circleback", "elasticsearch", - "web-crawler", - "luma" + "bookstack" ], "defaultOpen": true } diff --git a/surfsense_web/content/docs/connectors/web-crawler.mdx b/surfsense_web/content/docs/connectors/web-crawler.mdx index 2a23dea1a..6ea5b1c2b 100644 --- a/surfsense_web/content/docs/connectors/web-crawler.mdx +++ b/surfsense_web/content/docs/connectors/web-crawler.mdx @@ -3,36 +3,4 @@ title: Web Crawler description: Crawl and index websites with SurfSense --- -# Web Crawler Connector - -Crawl and index public websites to make them searchable. - -## Prerequisites - -- Firecrawl API key (see [Prerequisites](/docs)) - -## Setup - -1. Navigate to your Search Space settings -2. Click on **Add Connector** -3. Select **Web Crawler** from the list -4. Enter the URL(s) you want to crawl -5. Configure crawl depth and settings - -## What Gets Indexed - -- Web page content -- Page titles and metadata -- Links and navigation -- Images and media (configurable) - -## Configuration Options - -- **Crawl Depth**: How many levels deep to crawl -- **Include/Exclude Patterns**: Filter which URLs to index -- **Rate Limiting**: Control crawl speed - -## Sync Frequency - -The Web Crawler connector supports scheduled re-crawling to keep your content up to date. - +# Documentation in progress \ No newline at end of file diff --git a/surfsense_web/public/docs/connectors/atlassian/atlassian-authorization.png b/surfsense_web/public/docs/connectors/atlassian/atlassian-authorization.png new file mode 100644 index 000000000..71c63e200 Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/atlassian-authorization.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/atlassian-create-app.png b/surfsense_web/public/docs/connectors/atlassian/atlassian-create-app.png new file mode 100644 index 000000000..5a7fa7ded Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/atlassian-create-app.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/atlassian-dev-console-access.png b/surfsense_web/public/docs/connectors/atlassian/atlassian-dev-console-access.png new file mode 100644 index 000000000..cdfd0926d Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/atlassian-dev-console-access.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/atlassian-name-integration.png b/surfsense_web/public/docs/connectors/atlassian/atlassian-name-integration.png new file mode 100644 index 000000000..ebfcb7211 Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/atlassian-name-integration.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/atlassian-permissions.png b/surfsense_web/public/docs/connectors/atlassian/atlassian-permissions.png new file mode 100644 index 000000000..98df14e6f Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/atlassian-permissions.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/confluence/atlassian-confluence-classic-scopes.png b/surfsense_web/public/docs/connectors/atlassian/confluence/atlassian-confluence-classic-scopes.png new file mode 100644 index 000000000..99eb2d6d7 Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/confluence/atlassian-confluence-classic-scopes.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/confluence/atlassian-confluence-granular-scopes.png b/surfsense_web/public/docs/connectors/atlassian/confluence/atlassian-confluence-granular-scopes.png new file mode 100644 index 000000000..673630232 Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/confluence/atlassian-confluence-granular-scopes.png differ diff --git a/surfsense_web/public/docs/connectors/atlassian/jira/atlassian-jira-scopes.png b/surfsense_web/public/docs/connectors/atlassian/jira/atlassian-jira-scopes.png new file mode 100644 index 000000000..28bb42bd5 Binary files /dev/null and b/surfsense_web/public/docs/connectors/atlassian/jira/atlassian-jira-scopes.png differ