mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-04-25 00:36:31 +02:00
feat: enhance documentation and fixed bug in loading.tsx
This commit is contained in:
Anish Sarkar
parent
de08f0644f
commit
9215118bab
23 changed files with 614 additions and 463 deletions
|
|
@ -1,3 +1,5 @@
|
|||
"use client";
|
||||
|
||||
import { useTranslations } from "next-intl";
|
||||
import { Spinner } from "@/components/ui/spinner";
|
||||
|
||||
|
|
|
|||
|
|
@ -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<ConnectFormProps> = ({ 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<ConnectFormProps> = ({ onSubmit, isSubmitt
|
|||
</div>
|
||||
)}
|
||||
|
||||
{/* Documentation Section */}
|
||||
<Accordion
|
||||
type="single"
|
||||
collapsible
|
||||
className="w-full border border-border rounded-xl bg-slate-400/5 dark:bg-white/5"
|
||||
>
|
||||
<AccordionItem value="documentation" className="border-0">
|
||||
<AccordionTrigger className="text-sm sm:text-base font-medium px-3 sm:px-6 no-underline hover:no-underline">
|
||||
Documentation
|
||||
</AccordionTrigger>
|
||||
<AccordionContent className="px-3 sm:px-6 pb-3 sm:pb-6 space-y-6">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">How it works</h3>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground">
|
||||
The BookStack connector uses the BookStack REST API to fetch all pages from your
|
||||
BookStack instance that your account has access to.
|
||||
</p>
|
||||
<ul className="mt-2 list-disc pl-5 text-[10px] sm:text-xs text-muted-foreground space-y-1">
|
||||
<li>
|
||||
For follow up indexing runs, the connector retrieves pages that have been updated
|
||||
since the last indexing attempt.
|
||||
</li>
|
||||
<li>
|
||||
Indexing is configured to run periodically, so updates should appear in your
|
||||
search results within minutes.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">Authorization</h3>
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20 mb-4">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">API Token Required</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
You need to create an API token from your BookStack instance. The token requires
|
||||
"Access System API" permission.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
|
||||
<div className="space-y-4 sm:space-y-6">
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 1: Create an API Token
|
||||
</h4>
|
||||
<ol className="list-decimal pl-5 space-y-2 text-[10px] sm:text-xs text-muted-foreground">
|
||||
<li>Log in to your BookStack instance</li>
|
||||
<li>Click on your profile icon → Edit Profile</li>
|
||||
<li>Navigate to the "API Tokens" tab</li>
|
||||
<li>Click "Create Token" and give it a name</li>
|
||||
<li>Copy both the Token ID and Token Secret</li>
|
||||
<li>Paste them in the form above</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 2: Grant necessary access
|
||||
</h4>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground mb-3">
|
||||
Your user account must have "Access System API" permission. The connector will
|
||||
only index content your account can view.
|
||||
</p>
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">Rate Limiting</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
BookStack API has a rate limit of 180 requests per minute. The connector
|
||||
automatically handles rate limiting to ensure reliable indexing.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">Indexing</h3>
|
||||
<ol className="list-decimal pl-5 space-y-2 text-[10px] sm:text-xs text-muted-foreground mb-4">
|
||||
<li>
|
||||
Navigate to the Connector Dashboard and select the <strong>BookStack</strong>{" "}
|
||||
Connector.
|
||||
</li>
|
||||
<li>
|
||||
Enter your <strong>BookStack Instance URL</strong> (e.g.,
|
||||
https://docs.example.com)
|
||||
</li>
|
||||
<li>
|
||||
Enter your <strong>Token ID</strong> and <strong>Token Secret</strong> from your
|
||||
BookStack API token.
|
||||
</li>
|
||||
<li>
|
||||
Click <strong>Connect</strong> to establish the connection.
|
||||
</li>
|
||||
<li>Once connected, your BookStack pages will be indexed automatically.</li>
|
||||
</ol>
|
||||
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">What Gets Indexed</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
<p className="mb-2">The BookStack connector indexes the following data:</p>
|
||||
<ul className="list-disc pl-5 space-y-1">
|
||||
<li>All pages from your BookStack instance</li>
|
||||
<li>Page content in Markdown format</li>
|
||||
<li>Page titles and metadata</li>
|
||||
<li>Book and chapter hierarchy information</li>
|
||||
</ul>
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
</div>
|
||||
</div>
|
||||
</AccordionContent>
|
||||
</AccordionItem>
|
||||
</Accordion>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
|
|
|||
|
|
@ -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<ConnectFormProps> = ({ onSubmit, isSubmitting }
|
|||
</ul>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Documentation Section */}
|
||||
<Accordion
|
||||
type="single"
|
||||
collapsible
|
||||
className="w-full border border-border rounded-xl bg-slate-400/5 dark:bg-white/5"
|
||||
>
|
||||
<AccordionItem value="documentation" className="border-0">
|
||||
<AccordionTrigger className="text-sm sm:text-base font-medium px-3 sm:px-6 no-underline hover:no-underline">
|
||||
Documentation
|
||||
</AccordionTrigger>
|
||||
<AccordionContent className="px-3 sm:px-6 pb-3 sm:pb-6 space-y-6">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">How it works</h3>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground">
|
||||
The Luma connector uses the Luma API to fetch all events that your API key has
|
||||
access to.
|
||||
</p>
|
||||
<ul className="mt-2 list-disc pl-5 text-[10px] sm:text-xs text-muted-foreground space-y-1">
|
||||
<li>
|
||||
For follow up indexing runs, the connector retrieves events that have been updated
|
||||
since the last indexing attempt.
|
||||
</li>
|
||||
<li>
|
||||
Indexing is configured to run periodically, so updates should appear in your
|
||||
search results within minutes.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">Authorization</h3>
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20 mb-4">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">API Key Required</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
You need a Luma API key to use this connector. The key will be used to read your
|
||||
Luma events with read-only permissions.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
|
||||
<div className="space-y-4 sm:space-y-6">
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 1: Get Your API Key
|
||||
</h4>
|
||||
<ol className="list-decimal pl-5 space-y-2 text-[10px] sm:text-xs text-muted-foreground">
|
||||
<li>Log into your Luma account</li>
|
||||
<li>Navigate to your account settings</li>
|
||||
<li>Go to API settings or Developer settings</li>
|
||||
<li>Generate a new API key</li>
|
||||
<li>Copy the generated API key</li>
|
||||
<li>
|
||||
You can also visit{" "}
|
||||
<a
|
||||
href="https://lu.ma/api"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="font-medium underline underline-offset-4"
|
||||
>
|
||||
Luma API Settings
|
||||
</a>{" "}
|
||||
for more information.
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 2: Grant necessary access
|
||||
</h4>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground mb-3">
|
||||
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.
|
||||
</p>
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">Data Privacy</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
Only event details, descriptions, and attendee information will be indexed.
|
||||
Event attachments and linked files are not indexed by this connector.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">Indexing</h3>
|
||||
<ol className="list-decimal pl-5 space-y-2 text-[10px] sm:text-xs text-muted-foreground mb-4">
|
||||
<li>
|
||||
Navigate to the Connector Dashboard and select the <strong>Luma</strong>{" "}
|
||||
Connector.
|
||||
</li>
|
||||
<li>
|
||||
Place your <strong>API Key</strong> in the form field.
|
||||
</li>
|
||||
<li>
|
||||
Click <strong>Connect</strong> to establish the connection.
|
||||
</li>
|
||||
<li>Once connected, your Luma events will be indexed automatically.</li>
|
||||
</ol>
|
||||
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">What Gets Indexed</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
<p className="mb-2">The Luma connector indexes the following data:</p>
|
||||
<ul className="list-disc pl-5 space-y-1">
|
||||
<li>Event titles and descriptions</li>
|
||||
<li>Event details and metadata</li>
|
||||
<li>Attendee information</li>
|
||||
<li>Event dates and locations</li>
|
||||
</ul>
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
</div>
|
||||
</div>
|
||||
</AccordionContent>
|
||||
</AccordionItem>
|
||||
</Accordion>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
|
|
|||
|
|
@ -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<ConnectFormProps> = ({ onSubmit, isSubmitti
|
|||
</ul>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Documentation Section */}
|
||||
<Accordion
|
||||
type="single"
|
||||
collapsible
|
||||
className="w-full border border-border rounded-xl bg-slate-400/5 dark:bg-white/5"
|
||||
>
|
||||
<AccordionItem value="documentation" className="border-0">
|
||||
<AccordionTrigger className="text-sm sm:text-base font-medium px-3 sm:px-6 no-underline hover:no-underline">
|
||||
Documentation
|
||||
</AccordionTrigger>
|
||||
<AccordionContent className="px-3 sm:px-6 pb-3 sm:pb-6 space-y-6">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">How it works</h3>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground">
|
||||
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.
|
||||
</p>
|
||||
<ul className="mt-2 list-disc pl-5 text-[10px] sm:text-xs text-muted-foreground space-y-1">
|
||||
<li>
|
||||
The connector parses frontmatter metadata (title, tags, aliases, dates, etc.)
|
||||
</li>
|
||||
<li>Wiki-style links ([[note]]) are extracted and preserved</li>
|
||||
<li>Inline tags (#tag) are recognized and indexed</li>
|
||||
<li>Content is chunked intelligently for optimal search results</li>
|
||||
<li>
|
||||
Subsequent indexing runs use content hashing to skip unchanged files for faster
|
||||
sync
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">Setup</h3>
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20 mb-4">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">
|
||||
File System Access Required
|
||||
</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
The SurfSense backend must have read access to your Obsidian vault directory.
|
||||
For Docker deployments, mount your vault as a volume.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
|
||||
<div className="space-y-4 sm:space-y-6">
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 1: Locate your vault
|
||||
</h4>
|
||||
<ol className="list-decimal pl-5 space-y-2 text-[10px] sm:text-xs text-muted-foreground">
|
||||
<li>
|
||||
<strong>macOS/Linux:</strong> Right-click any note in Obsidian → "Reveal in
|
||||
Finder" to see the vault folder
|
||||
</li>
|
||||
<li>
|
||||
<strong>Windows:</strong> Right-click any note → "Show in system explorer"
|
||||
</li>
|
||||
<li>
|
||||
<strong>Or:</strong> Click the vault switcher (bottom-left icon) → "Open
|
||||
folder" next to your vault name
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 2: Enter the path
|
||||
</h4>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground mb-2">
|
||||
<strong>Running locally (no Docker):</strong> Use the direct path to your
|
||||
vault:
|
||||
</p>
|
||||
<pre className="bg-slate-800 text-slate-200 p-2 rounded text-[9px] sm:text-[10px] overflow-x-auto mb-2">
|
||||
{`/Users/yourname/Documents/MyObsidianVault`}
|
||||
</pre>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground mb-2">
|
||||
<strong>Running in Docker:</strong> Mount your vault as a volume in
|
||||
docker-compose.yml:
|
||||
</p>
|
||||
<pre className="bg-slate-800 text-slate-200 p-2 rounded text-[9px] sm:text-[10px] overflow-x-auto">
|
||||
{`volumes:
|
||||
- /path/to/your/vault:/app/obsidian_vaults/my-vault:ro`}
|
||||
</pre>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground mt-2">
|
||||
Then use <code>/app/obsidian_vaults/my-vault</code> as your vault path.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<h4 className="text-[10px] sm:text-xs font-medium mb-2">
|
||||
Step 3: Configure exclusions
|
||||
</h4>
|
||||
<p className="text-[10px] sm:text-xs text-muted-foreground">
|
||||
Common folders to exclude:
|
||||
</p>
|
||||
<ul className="list-disc pl-5 mt-1 space-y-1 text-[10px] sm:text-xs text-muted-foreground">
|
||||
<li>
|
||||
<code>.obsidian</code> - Obsidian config (always recommended)
|
||||
</li>
|
||||
<li>
|
||||
<code>.trash</code> - Obsidian's trash folder
|
||||
</li>
|
||||
<li>
|
||||
<code>templates</code> - If you have a templates folder
|
||||
</li>
|
||||
<li>
|
||||
<code>daily-notes</code> - If you want to exclude daily notes
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4">
|
||||
<div>
|
||||
<h3 className="text-sm sm:text-base font-semibold mb-2">What Gets Indexed</h3>
|
||||
<Alert className="bg-slate-400/5 dark:bg-white/5 border-slate-400/20">
|
||||
<Info className="h-3 w-3 sm:h-4 sm:w-4" />
|
||||
<AlertTitle className="text-[10px] sm:text-xs">Indexed Content</AlertTitle>
|
||||
<AlertDescription className="text-[9px] sm:text-[10px]">
|
||||
<p className="mb-2">The Obsidian connector indexes:</p>
|
||||
<ul className="list-disc pl-5 space-y-1">
|
||||
<li>All Markdown files (.md) in your vault</li>
|
||||
<li>YAML frontmatter metadata (title, tags, aliases, dates)</li>
|
||||
<li>Wiki-style links between notes</li>
|
||||
<li>Inline tags throughout your notes</li>
|
||||
<li>Full note content with proper chunking</li>
|
||||
</ul>
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
</div>
|
||||
</div>
|
||||
</AccordionContent>
|
||||
</AccordionItem>
|
||||
</Accordion>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -3,4 +3,70 @@ title: Bookstack
|
|||
description: Connect your Bookstack instance to SurfSense
|
||||
---
|
||||
|
||||
# Documentation in progress
|
||||
# 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
|
||||
|
||||
<Callout type="info" title="API Token Required">
|
||||
You need to create an API token from your BookStack instance. The token requires "Access System API" permission.
|
||||
</Callout>
|
||||
|
||||
### 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.
|
||||
|
||||
<Callout type="info" title="Rate Limiting">
|
||||
BookStack API has a rate limit of 180 requests per minute. The connector automatically handles rate limiting to ensure reliable indexing.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="Periodic Sync">
|
||||
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.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
<Callout type="info">
|
||||
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.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
<Callout type="info" title="No Credentials Needed">
|
||||
Circleback uses webhooks, so no API key or authentication is required. The webhook URL is unique to your search space.
|
||||
</Callout>
|
||||
|
||||
### 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).
|
||||
|
||||
<Callout type="warn">
|
||||
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.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## Connector Configuration
|
||||
|
||||
| Field | Description | Required |
|
||||
|-------|-------------|----------|
|
||||
| **Connector Name** | A friendly name to identify this connector | Yes |
|
||||
|
||||
<Callout type="info">
|
||||
Unlike other connectors, Circleback doesn't support periodic indexing since it's webhook-based. Meetings are automatically pushed to SurfSense when processed by Circleback.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="info">
|
||||
New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="info">
|
||||
You can enter up to 10 redirect URIs, one per line.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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 |
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Keep **Public Client** disabled (off) since SurfSense uses a server to make requests.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Once your bot reaches 100+ servers, these intents will require verification and approval.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -3,4 +3,115 @@ title: Elasticsearch
|
|||
description: Connect your Elasticsearch cluster to SurfSense
|
||||
---
|
||||
|
||||
# Documentation in progress
|
||||
# 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
|
||||
|
||||
<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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Binary files and files larger than 5MB are automatically excluded.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
The token starts with `ghp_`. Store it securely.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="Periodic Sync">
|
||||
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.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -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**
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="info">
|
||||
New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="info">
|
||||
You can enter up to 10 redirect URIs, one per line.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -3,4 +3,68 @@ title: Luma
|
|||
description: Connect your Luma events to SurfSense
|
||||
---
|
||||
|
||||
# Documentation in progress
|
||||
# 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
|
||||
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -17,7 +17,8 @@
|
|||
"luma",
|
||||
"circleback",
|
||||
"elasticsearch",
|
||||
"bookstack"
|
||||
"bookstack",
|
||||
"obsidian"
|
||||
],
|
||||
"defaultOpen": false
|
||||
}
|
||||
|
|
|
|||
|
|
@ -58,7 +58,9 @@ After registration, you'll be taken to the app's **Overview** page. Here you'll
|
|||
|
||||
|
||||
|
||||
> ⚠️ Never share your client secret publicly or include it in code repositories.
|
||||
<Callout type="warn">
|
||||
Never share your client secret publicly or include it in code repositories.
|
||||
</Callout>
|
||||
|
||||
## 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.
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
143
surfsense_web/content/docs/connectors/obsidian.mdx
Normal file
143
surfsense_web/content/docs/connectors/obsidian.mdx
Normal file
|
|
@ -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.
|
||||
|
||||
<Callout type="warn">
|
||||
This connector requires direct file system access and only works with self-hosted SurfSense installations.
|
||||
</Callout>
|
||||
|
||||
## 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 |
|
||||
|
||||
<Callout type="warn">
|
||||
Binary files and attachments are not indexed by default. Enable "Include Attachments" to index embedded files.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## 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**
|
||||
|
||||
<Callout type="info">
|
||||
Find your vault path: In Obsidian, right-click any note → "Reveal in Finder" (macOS) or "Show in Explorer" (Windows).
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="Periodic Sync">
|
||||
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.
|
||||
</Callout>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
The `:ro` flag mounts the vault as read-only, which is recommended for security.
|
||||
</Callout>
|
||||
|
||||
### 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
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
You won't be able to change the workspace later. The workspace will control the app even if you leave it.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
<Callout type="warn">
|
||||
Never share your app credentials publicly.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue