admin-valentin/open-notebook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update quick start guides and core concepts for clarity and accuracy

Browse source
This commit is contained in:
LUIS NOVO 2026-01-04 09:09:20 -03:00
parent e13e4a2d8b
commit 655d164fa0
13 changed files with 220 additions and 169 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
docs/0-START-HERE/index.md
View file

@ -5,20 +5,20 @@
## Choose Your Path
### 🚀 I want to use OpenAI (Fastest)
**5 minutes to running.** GPT-4, simple setup, powerful results.
**5 minutes to running.** GPT, simple setup, powerful results.
→ [OpenAI Quick Start](quick-start-openai.md)
---
### ☁️ I want to use other cloud AI (Anthropic, Google, Groq, etc.)
### ☁️ I want to use other cloud AI (Anthropic, Google, OpenRouter, etc.)
**5 minutes to running.** Choose from 15+ AI providers.
→ [Cloud Providers Quick Start](quick-start-cloud.md)
---
### 🏠 I want to run locally (Ollama, completely private)
### 🏠 I want to run locally (Ollama or LMStudio, completely private)
**5 minutes to running.** Keep everything private, on your machine. No costs.
→ [Local Quick Start](quick-start-local.md)
@ -41,21 +41,13 @@
| **Privacy** | Self-hosted, your control | Cloud, Google's servers |
| **AI Choice** | 15+ providers | Google's models only |
| **Podcast Speakers** | 1-4 customizable | 2 only |
| **Cost** | Pay what you use | Free (but your data) |
| **Offline** | Yes (with Ollama) | No |
| **Cost** | Completely free | Free (but your data) |
| **Offline** | Yes | No |
## Prerequisites
- **Docker**: All paths use Docker (free)
- **AI Provider**: Either a cloud API key OR use free local models (Ollama)
- **Browser**: Modern browser (Chrome, Firefox, Safari, Edge)
## System Requirements
- **RAM**: 4GB minimum (8GB recommended)
- **Storage**: 2GB for app + space for documents
- **CPU**: Any modern processor
- **Network**: Internet for cloud AI (optional for local)
---

31
docs/0-START-HERE/quick-start-cloud.md
View file

@ -9,6 +9,7 @@ Get Open Notebook running with **Anthropic, Google, Groq, or other cloud provide
- Already have it? Skip to step 2
2. **API Key** from your chosen provider:
- **OpenRouter** (100+ models, one key): https://openrouter.ai/keys
- **Anthropic (Claude)**: https://console.anthropic.com/
- **Google (Gemini)**: https://aistudio.google.com/
- **Groq** (fast, free tier): https://console.groq.com/
@ -29,15 +30,19 @@ services:
ports:
- "8000:8000"
api:
open_notebook:
image: lfnovo/open_notebook:v1-latest
ports:
- "5055:5055"
- "8502:8502" # Web UI
- "5055:5055" # API
environment:
# Choose ONE provider (uncomment your choice):
# OpenRouter - 100+ models with one API key
- OPENROUTER_API_KEY=sk-or-...
# Anthropic (Claude) - Excellent reasoning
- ANTHROPIC_API_KEY=sk-ant-...
# - ANTHROPIC_API_KEY=sk-ant-...
# Google (Gemini) - Large context, cost-effective
# - GOOGLE_API_KEY=...
@ -54,21 +59,12 @@ services:
- SURREAL_PASSWORD=password
- SURREAL_NAMESPACE=open_notebook
- SURREAL_DATABASE=production
volumes:
- ./notebook_data:/app/data
depends_on:
- surrealdb
volumes:
- ./data:/app/data
restart: always
frontend:
image: lfnovo/open_notebook-frontend:v1-latest
ports:
- "3000:3000"
environment:
- NEXT_PUBLIC_API_URL=http://localhost:5055
depends_on:
- api
restart: always
```
**Edit the file:**
@ -93,7 +89,7 @@ Wait 15-20 seconds for services to start.
Open your browser:
```
http://localhost:3000
http://localhost:8502
```
You should see the Open Notebook interface!
@ -108,6 +104,7 @@ You should see the Open Notebook interface!
| Provider | Recommended Model | Notes |
|----------|-------------------|-------|
| **OpenRouter** | `anthropic/claude-3.5-sonnet` | Access 100+ models |
| **Anthropic** | `claude-3-5-sonnet-latest` | Best reasoning |
| **Google** | `gemini-2.0-flash` | Large context, fast |
| **Groq** | `llama-3.3-70b-versatile` | Ultra-fast |
@ -138,7 +135,7 @@ You should see the Open Notebook interface!
## Verification Checklist
- [ ] Docker is running
- [ ] You can access `http://localhost:3000`
- [ ] You can access `http://localhost:8502`
- [ ] Models are configured for your provider
- [ ] You created a notebook
- [ ] Chat works
@ -151,6 +148,7 @@ You should see the Open Notebook interface!
| Provider | Speed | Quality | Context | Cost |
|----------|-------|---------|---------|------|
| **OpenRouter** | Varies | Varies | Varies | Varies (100+ models) |
| **Anthropic** | Medium | Excellent | 200K | $$$ |
| **Google** | Fast | Very Good | 1M+ | $$ |
| **Groq** | Ultra-fast | Good | 128K | $ (free tier) |
@ -165,6 +163,7 @@ You can enable multiple providers simultaneously:
```yaml
environment:
- OPENROUTER_API_KEY=sk-or-...
- ANTHROPIC_API_KEY=sk-ant-...
- GOOGLE_API_KEY=...
- GROQ_API_KEY=gsk_...

29
docs/0-START-HERE/quick-start-local.md
View file

@ -8,9 +8,9 @@ Get Open Notebook running with **100% local AI** using Ollama. No cloud API keys
- [Download here](https://www.docker.com/products/docker-desktop/)
- Already have it? Skip to step 2
2. **Ollama** installed (for local LLM)
- [Download here](https://ollama.ai/)
- Or use Docker image (easier): `ollama/ollama`
2. **Local LLM** - Choose one:
- **Ollama** (recommended): [Download here](https://ollama.ai/)
- **LM Studio** (GUI alternative): [Download here](https://lmstudio.ai)
## Step 1: Choose Your Setup (1 min)
@ -237,10 +237,31 @@ docker exec open_notebook-ollama-1 ollama pull neural-chat
---
## Alternative: Using LM Studio Instead of Ollama
**Prefer a GUI?** LM Studio is easier for non-technical users:
1. Download LM Studio: https://lmstudio.ai
2. Open the app, download a model from the library
3. Go to "Local Server" tab, start server (port 1234)
4. Update your docker-compose.yml:
```yaml
environment:
- OPENAI_COMPATIBLE_BASE_URL=http://host.docker.internal:1234/v1
- OPENAI_COMPATIBLE_API_KEY=not-needed
```
5. Configure in Settings → Models → Select your LM Studio model
**Note**: LM Studio runs outside Docker, use `host.docker.internal` to connect.
---
## Going Further
- **Switch models**: Change in Settings → Models anytime
- **Add more models**: Run `ollama pull <model>` and they'll appear in Settings
- **Add more models**:
- Ollama: Run `ollama pull <model>`
- LM Studio: Download from the app library
- **Deploy to server**: Same docker-compose.yml works anywhere
- **Use cloud hybrid**: Keep some local models, add OpenAI/Anthropic for complex tasks

29
docs/0-START-HERE/quick-start-openai.md
View file

@ -27,10 +27,11 @@ services:
ports:
- "8000:8000"
api:
open_notebook:
image: lfnovo/open_notebook:v1-latest
ports:
- "5055:5055"
- "8502:8502" # Web UI
- "5055:5055" # API
environment:
# Your OpenAI key
- OPENAI_API_KEY=sk-...
@ -41,20 +42,10 @@ services:
- SURREAL_PASSWORD=password
- SURREAL_NAMESPACE=open_notebook
- SURREAL_DATABASE=production
volumes:
- ./notebook_data:/app/data
depends_on:
- surrealdb
volumes:
- ./data:/app/data
restart: always
frontend:
image: lfnovo/open_notebook-frontend:v1-latest
ports:
- "3000:3000"
environment:
- NEXT_PUBLIC_API_URL=http://localhost:5055
depends_on:
- api
restart: always
```
@ -79,7 +70,7 @@ Wait 15-20 seconds for services to start.
Open your browser:
```
http://localhost:3000
http://localhost:8502
```
You should see the Open Notebook interface!
@ -116,7 +107,7 @@ You should see the Open Notebook interface!
## Verification Checklist
- [ ] Docker is running
- [ ] You can access `http://localhost:3000`
- [ ] You can access `http://localhost:8502`
- [ ] You created a notebook
- [ ] You added a source
- [ ] Chat works
@ -135,15 +126,15 @@ In your notebook, go to **Settings** → **Models** to choose:
## Troubleshooting
### "Port 3000 already in use"
### "Port 8502 already in use"
Change the port in docker-compose.yml:
```yaml
ports:
- "3001:3000" # Use 3001 instead
- "8503:8502" # Use 8503 instead
```
Then access at `http://localhost:3001`
Then access at `http://localhost:8503`
### "API key not working"

34
docs/1-INSTALLATION/docker-compose.md
View file

@ -42,10 +42,11 @@ services:
volumes:
- surreal_data:/mydata
api:
open_notebook:
image: lfnovo/open_notebook:v1-latest
ports:
- "5055:5055"
- "8502:8502" # Web UI
- "5055:5055" # API
environment:
# AI Provider (choose ONE)
- OPENAI_API_KEY=sk-... # Your OpenAI key
@ -58,23 +59,10 @@ services:
- SURREAL_PASSWORD=password
- SURREAL_NAMESPACE=open_notebook
- SURREAL_DATABASE=production
# API Configuration
- API_URL=http://localhost:5055
volumes:
- ./notebook_data:/app/data
depends_on:
- surrealdb
volumes:
- ./data:/app/data
restart: always
frontend:
image: lfnovo/open_notebook-frontend:v1-latest
ports:
- "3000:3000"
environment:
- NEXT_PUBLIC_API_URL=http://localhost:5055
depends_on:
- api
restart: always
volumes:
@ -99,8 +87,7 @@ docker compose up -d
Wait 15-20 seconds for all services to start:
```
✅ surrealdb running on :8000
✅ api running on :5055
✅ frontend running on :3000
✅ open_notebook running on :8502 (UI) and :5055 (API)
```
Check status:
@ -121,7 +108,7 @@ curl http://localhost:5055/health
**Frontend Access:**
Open browser to:
```
http://localhost:3000
http://localhost:8502
```
You should see the Open Notebook interface!
@ -265,14 +252,15 @@ docker compose logs api
### Port Already in Use
If you get "Port 3000 already in use", change the port:
If you get "Port 8502 already in use", change the port:
```yaml
ports:
- "3001:3000" # Use 3001 instead
- "8503:8502" # Use 8503 instead
- "5055:5055" # Keep API port same
```
Then access at `http://localhost:3001`
Then access at `http://localhost:8503`
---

2
docs/1-INSTALLATION/index.md
View file

@ -110,7 +110,7 @@ Before installing, you'll need:
1. Have Python 3.11+, Node.js 18+, Git installed
2. Follow [From Source](from-source.md)
3. Run `make start-all`
4. Access at `http://localhost:3000` (frontend) or `http://localhost:5055` (API)
4. Access at `http://localhost:8502` (frontend) or `http://localhost:5055` (API)
---

123
docs/2-CORE-CONCEPTS/ai-context-rag.md
View file

@ -1,6 +1,6 @@
# AI Context & RAG - How Open Notebook Uses Your Research
The core innovation in Open Notebook is how it makes AI models aware of your private research without uploading everything to the cloud. This section explains the "why" and "how" of that system.
Open Notebook uses different approaches to make AI models aware of your research depending on the feature. This section explains **RAG** (used in Ask) and **full-content context** (used in Chat).
---
@ -23,10 +23,17 @@ The core innovation in Open Notebook is how it makes AI models aware of your pri
- Pro: Private, free
- Con: AI doesn't know anything about your specific topic
### Open Notebook's Solution: RAG
**RAG** = Retrieval-Augmented Generation
### Open Notebook's Dual Approach
The insight: *Instead of changing the model, change what information you feed it.*
**For Chat**: Sends the entire selected content to the LLM
- Simple and transparent: You select sources, they're sent in full
- Maximum context: AI sees everything you choose
- You control which sources are included
**For Ask (RAG)**: Retrieval-Augmented Generation
- RAG = Retrieval-Augmented Generation
- The insight: *Search your content, find relevant pieces, send only those*
- Automatic: AI decides what's relevant based on your question
---
@ -260,45 +267,83 @@ Result: AI doesn't get distracted; gives better answer
## The Difference: Chat vs. Ask
Both use RAG, but differently.
**IMPORTANT**: These use completely different approaches!
### Chat: Manual Context Control
### Chat: Full-Content Context (NO RAG)
**How it works:**
```
YOU:
1. Choose which sources to include
1. Select which sources to include in context
2. Set context level (full/summary/excluded)
3. Ask question
SYSTEM:
- Uses ONLY the sources you selected
- Respects your context levels
- Answers based on what you chose
- Takes ALL selected sources (respecting context levels)
- Sends the ENTIRE content to the LLM at once
- NO search, NO retrieval, NO chunking
- AI sees everything you selected
YOU:
4. Ask follow-up (context stays the same)
5. Or change context for next question
AI:
- Responds based on the full content you provided
- Can reference any part of selected sources
- Conversational: context stays for follow-ups
```
**Use this when**: You know which sources matter for THIS conversation.
**Use this when**:
- You know which sources are relevant
- You want conversational back-and-forth
- You want AI to see the complete context
- You're doing close reading or analysis
### Ask: Automatic Search
**Advantages:**
- Simple and transparent
- AI sees everything (no missed content)
- Conversational flow
**Limitations:**
- Limited by LLM context window
- You must manually select relevant sources
- Sends more tokens (higher cost with many sources)
---
### Ask: RAG - Automatic Retrieval
**How it works:**
```
YOU:
Ask one complex question
SYSTEM:
1. Analyzes your question (using smart model)
2. Breaks it into searchable parts
3. Automatically searches your sources
4. Retrieves relevant chunks
5. Processes results
1. Analyzes your question
2. Searches across ALL your sources automatically
3. Finds relevant chunks using vector similarity
4. Retrieves only the most relevant pieces
5. Sends ONLY those chunks to the LLM
6. Synthesizes into comprehensive answer
YOU:
Get one detailed answer (not conversational)
AI:
- Sees ONLY the retrieved chunks (not full sources)
- Answers based on what was found to be relevant
- One-shot answer (not conversational)
```
**Use this when**: You want a comprehensive answer and trust the AI to find what's relevant.
**Use this when**:
- You have many sources and don't know which are relevant
- You want the AI to search automatically
- You need a comprehensive answer to a complex question
- You want to minimize tokens sent to LLM
**Advantages:**
- Automatic search (you don't pick sources)
- Works across many sources at once
- Cost-effective (sends only relevant chunks)
**Limitations:**
- Not conversational (single question/answer)
- AI only sees retrieved chunks (might miss context)
- Search quality depends on how well question matches content
---
@ -380,16 +425,26 @@ This is why semantic search finds conceptually similar content even when words a
## Summary
**RAG** allows Open Notebook to:
Open Notebook gives you **two ways** to work with AI:
### Chat (Full-Content)
- Sends entire selected sources to LLM
- Manual control: you pick sources
- Conversational: back-and-forth dialog
- Transparent: you know exactly what AI sees
- Best for: focused analysis, close reading
### Ask (RAG)
- Searches and retrieves relevant chunks automatically
- Automatic: AI finds what's relevant
- One-shot: single comprehensive answer
- Efficient: sends only relevant pieces
- Best for: broad questions across many sources
**Both approaches:**
1. Keep your data private (doesn't leave your system by default)
2. Make AI aware of your research (retrieval brings in relevant chunks)
3. Give you control (you decide what's in context)
4. Create audit trails (citations show what was used)
5. Support multiple searches (keyword and semantic)
2. Give you control (you choose which features to use)
3. Create audit trails (citations show what was used)
4. Support multiple AI providers
This is fundamentally different from:
- Systems that fine-tune (slow, permanent)
- Systems that send everything (privacy nightmare)
- Systems that ignore your data (no customization)
It's **retrieval-augmented generation**: the system retrieves what's relevant, then augments the AI's knowledge with it.
**Coming Soon**: The community is working on adding RAG capabilities to Chat as well, giving you the best of both worlds.

73
docs/2-CORE-CONCEPTS/chat-vs-transformations.md
View file

@ -93,30 +93,32 @@ You: [Get back one comprehensive answer]
---
### 3. TRANSFORMATIONS - Batch Processing with Templates
### 3. TRANSFORMATIONS - Template-Based Processing
**What it is:** Apply a reusable template to one or more sources and get structured outputs.
**What it is:** Apply a reusable template to a source and get structured output.
**The flow:**
```
1. You define a transformation (or choose a preset)
"Extract: main argument, methodology, limitations"
2. You apply it to one or more sources
OR system applies it to all sources
2. You apply it to ONE source at a time
(You can repeat for other sources)
3. For each source:
3. For the source:
- Source content + transformation prompt → AI
- Result stored as new insight/note
4. You get back
- Structured outputs (main argument, methodology, limitations)
- Saved as notes in your notebook
- Structured output (main argument, methodology, limitations)
- Saved as a note in your notebook
```
**Context management:** You choose which sources to transform.
**Context management:** Works on one source at a time.
**Batch processing:** Process multiple sources at once.
**Reusable:** Apply the same template to different sources (one by one).
**Note**: Currently processes one source at a time. Batch processing (multiple sources at once) is planned for a future release.
**Example:**
```
@ -128,23 +130,24 @@ You: Define transformation
- Limitations and gaps
- Recommended next research"
You: Apply to 10 papers
You: Apply to paper 1
System:
- For each paper, runs the transformation
- Results stored as 10 new notes
- Each note has the structure you defined
- Runs the transformation on paper 1
- Result stored as new note
You: Now you have structured notes from all 10 papers
Perfect for writing a literature review or comparison
You: Apply same transformation to paper 2, 3, etc.
After 10 papers:
- You have 10 structured notes with consistent format
- Perfect for writing a literature review or comparison
```
**Best for:**
- Extracting the same information from multiple sources
- Creating structured summaries
- Extracting the same information from each source (run repeatedly)
- Creating structured summaries with consistent format
- Building a knowledge base of categorized insights
- When you want consistent, reusable templates
- Batch processing multiple sources
- When you want reusable templates you can apply to each source
---
@ -165,8 +168,8 @@ What are you trying to do?
├─→ "I need to compare these sources or get a comprehensive answer"
│ └─→ USE: ASK
│
├─→ "I want to extract the same info from many sources"
│ └─→ USE: TRANSFORMATIONS
├─→ "I want to extract the same info from each source (one at a time)"
│ └─→ USE: TRANSFORMATIONS (apply to each source)
│
└─→ "I just want to read and search"
└─→ USE: Search (text or vector)
@ -179,13 +182,13 @@ What are you trying to do?
| Aspect | CHAT | ASK | TRANSFORMATIONS |
|--------|------|-----|-----------------|
| **What's it for?** | Conversational exploration | Comprehensive Q&A | Batch extraction |
| **# of questions** | Multiple (conversational) | One | One template, many sources |
| **Context control** | Manual (you choose) | Automatic (system searches) | Manual (you choose) |
| **Conversational?** | Yes (follow-ups work) | No (one question only) | No (batch process) |
| **Output** | Natural conversation | Natural answer | Structured notes |
| **Time** | Quick (back-and-forth) | Longer (comprehensive) | Batch (all at once) |
| **Best when** | Exploring & uncertain | Need full picture | Want consistency |
| **What's it for?** | Conversational exploration | Comprehensive Q&A | Template-based extraction |
| **# of questions** | Multiple (conversational) | One | One template per source |
| **Context control** | Manual (you choose) | Automatic (system searches) | One source at a time |
| **Conversational?** | Yes (follow-ups work) | No (one question only) | No (single operation) |
| **Output** | Natural conversation | Natural answer | Structured note |
| **Time** | Quick (back-and-forth) | Longer (comprehensive) | Per source |
| **Best when** | Exploring & uncertain | Need full picture | Want consistent format |
| **Model speed** | Any | Fast preferred | Any |
---
@ -199,8 +202,10 @@ Goal: Write literature review from 15 papers
Step 1: TRANSFORMATIONS
- Define: "Extract abstract, methodology, findings, relevance"
- Apply to all 15 papers
- Get back 15 structured notes
- Apply to paper 1 → get structured note
- Apply to paper 2 → get structured note
- ... repeat for all 15 papers
- Result: 15 structured notes with consistent format
Step 2: Read the notes
- Now you have consistent summaries
@ -231,7 +236,7 @@ Step 3: CHAT
Step 4: TRANSFORMATIONS (optional)
- Define: "Extract: pain point, frequency, who mentioned it"
- Apply to all interviews
- Apply to each interview (one by one)
- Get structured data for analysis
```
@ -338,11 +343,11 @@ CHAT → Save as Note → TRANSFORMATIONS
|-----------|-----|-----|
| "I want to explore a topic with follow-up questions" | **CHAT** | Conversational, you control context |
| "I need a comprehensive answer to one complex question" | **ASK** | Automatic search, synthesized answer |
| "I want consistent summaries from 10+ sources" | **TRANSFORMATIONS** | Template reuse, batch processing |
| "I want consistent summaries from each source" | **TRANSFORMATIONS** | Template reuse, apply to each source |
| "I'm comparing two specific sources" | **CHAT** | Select just those 2, have discussion |
| "I need to categorize all sources by X criteria" | **TRANSFORMATIONS** | Extract category for each source |
| "I need to categorize each source by X criteria" | **TRANSFORMATIONS** | Extract category from each source |
| "I want to understand the big picture across all sources" | **ASK** | Automatic comprehensive search |
| "I want to build a knowledge base" | **TRANSFORMATIONS** | Create structured notes |
| "I want to build a knowledge base" | **TRANSFORMATIONS** | Create structured note from each source |
| "I want to iterate on understanding" | **CHAT** | Multiple questions, refine thinking |
The key insight: **Different questions need different tools.** Open Notebook gives you all three because research rarely fits one mode.

10
docs/2-CORE-CONCEPTS/index.md
View file

@ -12,16 +12,16 @@ How Open Notebook organizes your research. Understand the three-tier container s
---
### 2. [AI Context & RAG](ai-context-rag.md)
How Open Notebook makes AI aware of your research without uploading everything to the cloud.
How Open Notebook makes AI aware of your research - two different approaches.
**Key idea**: RAG (Retrieval-Augmented Generation) means the AI searches your content, finds relevant pieces, and answers based on what it found. You control which content is in scope.
**Key idea**: **Chat** sends entire selected sources to the LLM (full context, conversational). **Ask** uses RAG (retrieval-augmented generation) to automatically search and retrieve only relevant chunks. Different tools for different needs.
---
### 3. [Chat vs. Transformations](chat-vs-transformations.md)
Why Open Notebook has different interaction modes and when to use each one.
**Key idea**: Chat is conversational exploration (you control context). Transformations are batch processing (you define the template). They answer different questions.
**Key idea**: Chat is conversational exploration (you control context). Transformations are insight extractions. They reduced content to smaller bits of concentrated/dense information, which is much more suitable for an AI to use.
---
@ -42,8 +42,8 @@ Why Open Notebook can turn research into audio and why this matters.
## Read This Section If:
- **You're new to Open Notebook** — Start here to understand how the system works conceptually before learning the features
- **You're confused about RAG** — Section 2 explains what it is and why it matters
- **You're wondering when to use Chat vs Ask** — Section 3 clarifies the differences
- **You're confused about Chat vs Ask** — Section 2 explains the difference (full-content vs RAG)
- **You're wondering when to use Chat vs Transformations** — Section 3 clarifies the differences
- **You want to understand privacy controls** — Section 4 shows you what you can control
- **You're curious about podcasts** — Section 5 explains the architecture and why it's different from competitors

2
docs/5-CONFIGURATION/advanced.md
View file

@ -192,7 +192,7 @@ API_URL=https://mynotebook.example.com
### Firewall Rules
Restrict access to your Open Notebook:
- Port 8502/3000 (frontend): Only from your IP
- Port 8502 (frontend): Only from your IP
- Port 5055 (API): Only from frontend
- Port 8000 (SurrealDB): Never expose to internet

4
docs/5-CONFIGURATION/server.md
View file

@ -139,7 +139,7 @@ Edit docker-compose.yml:
services:
frontend:
ports:
- "8001:3000" # Change from 8502 to 8001
- "8001:8502" # Change from 8502 to 8001
```
Access at: `http://localhost:8001`
@ -292,7 +292,7 @@ server {
# Frontend
location / {
proxy_pass http://localhost:3000;
proxy_pass http://localhost:8502;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

20
docs/6-TROUBLESHOOTING/connection-issues.md
View file

@ -60,7 +60,7 @@ docker compose up -d
cat .env | grep API_URL
# Should match your frontend URL:
# Frontend: http://localhost:3000
# Frontend: http://localhost:8502
# API_URL: http://localhost:5055
# If wrong, fix it:
@ -292,7 +292,7 @@ docker compose restart
### Step 3: Access from Other Machine
```bash
# In browser on other machine:
http://192.168.1.100:3000
http://192.168.1.100:8502
# (or your server IP)
```
@ -302,7 +302,7 @@ http://192.168.1.100:3000
docker compose ps
# Should show port mapping:
# 0.0.0.0:3000->3000/tcp
# 0.0.0.0:8502->8502/tcp
# 0.0.0.0:5055->5055/tcp
```
@ -311,7 +311,7 @@ docker compose ps
# Check firewall on server
sudo ufw status
# May need to open ports:
sudo ufw allow 3000
sudo ufw allow 8502
sudo ufw allow 5055
# Check on different machine:
@ -341,7 +341,7 @@ CORS policy: Response to preflight request doesn't pass access control check
```bash
# Check browser console error for what URLs are being used
# The error shows:
# - Requesting from: http://localhost:3000
# - Requesting from: http://localhost:8502
# - Trying to reach: http://localhost:5055
# Make sure API_URL matches:
@ -364,19 +364,19 @@ docker compose ps
# All should show "Up"
# 2. Ports listening?
netstat -tlnp | grep -E "3000|5055|8000"
netstat -tlnp | grep -E "8502|5055|8000"
# 3. API responding?
curl http://localhost:5055/health
# 4. Frontend accessible?
curl http://localhost:3000 | head
curl http://localhost:8502 | head
# 5. Network OK?
ping google.com
# 6. No firewall?
sudo ufw status | grep -E "5055|3000|8000"
sudo ufw status | grep -E "5055|8502|8000"
```
---
@ -384,9 +384,9 @@ sudo ufw status | grep -E "5055|3000|8000"
## Checklist for Remote Access
- [ ] Server IP noted (e.g., 192.168.1.100)
- [ ] Ports 3000, 5055, 8000 exposed in docker-compose
- [ ] Ports 8502, 5055, 8000 exposed in docker-compose
- [ ] API_URL set to server IP
- [ ] Firewall allows ports 3000, 5055, 8000
- [ ] Firewall allows ports 8502, 5055, 8000
- [ ] Can reach server from client machine (ping IP)
- [ ] All services running (docker compose ps)
- [ ] Can curl API from client (curl http://IP:5055/health)

14
docs/6-TROUBLESHOOTING/quick-fixes.md
View file

@ -26,7 +26,7 @@ curl http://localhost:5055/health
docker compose restart
# Step 4: Try again
# Open http://localhost:3000 in browser
# Open http://localhost:8502 in browser
```
**If still broken:**
@ -70,7 +70,7 @@ docker compose logs api | grep -i "api key\|error"
## #3: "Port X already in use"
**Symptom:** Docker error "Port 3000 is already allocated"
**Symptom:** Docker error "Port 8502 is already allocated"
**Cause:** Another service using that port
@ -78,18 +78,18 @@ docker compose logs api | grep -i "api key\|error"
```bash
# Option 1: Stop the other service
# Find what's using port 3000
lsof -i :3000
# Find what's using port 8502
lsof -i :8502
# Kill it or close the app
# Option 2: Use different port
# Edit docker-compose.yml
# Change: - "3000:3000"
# To: - "3001:3000"
# Change: - "8502:8502"
# To: - "8503:8502"
# Then restart
docker compose restart
# Access at: http://localhost:3001
# Access at: http://localhost:8503
```
---