mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-06-26 21:39:43 +02:00
refactor: remove legacy Obsidian connector support
This commit is contained in:
Anish Sarkar
parent
16ea8e2401
commit
99623a85d5
10 changed files with 44 additions and 1046 deletions
|
|
@ -1,15 +1,11 @@
|
|||
"use client";
|
||||
|
||||
import { AlertTriangle, Download, Info } from "lucide-react";
|
||||
import { Info } from "lucide-react";
|
||||
import { type FC, useEffect, useMemo, useState } from "react";
|
||||
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import { connectorsApiService, type ObsidianStats } from "@/lib/apis/connectors-api.service";
|
||||
import type { ConnectorConfigProps } from "../index";
|
||||
|
||||
const PLUGIN_RELEASES_URL =
|
||||
"https://github.com/MODSetter/SurfSense/releases?q=obsidian&expanded=true";
|
||||
|
||||
function formatTimestamp(value: unknown): string {
|
||||
if (typeof value !== "string" || !value) return "—";
|
||||
const d = new Date(value);
|
||||
|
|
@ -26,78 +22,17 @@ function formatTimestamp(value: unknown): string {
|
|||
* web UI doesn't expose a Name input or a Save button for Obsidian (the
|
||||
* latter is suppressed in `connector-edit-view.tsx`).
|
||||
*
|
||||
* Renders one of three modes depending on the connector's `config`:
|
||||
*
|
||||
* 1. **Plugin connector** (`config.source === "plugin"`) — read-only stats
|
||||
* panel showing what the plugin most recently reported.
|
||||
* 2. **Legacy server-path connector** (`config.legacy === true`, set by the
|
||||
* Phase 3 alembic) — migration banner, an "Install Plugin" CTA, and a
|
||||
* short "how to migrate" checklist that ends with the user pressing the
|
||||
* standard Disconnect button (which deletes this connector along with
|
||||
* every document it previously indexed).
|
||||
* 3. **Unknown** — fallback for rows that escaped the alembic; suggests a
|
||||
* clean re-install.
|
||||
* Renders plugin stats when connector metadata comes from the plugin.
|
||||
* If metadata is missing or malformed, we show a recovery hint.
|
||||
*/
|
||||
export const ObsidianConfig: FC<ConnectorConfigProps> = ({ connector }) => {
|
||||
const config = (connector.config ?? {}) as Record<string, unknown>;
|
||||
const isLegacy = config.legacy === true;
|
||||
const isPlugin = config.source === "plugin";
|
||||
|
||||
if (isLegacy) return <LegacyBanner />;
|
||||
if (isPlugin) return <PluginStats config={config} />;
|
||||
return <UnknownConnectorState />;
|
||||
};
|
||||
|
||||
const LegacyBanner: FC = () => {
|
||||
return (
|
||||
<div className="space-y-4">
|
||||
<Alert className="border-amber-500/40 bg-amber-500/10">
|
||||
<AlertTriangle className="size-4 shrink-0 text-amber-500" />
|
||||
<AlertTitle className="text-xs sm:text-sm">
|
||||
Sync stopped — install the plugin to migrate
|
||||
</AlertTitle>
|
||||
<AlertDescription className="text-[11px] sm:text-xs leading-relaxed">
|
||||
This Obsidian connector used the legacy server-path scanner, which has been removed. The
|
||||
notes already indexed remain searchable, but they no longer reflect changes made in your
|
||||
vault.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
|
||||
<a
|
||||
href={PLUGIN_RELEASES_URL}
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="inline-flex"
|
||||
>
|
||||
<Button type="button" variant="outline" size="sm" className="gap-2">
|
||||
<Download className="size-3.5" />
|
||||
Install the plugin
|
||||
</Button>
|
||||
</a>
|
||||
|
||||
<div className="rounded-xl border border-border bg-slate-400/5 p-3 sm:p-6 dark:bg-white/5">
|
||||
<h3 className="mb-3 text-sm font-medium sm:text-base">How to migrate</h3>
|
||||
<ol className="list-decimal space-y-2 pl-5 text-[11px] leading-relaxed text-muted-foreground sm:text-xs">
|
||||
<li>Install the SurfSense Obsidian plugin using the button above.</li>
|
||||
<li>
|
||||
In Obsidian, open Settings → SurfSense, sign in, pick a search space, and wait for the
|
||||
first sync to finish.
|
||||
</li>
|
||||
<li>
|
||||
Confirm the new "Obsidian — <vault>" connector shows your notes, then return here
|
||||
and use the Disconnect button below to remove this legacy connector.
|
||||
</li>
|
||||
</ol>
|
||||
<p className="mt-3 text-[11px] leading-relaxed text-amber-600 dark:text-amber-400 sm:text-xs">
|
||||
Heads up: Disconnect also deletes every document this connector previously indexed. Make
|
||||
sure the plugin has finished its first sync before you disconnect, otherwise your Obsidian
|
||||
notes will disappear from search until the plugin re-indexes them.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
const PluginStats: FC<{ config: Record<string, unknown> }> = ({ config }) => {
|
||||
const vaultId = typeof config.vault_id === "string" ? config.vault_id : null;
|
||||
const [stats, setStats] = useState<ObsidianStats | null>(null);
|
||||
|
|
@ -179,8 +114,8 @@ const UnknownConnectorState: FC = () => (
|
|||
<Info className="size-4 shrink-0" />
|
||||
<AlertTitle className="text-xs sm:text-sm">Unrecognized config</AlertTitle>
|
||||
<AlertDescription className="text-[11px] sm:text-xs">
|
||||
This connector has neither plugin metadata nor a legacy marker. It may predate the migration —
|
||||
you can safely delete it and re-install the SurfSense Obsidian plugin to resume syncing.
|
||||
This connector is missing plugin metadata. Delete it, then reconnect your vault from the
|
||||
SurfSense Obsidian plugin so sync can resume.
|
||||
</AlertDescription>
|
||||
</Alert>
|
||||
);
|
||||
|
|
|
|||
|
|
@ -111,7 +111,9 @@ export const ConnectorConnectView: FC<ConnectorConnectViewProps> = ({
|
|||
: getConnectorTypeDisplay(connectorType)}
|
||||
</h2>
|
||||
<p className="text-xs sm:text-base text-muted-foreground mt-1">
|
||||
Enter your connection details
|
||||
{connectorType === "OBSIDIAN_CONNECTOR"
|
||||
? "Follow the plugin setup steps below"
|
||||
: "Enter your connection details"}
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,143 +1,60 @@
|
|||
---
|
||||
title: Obsidian
|
||||
description: Connect your Obsidian vault to SurfSense
|
||||
description: Sync your Obsidian vault with the SurfSense plugin
|
||||
---
|
||||
|
||||
# Obsidian Integration Setup Guide
|
||||
# Obsidian Plugin 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>
|
||||
SurfSense integrates with Obsidian through the SurfSense Obsidian plugin.
|
||||
The old server-side vault path scanner is no longer supported.
|
||||
|
||||
## How it works
|
||||
|
||||
The Obsidian connector scans your local Obsidian vault directory and indexes all Markdown files. It preserves your note structure and extracts metadata from YAML frontmatter.
|
||||
The plugin runs inside your Obsidian app and pushes note updates to SurfSense over HTTPS.
|
||||
This works for cloud and self-hosted deployments, including desktop and mobile clients.
|
||||
|
||||
- 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
|
||||
## 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 |
|
||||
| Markdown files | Note content (`.md`) |
|
||||
| Frontmatter | YAML metadata like title, tags, aliases, dates |
|
||||
| Wiki links | Linked notes (`[[note]]`) |
|
||||
| Tags | Inline and frontmatter tags |
|
||||
| Vault metadata | Vault and path metadata used for deep links and sync state |
|
||||
|
||||
<Callout type="warn">
|
||||
Binary files and attachments are not indexed by default. Enable "Include Attachments" to index embedded files.
|
||||
</Callout>
|
||||
## Quick start
|
||||
|
||||
---
|
||||
|
||||
## 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**
|
||||
1. Open **Connectors** in SurfSense and choose **Obsidian**.
|
||||
2. Click **Open plugin releases** and install the latest SurfSense Obsidian plugin.
|
||||
3. In Obsidian, open **Settings → SurfSense**.
|
||||
4. Paste your SurfSense API token from the connector setup panel.
|
||||
5. Paste your SurfSense backend URL in the plugin's **Server URL** setting.
|
||||
6. Choose the Search Space in the plugin, then run the first sync.
|
||||
7. Confirm the connector appears as **Obsidian — <vault>** in SurfSense.
|
||||
|
||||
<Callout type="info">
|
||||
Find your vault path: In Obsidian, right-click any note → "Reveal in Finder" (macOS) or "Show in Explorer" (Windows).
|
||||
You do not create or configure a vault path in the web UI. The connector row is created automatically when the plugin calls `/api/v1/obsidian/connect`.
|
||||
</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>
|
||||
## Self-hosted notes
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
|
||||
---
|
||||
- Use your public or LAN backend URL that your Obsidian device can reach.
|
||||
- No Docker bind mount for the vault is required.
|
||||
- If your instance is behind TLS, ensure the URL/certificate is valid for the device running Obsidian.
|
||||
|
||||
## 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
|
||||
**Plugin connects but no files appear**
|
||||
- Verify the plugin is pointed to the correct Search Space.
|
||||
- Trigger a manual sync from the plugin settings.
|
||||
- Confirm your API token is valid and not expired.
|
||||
|
||||
**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)
|
||||
**Unauthorized / 401 errors**
|
||||
- Regenerate and paste a fresh API token from SurfSense.
|
||||
- Ensure the token belongs to the same account and workspace you are syncing into.
|
||||
|
||||
**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
|
||||
**Cannot reach server URL**
|
||||
- Check that the backend URL is reachable from the Obsidian device.
|
||||
- For self-hosted setups, verify firewall and reverse proxy rules.
|
||||
- Avoid using localhost unless SurfSense and Obsidian run on the same machine.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue