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
153 lines
2.7 KiB
Markdown
153 lines
2.7 KiB
Markdown
# From Source Installation
|
|
|
|
Clone the repository and run locally. **For developers and contributors.**
|
|
|
|
## Prerequisites
|
|
|
|
- **Python 3.11+** - [Download](https://www.python.org/)
|
|
- **Node.js 18+** - [Download](https://nodejs.org/)
|
|
- **Git** - [Download](https://git-scm.com/)
|
|
- **Docker** (for SurrealDB) - [Download](https://docker.com/)
|
|
- **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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
uv sync
|
|
uv pip install python-magic
|
|
```
|
|
|
|
### 3. Start SurrealDB
|
|
|
|
```bash
|
|
# Terminal 1
|
|
make database
|
|
# or: docker compose up surrealdb
|
|
```
|
|
|
|
### 4. Set Environment Variables
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and add your API key:
|
|
# OPENAI_API_KEY=sk-...
|
|
# (or ANTHROPIC_API_KEY, GROQ_API_KEY, etc.)
|
|
```
|
|
|
|
### 5. Start API
|
|
|
|
```bash
|
|
# Terminal 2
|
|
make api
|
|
# or: uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055
|
|
```
|
|
|
|
### 6. Start Frontend
|
|
|
|
```bash
|
|
# 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
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Format and lint Python
|
|
make ruff
|
|
# or: ruff check . --fix
|
|
|
|
# Type checking
|
|
make lint
|
|
# or: uv run python -m mypy .
|
|
```
|
|
|
|
### Run Tests
|
|
|
|
```bash
|
|
uv run pytest tests/
|
|
```
|
|
|
|
### Common Commands
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
docker ps # Check SurrealDB running
|
|
docker logs surrealdb # View logs
|
|
```
|
|
|
|
### Port 5055 already in use
|
|
|
|
```bash
|
|
# Use different port
|
|
uv run uvicorn api.main:app --port 5056
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Read [Development Guide](../7-DEVELOPMENT/quick-start.md)
|
|
2. See [Architecture Overview](../7-DEVELOPMENT/architecture.md)
|
|
3. Check [Contributing Guide](../7-DEVELOPMENT/contributing.md)
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
- **Discord**: [Community](https://discord.gg/37XJPXfz2w)
|
|
- **Issues**: [GitHub Issues](https://github.com/lfnovo/open-notebook/issues)
|