Skip to content

quick-start.md

Latest commit

 

History

History
128 lines (90 loc) · 2.72 KB

quick-start.md

File metadata and controls

128 lines (90 loc) · 2.72 KB

Quick Start - Development

Get Open Notebook running locally in 5 minutes.

Prerequisites

  • Python 3.11+
  • Git
  • uv (package manager) - install with curl -LsSf https://astral.sh/uv/install.sh | sh
  • Docker (optional, for SurrealDB)

1. Clone the Repository (2 min)

# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/open-notebook.git
cd open-notebook

# Add upstream remote for updates
git remote add upstream https://github.com/lfnovo/open-notebook.git

2. Install Dependencies (2 min)

# Install Python dependencies
uv sync

# Verify uv is working
uv --version

3. Start Services (1 min)

In separate terminal windows:

# Terminal 1: Start SurrealDB (database)
make database
# or: docker run -d --name surrealdb -p 8000:8000 surrealdb/surrealdb:v2 start --user root --pass password --bind 0.0.0.0:8000 memory

# Terminal 2: Start API (backend on port 5055)
make api
# or: uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055

# Terminal 3: Start Frontend (UI on port 3000)
cd frontend && npm run dev

4. Verify Everything Works (instant)

All three show up? ✅ You're ready to develop!

Next Steps

Troubleshooting

"Port 5055 already in use"

# Find what's using the port
lsof -i :5055

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

"Can't connect to SurrealDB"

# Check if SurrealDB is running
docker ps | grep surrealdb

# Restart it
make database

"Python version is too old"

# Check your Python version
python --version  # Should be 3.11+

# Use Python 3.11 specifically
uv sync --python 3.11

"npm: command not found"

# Install Node.js from https://nodejs.org/
# Then install frontend dependencies
cd frontend && npm install

Common Development Commands

# Run tests
uv run pytest

# Format code
make ruff

# Type checking
make lint

# Run the full stack
make start-all

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

Need more help? See Development Setup for details or join our Discord.