mirror of
https://github.com/lfnovo/open-notebook.git
synced 2026-05-04 06:10:35 +00:00
docs: new docs
This commit is contained in:
LUIS NOVO
parent
3bb691d0b8
commit
b20c62df47
44 changed files with 12929 additions and 1853 deletions
351
docs/deployment/single-container.md
Normal file
351
docs/deployment/single-container.md
Normal file
|
|
@ -0,0 +1,351 @@
|
|||
# Single Container Deployment
|
||||
|
||||
For users who prefer an all-in-one container solution (e.g., PikaPods, Railway, simple cloud deployments), Open Notebook provides a single-container image that includes all services: SurrealDB, API backend, background worker, and Streamlit UI.
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
The single-container deployment packages everything you need:
|
||||
- **SurrealDB**: Database service
|
||||
- **FastAPI**: REST API backend
|
||||
- **Background Worker**: For podcast generation and transformations
|
||||
- **Streamlit**: Web UI interface
|
||||
|
||||
All services are managed by supervisord with proper startup ordering, making it perfect for platforms that prefer single-container deployments.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: Docker Compose (Recommended)
|
||||
|
||||
This is the easiest way to get started with persistent data.
|
||||
|
||||
1. **Create a project directory**:
|
||||
```bash
|
||||
mkdir open-notebook
|
||||
cd open-notebook
|
||||
```
|
||||
|
||||
2. **Create a `docker-compose.single.yml` file**:
|
||||
```yaml
|
||||
services:
|
||||
open_notebook_single:
|
||||
image: lfnovo/open_notebook:latest-single
|
||||
ports:
|
||||
- "8502:8502" # Streamlit UI
|
||||
- "5055:5055" # REST API
|
||||
environment:
|
||||
# Required: Add your API keys here
|
||||
- OPENAI_API_KEY=your_openai_key
|
||||
- ANTHROPIC_API_KEY=your_anthropic_key
|
||||
|
||||
# Optional: Additional providers
|
||||
- GOOGLE_API_KEY=your_google_key
|
||||
- GROQ_API_KEY=your_groq_key
|
||||
|
||||
# Optional: Password protection for public deployments
|
||||
- OPEN_NOTEBOOK_PASSWORD=your_secure_password
|
||||
volumes:
|
||||
- ./notebook_data:/app/data # Application data
|
||||
- ./surreal_single_data:/mydata # SurrealDB data
|
||||
restart: always
|
||||
```
|
||||
|
||||
3. **Start the container**:
|
||||
```bash
|
||||
docker compose -f docker-compose.single.yml up -d
|
||||
```
|
||||
|
||||
4. **Access the application**:
|
||||
- Streamlit UI: http://localhost:8502
|
||||
- REST API: http://localhost:5055
|
||||
- API Documentation: http://localhost:5055/docs
|
||||
|
||||
### Option 2: Direct Docker Run
|
||||
|
||||
For quick testing without docker-compose:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name open-notebook-single \
|
||||
-p 8502:8502 \
|
||||
-p 5055:5055 \
|
||||
-v ./notebook_data:/app/data \
|
||||
-v ./surreal_single_data:/mydata \
|
||||
-e OPENAI_API_KEY=your_openai_key \
|
||||
-e ANTHROPIC_API_KEY=your_anthropic_key \
|
||||
-e OPEN_NOTEBOOK_PASSWORD=your_secure_password \
|
||||
lfnovo/open_notebook:latest-single
|
||||
```
|
||||
|
||||
## 🌐 Platform-Specific Deployments
|
||||
|
||||
### PikaPods
|
||||
|
||||
Perfect for PikaPods one-click deployment:
|
||||
|
||||
1. **Use this configuration**:
|
||||
```
|
||||
Image: lfnovo/open_notebook:latest-single
|
||||
Port: 8502
|
||||
```
|
||||
|
||||
2. **Set environment variables in PikaPods**:
|
||||
```
|
||||
OPENAI_API_KEY=your_openai_key
|
||||
OPEN_NOTEBOOK_PASSWORD=your_secure_password
|
||||
```
|
||||
|
||||
3. **Mount volumes**:
|
||||
- `/app/data` for application data
|
||||
- `/mydata` for database files
|
||||
|
||||
### Railway
|
||||
|
||||
For Railway deployment:
|
||||
|
||||
1. **Connect your GitHub repository** or use the template
|
||||
2. **Set environment variables**:
|
||||
```
|
||||
OPENAI_API_KEY=your_openai_key
|
||||
OPEN_NOTEBOOK_PASSWORD=your_secure_password
|
||||
```
|
||||
3. **Configure volumes** in Railway dashboard for data persistence
|
||||
|
||||
### DigitalOcean App Platform
|
||||
|
||||
1. **Create a new app** from Docker Hub
|
||||
2. **Use image**: `lfnovo/open_notebook:latest-single`
|
||||
3. **Set environment variables** in the app settings
|
||||
4. **Configure persistent storage** for `/app/data` and `/mydata`
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The single-container deployment uses the same environment variables as the multi-container setup, but with SurrealDB configured for localhost connection:
|
||||
|
||||
```bash
|
||||
# Database connection (automatically configured)
|
||||
SURREAL_URL="ws://localhost:8000/rpc"
|
||||
SURREAL_USER="root"
|
||||
SURREAL_PASSWORD="root"
|
||||
SURREAL_NAMESPACE="open_notebook"
|
||||
SURREAL_DATABASE="staging"
|
||||
|
||||
# Required: At least one AI provider
|
||||
OPENAI_API_KEY=your_openai_key
|
||||
|
||||
# Optional: Additional AI providers
|
||||
ANTHROPIC_API_KEY=your_anthropic_key
|
||||
GOOGLE_API_KEY=your_google_key
|
||||
GROQ_API_KEY=your_groq_key
|
||||
OLLAMA_API_BASE=http://your-ollama-host:11434
|
||||
|
||||
# Optional: Security for public deployments
|
||||
OPEN_NOTEBOOK_PASSWORD=your_secure_password
|
||||
|
||||
# Optional: Advanced TTS
|
||||
ELEVENLABS_API_KEY=your_elevenlabs_key
|
||||
```
|
||||
|
||||
### Data Persistence
|
||||
|
||||
**Critical**: Always mount these volumes to persist data between container restarts:
|
||||
|
||||
1. **`/app/data`** - Application data (notebooks, sources, uploads)
|
||||
2. **`/mydata`** - SurrealDB database files
|
||||
|
||||
**Example with proper volumes**:
|
||||
```yaml
|
||||
volumes:
|
||||
- ./notebook_data:/app/data # Your notebooks and sources
|
||||
- ./surreal_single_data:/mydata # Database files
|
||||
```
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
### Password Protection
|
||||
|
||||
For public deployments, **always set a password**:
|
||||
|
||||
```bash
|
||||
OPEN_NOTEBOOK_PASSWORD=your_secure_password
|
||||
```
|
||||
|
||||
This protects both the Streamlit UI and REST API with password authentication.
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
1. **Use HTTPS**: Deploy behind a reverse proxy with SSL
|
||||
2. **Strong Password**: Use a complex, unique password
|
||||
3. **Regular Updates**: Keep the container image updated
|
||||
4. **Network Security**: Configure firewall rules appropriately
|
||||
5. **Monitor Access**: Check logs for suspicious activity
|
||||
|
||||
## 🏗️ Building from Source
|
||||
|
||||
To build the single-container image yourself:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/lfnovo/open-notebook
|
||||
cd open-notebook
|
||||
|
||||
# Build the single-container image
|
||||
make docker-build-single-dev
|
||||
|
||||
# Or build with multi-platform support
|
||||
make docker-build-single
|
||||
```
|
||||
|
||||
## 📊 Service Management
|
||||
|
||||
### Startup Order
|
||||
|
||||
Services start in this order with proper delays:
|
||||
1. **SurrealDB** (5 seconds startup time)
|
||||
2. **API Backend** (3 seconds startup time)
|
||||
3. **Background Worker** (3 seconds startup time)
|
||||
4. **Streamlit UI** (5 seconds startup time)
|
||||
|
||||
### Service Monitoring
|
||||
|
||||
All services are managed by supervisord. Check service status:
|
||||
|
||||
```bash
|
||||
# View all services
|
||||
docker exec -it open-notebook-single supervisorctl status
|
||||
|
||||
# View specific service logs
|
||||
docker exec -it open-notebook-single supervisorctl tail -f api
|
||||
docker exec -it open-notebook-single supervisorctl tail -f streamlit
|
||||
```
|
||||
|
||||
## 💻 Resource Requirements
|
||||
|
||||
### Minimum Requirements
|
||||
- **Memory**: 1GB RAM
|
||||
- **CPU**: 1 core
|
||||
- **Storage**: 10GB (for data persistence)
|
||||
- **Network**: Internet connection for AI providers
|
||||
|
||||
### Recommended for Production
|
||||
- **Memory**: 2GB+ RAM
|
||||
- **CPU**: 2+ cores
|
||||
- **Storage**: 50GB+ (for larger datasets)
|
||||
- **Network**: Stable high-speed internet
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Container Won't Start
|
||||
|
||||
**Check the logs**:
|
||||
```bash
|
||||
docker logs open-notebook-single
|
||||
```
|
||||
|
||||
**Common issues**:
|
||||
- Insufficient memory (increase to 2GB+)
|
||||
- Port conflicts (change port mapping)
|
||||
- Missing API keys (check environment variables)
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
**Symptoms**: API errors, empty notebooks, connection timeouts
|
||||
|
||||
**Solutions**:
|
||||
1. **Check memory**: SurrealDB needs at least 512MB
|
||||
2. **Verify volumes**: Ensure `/mydata` is mounted and writable
|
||||
3. **Check startup order**: Wait for full startup (30-60 seconds)
|
||||
4. **Restart container**: Sometimes a fresh start helps
|
||||
|
||||
### Service Startup Problems
|
||||
|
||||
**Check individual services**:
|
||||
```bash
|
||||
# Enter the container
|
||||
docker exec -it open-notebook-single bash
|
||||
|
||||
# Check service status
|
||||
supervisorctl status
|
||||
|
||||
# Restart specific service
|
||||
supervisorctl restart api
|
||||
supervisorctl restart streamlit
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
**Symptoms**: Slow response times, timeouts
|
||||
|
||||
**Solutions**:
|
||||
1. **Increase memory**: Allocate 2GB+ RAM
|
||||
2. **Check CPU**: Ensure adequate CPU resources
|
||||
3. **Monitor logs**: Look for performance bottlenecks
|
||||
4. **Optimize models**: Use faster models for real-time tasks
|
||||
|
||||
## 📊 Comparison: Single vs Multi-Container
|
||||
|
||||
| Feature | Single-Container | Multi-Container |
|
||||
|---------|------------------|-----------------|
|
||||
| **Deployment** | One container | Multiple containers |
|
||||
| **Complexity** | Simple | More complex |
|
||||
| **Scaling** | All services together | Independent scaling |
|
||||
| **Resource Control** | Shared resources | Fine-grained control |
|
||||
| **Debugging** | All logs in one place | Separate service logs |
|
||||
| **Platform Support** | Excellent for PaaS | Better for Kubernetes |
|
||||
| **Memory Usage** | More efficient | More flexible |
|
||||
| **Startup Time** | Faster | Slower |
|
||||
|
||||
## 🎯 When to Use Single-Container
|
||||
|
||||
### ✅ Use Single-Container When:
|
||||
- **Platform requirements**: PikaPods, Railway, or similar platforms
|
||||
- **Simple deployment**: You want the easiest possible setup
|
||||
- **Resource constraints**: Limited memory/CPU resources
|
||||
- **Quick testing**: Rapid deployment for testing
|
||||
- **Single user**: Personal use without scaling needs
|
||||
|
||||
### ❌ Use Multi-Container When:
|
||||
- **Production scaling**: Need to scale services independently
|
||||
- **Resource optimization**: Want fine-grained resource control
|
||||
- **Development**: Building/debugging the application
|
||||
- **High availability**: Need service-level redundancy
|
||||
- **Complex networking**: Custom networking requirements
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
### Quick Diagnostics
|
||||
|
||||
Before asking for help, gather this information:
|
||||
|
||||
```bash
|
||||
# Container status
|
||||
docker ps
|
||||
|
||||
# Container logs
|
||||
docker logs open-notebook-single
|
||||
|
||||
# Service status inside container
|
||||
docker exec -it open-notebook-single supervisorctl status
|
||||
|
||||
# Resource usage
|
||||
docker stats open-notebook-single
|
||||
```
|
||||
|
||||
### Community Support
|
||||
|
||||
- **[Discord Server](https://discord.gg/37XJPXfz2w)** - Real-time help and discussion
|
||||
- **[GitHub Issues](https://github.com/lfnovo/open-notebook/issues)** - Bug reports and feature requests
|
||||
- **[Documentation](../index.md)** - Complete documentation
|
||||
|
||||
### Common Solutions
|
||||
|
||||
1. **Port conflicts**: Change port mapping in docker-compose
|
||||
2. **Memory issues**: Increase container memory allocation
|
||||
3. **Volume permissions**: Ensure mounted volumes are writable
|
||||
4. **API key errors**: Verify environment variables are set correctly
|
||||
5. **Startup timeouts**: Wait 60+ seconds for full service startup
|
||||
|
||||
---
|
||||
|
||||
**Ready to deploy?** Start with Option 1 (Docker Compose) above for the best experience!
|
||||
Loading…
Add table
Add a link
Reference in a new issue