# 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)