|
|
# Setup Guide
|
|
|
|
|
|
## Prerequisites
|
|
|
|
|
|
- Docker & Docker Compose v2.20+
|
|
|
- 16 GB RAM recommended (for local LLMs)
|
|
|
- GPU optional (CPU inference works but is slower)
|
|
|
- A Markdown vault (Obsidian/Logseq compatible directory)
|
|
|
|
|
|
---
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
|
### 1. Clone and configure
|
|
|
|
|
|
```bash
|
|
|
git clone <repo-url> second-brain
|
|
|
cd second-brain
|
|
|
cp .env.example .env
|
|
|
# Edit .env — at minimum, set POSTGRES_PASSWORD
|
|
|
```
|
|
|
|
|
|
### 2. Place your vault
|
|
|
|
|
|
Copy your Markdown notes into `./vault/`, or mount your existing Obsidian/Logseq vault:
|
|
|
|
|
|
```bash
|
|
|
# Option A: copy files
|
|
|
cp -r ~/obsidian-vault/* ./vault/
|
|
|
|
|
|
# Option B: symlink (Linux/macOS)
|
|
|
ln -s ~/obsidian-vault ./vault
|
|
|
```
|
|
|
|
|
|
The vault directory structure is preserved — subfolders become part of the document path.
|
|
|
|
|
|
### 3. Start services
|
|
|
|
|
|
```bash
|
|
|
docker compose up -d
|
|
|
```
|
|
|
|
|
|
This starts:
|
|
|
- PostgreSQL with pgvector (port 5432)
|
|
|
- Redis (port 6379)
|
|
|
- Ollama (port 11434)
|
|
|
- RAG API (port 8000)
|
|
|
- Ingestion Worker (background)
|
|
|
- AI Agents (background)
|
|
|
- Web UI (port 3000)
|
|
|
|
|
|
### 4. Wait for model download
|
|
|
|
|
|
Ollama pulls the embedding and chat models on first boot. This may take several minutes.
|
|
|
|
|
|
```bash
|
|
|
# Watch the bootstrap container logs
|
|
|
docker compose logs -f ollama-bootstrap
|
|
|
```
|
|
|
|
|
|
### 5. Check the UI
|
|
|
|
|
|
Open **http://localhost:3000** in your browser.
|
|
|
|
|
|
---
|
|
|
|
|
|
## Service Ports
|
|
|
|
|
|
| Service | Port | URL |
|
|
|
|-------------|-------|------------------------------|
|
|
|
| Web UI | 3000 | http://localhost:3000 |
|
|
|
| RAG API | 8000 | http://localhost:8000 |
|
|
|
| API Docs | 8000 | http://localhost:8000/docs |
|
|
|
| Ollama | 11434 | http://localhost:11434 |
|
|
|
| PostgreSQL | 5432 | localhost:5432 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
All configuration is in `.env`. Key settings:
|
|
|
|
|
|
| Variable | Default | Description |
|
|
|
|-------------------|--------------------|------------------------------------|
|
|
|
| `CHAT_MODEL` | `mistral` | Ollama model for chat |
|
|
|
| `EMBEDDING_MODEL` | `nomic-embed-text` | Ollama model for embeddings |
|
|
|
| `CHUNK_SIZE` | `700` | Target tokens per chunk |
|
|
|
| `SEARCH_THRESHOLD`| `0.65` | Minimum similarity score (0–1) |
|
|
|
| `AUTO_TAG` | `true` | Enable LLM-based auto-tagging |
|
|
|
| `AUTO_SUMMARIZE` | `true` | Enable LLM-based auto-summarization|
|
|
|
|
|
|
---
|
|
|
|
|
|
## Switching LLM Models
|
|
|
|
|
|
The system is model-agnostic. To use a different model:
|
|
|
|
|
|
```bash
|
|
|
# Pull the model
|
|
|
docker compose exec ollama ollama pull llama3
|
|
|
|
|
|
# Update .env
|
|
|
CHAT_MODEL=llama3
|
|
|
|
|
|
# Restart the affected services
|
|
|
docker compose restart rag-api agents
|
|
|
```
|
|
|
|
|
|
Popular model choices:
|
|
|
- `mistral` — fast, good quality (7B)
|
|
|
- `llama3` — excellent quality (8B/70B)
|
|
|
- `phi3` — lightweight, efficient (3.8B)
|
|
|
- `qwen2` — strong multilingual support
|
|
|
|
|
|
---
|
|
|
|
|
|
## Re-indexing the Vault
|
|
|
|
|
|
The ingestion worker automatically re-indexes changed files. To force a full re-index:
|
|
|
|
|
|
```bash
|
|
|
curl -X POST http://localhost:8000/api/v1/index/reindex \
|
|
|
-H "Content-Type: application/json" \
|
|
|
-d '{"force": true}'
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## Backup
|
|
|
|
|
|
```bash
|
|
|
# Backup database
|
|
|
docker compose exec postgres pg_dump -U brain second_brain > backup.sql
|
|
|
|
|
|
# Restore
|
|
|
docker compose exec -T postgres psql -U brain second_brain < backup.sql
|
|
|
```
|
|
|
|
|
|
The vault itself is just files — back it up with any file backup tool.
|
|
|
|
|
|
---
|
|
|
|
|
|
## Stopping / Resetting
|
|
|
|
|
|
```bash
|
|
|
# Stop all services (preserve data)
|
|
|
docker compose down
|
|
|
|
|
|
# Full reset (DELETE all data!)
|
|
|
docker compose down -v
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## Obsidian Compatibility
|
|
|
|
|
|
The vault is fully compatible with Obsidian. You can:
|
|
|
- Open `./vault/` directly in Obsidian
|
|
|
- Use all Obsidian features (graph view, backlinks, templates, etc.)
|
|
|
- The system reads `[[WikiLinks]]`, `#tags`, and YAML frontmatter
|
|
|
|
|
|
## Logseq Compatibility
|
|
|
|
|
|
Point Logseq's graph folder to `./vault/`. The system handles:
|
|
|
- `[[Page references]]`
|
|
|
- `#tags` in journal and pages
|
|
|
- YAML frontmatter (or Logseq's `::` properties are stored as-is)
|
