MIGRATION.md

Migration Guide: Streamlit to React/Next.js Frontend

Version: 1.0.0 Last Updated: October 2025

This guide helps existing Open Notebook users migrate from the legacy Streamlit frontend to the new React/Next.js frontend.

---

⚠️ Breaking Changes in v1.0

Open Notebook v1.0 introduces breaking changes that require manual migration. Please read this section carefully before upgrading.

Docker Tag Changes

The "latest" tag is now frozen at the last Streamlit version. Starting with v1.0, we use versioned tags to prevent unexpected breaking changes:

• latest and latest-single → FROZEN at Streamlit version (will not update)
• v1-latest and v1-latest-single → NEW tags for v1.x releases (recommended)
• X.Y.Z and X.Y.Z-single → Specific version tags (unchanged)

Why this change? The v1.0 release brings significant architectural changes (Streamlit → React/Next.js frontend). Freezing the "latest" tag prevents existing deployments from breaking unexpectedly, while the new "v1-latest" tag allows users to explicitly opt into the v1 architecture.

Quick Migration for Docker Users

If you're currently using latest or latest-single, you need to:

1. Update your docker-compose.yml or docker run command:

   # Before:
   image: lfnovo/open_notebook:latest-single
   
   # After (recommended):
   image: lfnovo/open_notebook:v1-latest-single
   

2. Expose port 5055 for the API (required in v1):

   ports:
     - "8502:8502"  # Frontend
     - "5055:5055"  # API (NEW - required)
   

3. Verify API connectivity after upgrade:

   curl http://localhost:5055/api/config
   

API Connectivity (Port 5055)

Important: v1.0 requires port 5055 to be exposed to your host machine so the frontend can communicate with the API.

Auto-Detection: The Next.js frontend automatically detects the API URL:

• If you access the frontend at http://localhost:8502, it uses http://localhost:5055
• If you access the frontend at http://192.168.1.100:8502, it uses http://192.168.1.100:5055
• If you access the frontend at http://my-server:8502, it uses http://my-server:5055

Manual Override: If auto-detection doesn't work (e.g., reverse proxy, complex networking), set the API_URL environment variable:

# Docker run example
docker run -d \
  --name open-notebook \
  -p 8502:8502 -p 5055:5055 \
  -e API_URL=http://my-custom-api:5055 \
  -v ./notebook_data:/app/data \
  -v ./surreal_data:/mydata \
  lfnovo/open_notebook:v1-latest-single

# docker-compose.yml example
services:
  open_notebook:
    image: lfnovo/open_notebook:v1-latest-single
    ports:
      - "8502:8502"
      - "5055:5055"
    environment:
      - API_URL=http://my-custom-api:5055
    volumes:
      - ./notebook_data:/app/data
      - ./surreal_data:/mydata

Health Check

Verify your API is accessible with:

# Local deployment
curl http://localhost:5055/api/config

# Remote deployment
curl http://your-server-ip:5055/api/config

Expected response:

{
  "version": "1.0.0",
  "latestVersion": "1.0.0",
  "hasUpdate": false,
  "dbStatus": "online"
}

Note: The API URL is now auto-detected by the frontend from the hostname you're accessing, so /api/config no longer returns apiUrl.

Troubleshooting

Problem: Frontend shows "Cannot connect to API" error

• Check: Is port 5055 exposed? Run docker ps and verify port mapping
• Check: Can you reach the API? Run curl http://localhost:5055/api/config
• Solution: If using custom networking, set API_URL environment variable

Problem: Auto-detection uses wrong hostname

• Example: Frontend at http://internal-hostname:8502 but API should use http://public-hostname:5055
• Solution: Set API_URL=http://public-hostname:5055 environment variable

Problem: Still running the old Streamlit version after docker pull

• Check: Are you using the "latest" tag? It's frozen at Streamlit version
• Solution: Update to v1-latest or v1-latest-single tag

---

What Changed

Open Notebook has migrated from a Streamlit-based frontend to a modern React/Next.js application. This brings significant improvements in performance, user experience, and maintainability.

Key Changes

Aspect	Before (Streamlit)	After (React/Next.js)
Frontend Framework	Streamlit	Next.js 15 + React 18
UI Components	Streamlit widgets	shadcn/ui + Radix UI
Frontend Port	8502	8502 (unchanged)
API Port	5055	5055 (unchanged)
Navigation	Sidebar with emoji icons	Clean sidebar navigation
Performance	Server-side rendering	Client-side React with API calls
Customization	Limited	Highly customizable

What Stayed the Same

• Core functionality: All features remain available
• API backend: FastAPI backend unchanged
• Database: SurrealDB unchanged
• Data format: No data migration needed
• Configuration: Same environment variables
• Docker deployment: Same ports and setup

Migration Paths

Path 1: Docker Users (Recommended)

If you're running Open Notebook via Docker, migration is automatic:

1. Stop the current version:

   docker-compose down
   

2. Update to the latest image:

   # Update docker-compose.yml to use v1-latest
   # Change from:
   image: lfnovo/open_notebook:latest-single
   # To:
   image: lfnovo/open_notebook:v1-latest-single
   

3. Start the new version:

   docker-compose pull
   docker-compose up -d
   

4. Access the new frontend:

   • Frontend: http://localhost:8502 (new React UI)
   • API Docs: http://localhost:5055/docs

Your data is automatically preserved! All notebooks, sources, and notes carry over seamlessly.

Path 2: Source Code Users

If you're running from source code:

1. Pull the latest code:

   git pull origin main
   

2. Install frontend dependencies:

   cd frontend
   npm install
   cd ..
   

3. Update Python dependencies:

   uv sync
   

4. Start services (3 terminals):

   # Terminal 1: Database
   make database
   
   # Terminal 2: API
   uv run python api/main.py
   
   # Terminal 3: Frontend (NEW)
   cd frontend && npm run dev
   

5. Access the application:

   • Frontend: http://localhost:8502
   • API: http://localhost:5055

Breaking Changes

Removed Features

The following Streamlit-specific features are no longer available:

• Streamlit cache: Replaced with React Query caching
• Streamlit session state: Replaced with React state management
• Direct file access via Streamlit: Use API endpoints instead

Changed Navigation

Navigation paths have been simplified:

Old Path	New Path
Settings → Models	Models
Settings → Advanced	Advanced
Other paths	(Same but cleaner navigation)

API Changes

No breaking API changes! The REST API remains fully backward compatible.

New Features in React Version

The React frontend brings several improvements:

Performance

• Faster page loads: Client-side rendering with React
• Better caching: React Query for intelligent data caching
• Optimized builds: Next.js automatic code splitting

User Experience

• Modern UI: Clean, professional interface with shadcn/ui
• Responsive design: Better mobile and tablet support
• Keyboard shortcuts: Improved keyboard navigation
• Real-time updates: Better WebSocket support

Developer Experience

• TypeScript: Full type safety
• Component library: Reusable UI components
• Hot reload: Instant updates during development
• Testing: Better test infrastructure

Troubleshooting

Issue: Can't access the frontend

Solution:

# Check if services are running
docker-compose ps

# Check logs
docker-compose logs open_notebook

# Restart services
docker-compose restart

Issue: API errors in new frontend

Solution: The new frontend requires the API to be running. Ensure:

# API should be accessible at
curl http://localhost:5055/health

# If not, check API logs
docker-compose logs open_notebook | grep api

Issue: Missing data after migration

Solution: Data is preserved automatically. If you don't see your data:

1. Check database volume is mounted correctly:

   docker-compose down
   # Verify volumes in docker-compose.yml:
   # - ./surreal_data:/mydata  (for multi-container)
   # - ./surreal_single_data:/mydata (for single-container)
   docker-compose up -d
   

2. Check SurrealDB is running:

   docker-compose logs surrealdb
   

Issue: Port conflicts

Solution: If ports 8502 or 5055 are already in use:

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

# Stop conflicting service or change Open Notebook ports
# Edit docker-compose.yml:
ports:
  - "8503:8502"  # Change external port
  - "5056:5055"  # Change external port

Rollback Instructions

If you need to roll back to the Streamlit version:

Docker Users

# Stop current version
docker-compose down

# Edit docker-compose.yml to use old image
# Change to: lfnovo/open_notebook:streamlit-latest

# Start old version
docker-compose up -d

Source Code Users

# Checkout the last Streamlit version tag
git checkout tags/streamlit-final

# Install dependencies
uv sync

# Start Streamlit
uv run streamlit run app_home.py

Getting Help

If you encounter issues during migration:

• Discord: Join our Discord community for real-time help
• GitHub Issues: Report bugs at github.com/lfnovo/open-notebook/issues
• Documentation: Check full documentation

FAQs

Will my notebooks and data be lost?

No! All data is preserved. The database and API backend are unchanged.

Do I need to update my API integrations?

No! The REST API remains fully backward compatible.

Can I use both frontends simultaneously?

Technically yes, but not recommended. Choose one for consistency.

What about my custom Streamlit pages?

Custom Streamlit pages won't work with the React frontend. Consider:

• Using the REST API to build custom integrations
• Contributing React components to the project
• Requesting features in GitHub issues

Is the Streamlit version still supported?

The Streamlit version is no longer actively developed. We recommend migrating to the React version for the best experience and latest features.

Timeline

• Legacy (Pre-v1.0): Streamlit frontend
• Current (v1.0+): React/Next.js frontend
• Future: Continued React development with new features

---

Ready to migrate? Follow the migration path for your deployment method above. The process is straightforward and your data is safe!