mirror of
https://github.com/lfnovo/open-notebook.git
synced 2026-04-28 19:40:50 +00:00
e13e4a2d8b
- Replace old docs structure with new comprehensive documentation - Organize into 8 major sections (0-START-HERE through 7-DEVELOPMENT) - Convert CONFIGURATION.md, CONTRIBUTING.md, MAINTAINER_GUIDE.md to redirects - Remove outdated MIGRATION.md and DESIGN_PRINCIPLES.md - Fix all internal documentation links and cross-references - Add progressive disclosure paths for different user types - Include 44 focused guides covering all features - Update README.md to remove v1.0 breaking changes notice
2.7 KiB
2.7 KiB
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)
- API Health: http://localhost:5055/health → should return
{"status": "ok"} - API Docs: http://localhost:5055/docs → interactive API documentation
- Frontend: http://localhost:3000 → Open Notebook UI
All three show up? ✅ You're ready to develop!
Next Steps
- First Issue? Pick a good first issue
- Understand the code? Read Architecture Overview
- Make changes? Follow Contributing Guide
- Setup details? See Development Setup
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.