feat: docs and ui tweaks

This commit is contained in:
DESKTOP-RTLN3BA\$punk 2026-07-06 19:26:35 -07:00
parent 64f2b4a6eb
commit 271a21aee6
103 changed files with 2161 additions and 2625 deletions

View file

@ -0,0 +1,125 @@
---
title: Baidu Search (Deprecated)
description: The Baidu Search connector is deprecated; public web search now runs through Google Search
---
# Baidu Search Integration Setup Guide
<Callout type="warn" title="Deprecated">
The Baidu Search connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Public web search in SurfSense now runs through the built-in **Google Search** specialist — see [Web Search](/docs/how-to/web-search). Existing Baidu connector rows remain manageable, and you can add an alternative provider through a Custom MCP connector. The guide below is retained for reference only.
</Callout>
This guide walks you through connecting Baidu AI Search to SurfSense for Chinese web search and AI-powered research.
## How it works
The Baidu Search connector uses Baidu AI Search through Qianfan AppBuilder's intelligent search generation API. It is a live search connector: SurfSense queries Baidu when the assistant needs current web results instead of periodically indexing content into your knowledge base.
- Baidu Search is best for Simplified Chinese queries and China-focused web content.
- Results are merged with SurfSense's other configured web search engines.
- The connector returns Baidu references as sources that can be cited in chat responses.
---
## Authorization
<Callout type="info" title="API Key Required">
You need a Baidu Qianfan AppBuilder API key to use this connector. The key is encrypted and stored securely by SurfSense.
</Callout>
### Step 1: Get Your Baidu AI Search API Key
1. Open the [Baidu AI Search product page](https://cloud.baidu.com/product/ai-search.html) and sign in with your Baidu Cloud account.
2. Open Qianfan AppBuilder or the AI Search console from Baidu Cloud.
3. Create or select an application that has access to Baidu AI Search.
4. Generate an API key for the application.
5. Copy the API key. SurfSense uses it as the `BAIDU_API_KEY` connector setting.
<Callout type="warn">
Keep this key private. Do not paste it into chat messages, issue reports, screenshots, or public repositories.
</Callout>
---
## Connecting to SurfSense
1. Navigate to **Connectors** → **Add Connector** → **Baidu Search**.
2. Fill in the required fields:
| Field | Description | Example |
|-------|-------------|---------|
| **Connector Name** | A friendly name to identify this connector | `Baidu Search` |
| **Baidu AppBuilder API Key** | Your Qianfan AppBuilder API key | `bce-v3/...` |
3. Click **Connect** to save the connector.
4. Ask a current Chinese web query in chat, such as `今天中国人工智能行业有什么重要新闻?`.
### Optional Advanced Settings
SurfSense stores advanced Baidu options in the connector config. If your deployment exposes these fields, use the following values:
| Setting | Description | Default |
|---------|-------------|---------|
| `BAIDU_MODEL` | The model Baidu AI Search uses for answer generation | `ernie-3.5-8k` |
| `BAIDU_SEARCH_SOURCE` | Baidu search source version | `baidu_search_v2` |
| `BAIDU_ENABLE_DEEP_SEARCH` | Enables Baidu's deeper search mode when supported by your account | `false` |
SurfSense calls Baidu's intelligent search generation endpoint:
```text
POST https://qianfan.baidubce.com/v2/ai_search/chat/completions
```
For request and response details, see Baidu's [intelligent search generation API documentation](https://cloud.baidu.com/doc/qianfan/s/Omh4su4s0).
---
## When to Use Baidu Search
| Use Case | Why Baidu Search Helps |
|----------|------------------------|
| Chinese news and current events | Better coverage for China-focused sources |
| Chinese company, product, or policy research | More local web results than global search engines alone |
| Mandarin-language fact finding | Native Chinese search and summarization behavior |
| Cross-checking web search | Adds another source alongside SearXNG, Tavily, or Linkup |
<Callout type="info" title="Live Search Connector">
Baidu Search does not create indexed documents in your knowledge base. It runs when the assistant calls web search, then returns live sources for that answer.
</Callout>
---
## Troubleshooting
**No Baidu results appear**
- Confirm the Baidu Search connector is active in the current workspace.
- Try a Chinese query with clear search intent, for example `百度智能云千帆 AppBuilder 最新功能`.
- Check whether other web search engines are returning results. If none are, review the general [Web Search](/docs/how-to/web-search) setup.
**Authentication failed**
- Verify that the API key was copied from Qianfan AppBuilder, not another Baidu Cloud product.
- Regenerate the API key if it was rotated, expired, or copied with extra whitespace.
- Make sure the related application has access to Baidu AI Search.
**Requests time out**
- Baidu AI Search can take longer than ordinary keyword search because it performs search and summarization.
- Retry with a narrower query.
- If you self-host SurfSense, verify that the backend container can reach `qianfan.baidubce.com`.
**Results are not relevant**
- Use Chinese keywords for China-focused topics.
- Include entity names, dates, or locations in the query.
- Compare with SearXNG or another configured live search connector for broader coverage.
---
## Verification Checklist
- The Baidu Search connector appears in your connector list.
- A Chinese current-events query triggers web search in chat.
- Chat responses include Baidu-backed sources with titles and URLs.
- Invalid API keys fail without breaking other configured search engines.

View file

@ -0,0 +1,84 @@
---
title: Discord
description: Connect your Discord servers to SurfSense
---
# Discord OAuth Integration Setup Guide
<Callout type="warn" title="Deprecated">
The Discord connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
</Callout>
This guide walks you through setting up a Discord OAuth integration for SurfSense.
## Step 1: Create a New Discord Application
1. Navigate to [discord.com/developers/applications](https://discord.com/developers/applications)
2. Click **"New Application"**
3. Enter the application name: `SurfSense`
4. Click **"Create"**
## Step 2: Configure General Information
On the **General Information** page, fill in the details:
| Field | Value |
|-------|-------|
| **App Icon** | Upload an icon (1024x1024px, PNG/GIF/JPG/WEBP, max 10MB) |
| **Name** | `SurfSense` |
| **Description** | Connect any LLM to your internal knowledge sources and chat with it in real time alongside your team. |
| **Tags** | Add up to 5 tags (optional) |
You'll also see your **Application ID** and **Public Key** on this page.
![General Information](/docs/connectors/discord/discord-general-info.png)
## Step 3: Configure OAuth2 Settings
1. In the left sidebar, click **"OAuth2"**
2. Copy your **Client ID** and **Client Secret** (click to reveal)
3. Under **Redirects**, click **"Add Another"** and enter:
```
http://localhost:8000/api/v1/auth/discord/connector/callback
```
<Callout type="warn">
Keep **Public Client** disabled (off) since SurfSense uses a server to make requests.
</Callout>
![OAuth2 Configuration](/docs/connectors/discord/discord-oauth2.png)
## Step 4: Configure Bot Settings
1. In the left sidebar, click **"Bot"**
2. Configure the **Authorization Flow**:
- **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
<Callout type="warn">
Once your bot reaches 100+ servers, these intents will require verification and approval.
</Callout>
![Bot Settings](/docs/connectors/discord/discord-bot-settings.png)
---
## Running SurfSense with Discord Connector
Add the Discord credentials to your `.env` file (created during [Docker installation](/docs/docker-installation)):
```bash
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_REDIRECT_URI=http://localhost:8000/api/v1/auth/discord/connector/callback
DISCORD_BOT_TOKEN=your_discord_bot_token
```
Then restart the services:
```bash
docker compose up -d
```

View file

@ -0,0 +1,121 @@
---
title: Elasticsearch
description: Connect your Elasticsearch cluster to SurfSense
---
# Elasticsearch Integration Setup Guide
<Callout type="warn" title="Deprecated">
The Elasticsearch connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
</Callout>
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
<Callout type="info" title="Authentication Required">
Elasticsearch requires authentication. You can use either an API key or username/password authentication.
</Callout>
### 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)
<Callout type="info" title="Periodic Sync">
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.
</Callout>
---
## 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.

View file

@ -0,0 +1,74 @@
---
title: Luma
description: Connect your Luma events to SurfSense
---
# Luma Integration Setup Guide
<Callout type="warn" title="Deprecated">
The Luma connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
</Callout>
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
<Callout type="info" title="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.
</Callout>
### 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.
<Callout type="info" title="Periodic Sync">
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.
</Callout>
---
## 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 |
<Callout type="warn">
Event attachments and linked files are not indexed by this connector.
</Callout>

View file

@ -0,0 +1,5 @@
{
"title": "Deprecated",
"pages": ["discord", "microsoft-teams", "luma", "baidu-search", "elasticsearch", "web-crawler"],
"defaultOpen": false
}

View file

@ -0,0 +1,124 @@
---
title: Microsoft Teams
description: Connect your Microsoft Teams to SurfSense
---
# Microsoft Teams OAuth Integration Setup Guide
This guide walks you through setting up a Microsoft Teams OAuth integration for SurfSense using Azure App Registration.
<Callout type="warn" title="Deprecated">
The Microsoft Teams connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Existing connections remain manageable. The guide below is retained for reference only.
</Callout>
<Callout type="info">
Microsoft Teams and [Microsoft OneDrive](/docs/connectors/external/onedrive) share the same Azure App Registration. If you have already created an app for OneDrive, you can reuse the same Client ID and Client Secret. Just make sure both redirect URIs are added (see Step 3).
</Callout>
## Step 1: Access Azure App Registrations
1. Navigate to [portal.azure.com](https://portal.azure.com)
2. In the search bar, type **"app reg"**
3. Select **"App registrations"** from the Services results
![Azure Portal Search](/docs/connectors/microsoft-teams/azure-search-app-reg.png)
## Step 2: Create New Registration
1. On the **App registrations** page, click **"+ New registration"**
![App Registrations Page](/docs/connectors/microsoft-teams/azure-app-registrations.png)
## Step 3: Register the Application
Fill in the application details:
| Field | Value |
|-------|-------|
| **Name** | `SurfSense` |
| **Supported account types** | Select **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts"** |
| **Redirect URI** | Platform: `Web`, URI: `http://localhost:8000/api/v1/auth/teams/connector/callback` |
Click **"Register"**
After registration, add the OneDrive redirect URI as well:
1. Go to **Authentication** in the left sidebar
2. Under **Platform configurations** > **Web** > **Redirect URIs**, click **Add URI**
3. Add: `http://localhost:8000/api/v1/auth/onedrive/connector/callback`
4. Click **Save**
![Register Application Form](/docs/connectors/microsoft-teams/azure-register-app.png)
## Step 4: Get Application (Client) ID
After registration, you will be taken to the app's **Overview** page. Here you will find:
1. Copy the **Application (client) ID** - this is your Client ID
2. Note the **Directory (tenant) ID** if needed
![Application Overview](/docs/connectors/microsoft-teams/azure-app-overview.png)
## Step 5: Create Client Secret
1. In the left sidebar under **Manage**, click **"Certificates & secrets"**
2. Select the **"Client secrets"** tab
3. Click **"+ New client secret"**
4. Enter a description (e.g., `SurfSense`) and select an expiration period
5. Click **"Add"**
![Certificates & Secrets - Empty](/docs/connectors/microsoft-teams/azure-certificates-empty.png)
6. **Important**: Copy the secret **Value** immediately. It will not be shown again!
![Certificates & Secrets - Created](/docs/connectors/microsoft-teams/azure-certificates-created.png)
<Callout type="warn">
Never share your client secret publicly or include it in code repositories.
</Callout>
## Step 6: Configure API Permissions
1. In the left sidebar under **Manage**, click **"API permissions"**
2. Click **"+ Add a permission"**
3. Select **"Microsoft Graph"**
4. Select **"Delegated permissions"**
5. Add the following permissions:
| Permission | Type | Description | Admin Consent |
|------------|------|-------------|---------------|
| `Channel.ReadBasic.All` | Delegated | Read the names and descriptions of channels | No |
| `ChannelMessage.Read.All` | Delegated | Read user channel messages | Yes |
| `offline_access` | Delegated | Maintain access to data you have given it access to | No |
| `Team.ReadBasic.All` | Delegated | Read the names and descriptions of teams | No |
| `User.Read` | Delegated | Sign in and read user profile | No |
6. Click **"Add permissions"**
<Callout type="warn">
The `ChannelMessage.Read.All` permission requires admin consent. An admin will need to click **"Grant admin consent for [Directory]"** for full functionality.
</Callout>
![API Permissions](/docs/connectors/microsoft-teams/azure-api-permissions.png)
---
## Running SurfSense with Microsoft Teams Connector
Add the Microsoft OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation)):
```bash
MICROSOFT_CLIENT_ID=your_microsoft_client_id
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret
TEAMS_REDIRECT_URI=http://localhost:8000/api/v1/auth/teams/connector/callback
```
<Callout type="info">
The `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` are shared between the Teams and OneDrive connectors. You only need to set them once.
</Callout>
Then restart the services:
```bash
docker compose up -d
```

View file

@ -0,0 +1,10 @@
---
title: Web Crawler
description: The web crawler connector is deprecated
---
# Web Crawler
<Callout type="warn" title="Deprecated">
The web crawler connector is **deprecated** and can no longer be connected (the backend refuses new connections with HTTP 410). Crawling is now built into the platform as the [Web Crawl native scraper](/docs/connectors/native/web-crawl). To save individual webpages, you can also use the [SurfSense browser extension](https://github.com/MODSetter/SurfSense/tree/main/surfsense_browser_extension), which captures pages behind authentication.
</Callout>