docs/1-INSTALLATION/from-source.md

From Source Installation

Clone the repository and run locally. For developers and contributors.

Prerequisites

• Python 3.11+ - Download
• Node.js 18+ - Download
• Git - Download
• Docker (for SurrealDB) - Download
• uv (Python package manager) - curl -LsSf https://astral.sh/uv/install.sh | sh
• API key from OpenAI or similar (or use Ollama for free)

Quick Setup (10 minutes)

1. Clone Repository

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook

# If you forked it:
git clone https://github.com/YOUR_USERNAME/open-notebook.git
cd open-notebook
git remote add upstream https://github.com/lfnovo/open-notebook.git

2. Install Python Dependencies

uv sync
uv pip install python-magic

2.1 Alternative: Conda Setup (Optional)

If you prefer using Conda to manage your environments, follow these steps instead of the standard uv sync:

# Create and activate the environment
conda create -n open-notebook python=3.11 -y
conda activate open-notebook

# Install uv inside conda to maintain compatibility with the Makefile
conda install -c conda-forge uv nodejs -y

# Sync dependencies
uv sync

Note: Installing uv inside your Conda environment ensures that commands like make start-all and make api continue to work seamlessly.

3. Start SurrealDB

# Terminal 1
make database
# or: docker compose up surrealdb

4. Set Environment Variables

cp .env.example .env
# Edit .env and set:
# OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key

After starting the app, configure AI providers via the Settings → API Keys UI in the browser.

5. Start API

# Terminal 2
make api
# or: uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055

6. Start Frontend

# Terminal 3
cd frontend && npm install && npm run dev

7. Access

• Frontend: http://localhost:3000
• API Docs: http://localhost:5055/docs
• Database: http://localhost:8000

8. Configure AI Provider

1. Open http://localhost:3000
2. Go to Settings → API Keys
3. Click Add Credential → Select your provider → Paste API key
4. Click Save, then Test Connection
5. Click Discover Models → Register Models

---

Development Workflow

Code Quality

# Format and lint Python
make ruff
# or: ruff check . --fix

# Type checking
make lint
# or: uv run python -m mypy .

Run Tests

uv run pytest tests/

Common Commands

# Start everything
make start-all

# View API docs
open http://localhost:5055/docs

# Check database migrations
# (Auto-run on API startup)

# Clean up
make clean

---

Troubleshooting

Python version too old

python --version  # Check version
uv sync --python 3.11  # Use specific version

npm: command not found

Install Node.js from https://nodejs.org/

Database connection errors

docker ps  # Check SurrealDB running
docker logs surrealdb  # View logs

Port 5055 already in use

# Use different port
uv run uvicorn api.main:app --port 5056

---

Next Steps

1. Read Development Guide
2. See Architecture Overview
3. Check Contributing Guide

---

Getting Help

• Discord: Community
• Issues: GitHub Issues