open-notebook/docs/migration/streamlit-to-nextjs.md

Migration Guide: Next.js to Next.js Frontend

Complete guide for upgrading from the React frontend to the new Next.js frontend.

Overview

Open Notebook has migrated from a Next.js-based user interface to a modern Next.js/React frontend. This upgrade provides:

• Improved Performance: Faster page loads and smoother interactions
• Modern UI/UX: Contemporary design with better responsiveness
• Enhanced Features: Better real-time updates and interactivity
• Future-Ready: Foundation for upcoming features like live updates

What's Changing

User Interface

• Old: Next.js-based UI (Python/Next.js)
• New: Next.js/React frontend (JavaScript/TypeScript)

What Stays the Same

• ✅ Same Port: Still runs on port 8502
• ✅ API Unchanged: REST API remains on port 5055
• ✅ Data Intact: All your notebooks, sources, and notes are preserved
• ✅ Configuration: Same environment variables and settings
• ✅ Features: All existing functionality works the same way

Upgrade Instructions

For Docker Users (Recommended)

Single-Container Setup

1. Stop the current container:

   docker compose down
   

2. Pull the latest image:

   docker compose pull
   

3. Start with the new version:

   docker compose up -d
   

4. Verify it's running:

   • Open http://localhost:8502 in your browser
   • You should see the new Next.js interface

Multi-Container Setup

Same steps as above - the process is identical.

For Development Setup

If you're running Open Notebook from source:

1. Pull the latest changes:

   git pull origin main
   

2. Install frontend dependencies:

   cd frontend
   npm install
   npm run build
   cd ..
   

3. Start the application:

   make start-all
   

4. Access the new interface:

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

Verification Steps

After upgrading, verify everything works correctly:

1. Check the UI loads:

   • Navigate to http://localhost:8502
   • You should see a modern interface with a cleaner design

2. Test your notebooks:

   • Open an existing notebook
   • Verify sources are visible
   • Check notes are accessible
   • Try the chat functionality

3. Test core features:

   • Create a new notebook
   • Add a source (URL, file, or text)
   • Generate a note
   • Search your content
   • Start a chat session

4. Check API access (if you use it):

   • Navigate to http://localhost:5055/docs
   • API documentation should be accessible
   • Test any custom integrations

Troubleshooting

UI Doesn't Load

Symptom: Browser shows error or blank page at http://localhost:8502

Solutions:

1. Check container logs:

   docker compose logs -f open_notebook
   

2. Verify container is running:

   docker compose ps
   

3. Try restarting:

   docker compose restart open_notebook
   

Port Conflicts

Symptom: Error about port 8502 already in use

Solutions:

1. Check what's using the port:

   # macOS/Linux
   lsof -i :8502
   
   # Windows
   netstat -ano | findstr :8502
   

2. Stop the conflicting service or change Open Notebook's port:

   # In docker-compose.yml
   ports:
     - "8503:8502"  # Maps host port 8503 to container port 8502
   

Data Not Showing

Symptom: Notebooks or sources appear empty

Solutions:

1. Verify volume mounts are correct:

   docker compose config
   

2. Check database is running (multi-container):

   docker compose ps surrealdb
   

3. Verify data directories exist:

   ls -la notebook_data/
   ls -la surreal_data/
   

API Errors

Symptom: Frontend shows "Cannot connect to API" or similar errors

Solutions:

1. Verify API is running:

   curl http://localhost:5055/health
   

2. Check API logs:

   docker compose logs -f open_notebook | grep api
   

3. Ensure environment variables are set:

   docker compose exec open_notebook env | grep SURREAL
   

Rollback Instructions

If you need to rollback to the Next.js version:

Quick Rollback

1. Stop current containers:

   docker compose down
   

2. Use a specific older version (replace with your previous version):

   # In docker-compose.yml, change:
   image: lfnovo/open_notebook:0.1.45-single  # or whatever version you had
   

3. Start the old version:

   docker compose up -d
   

Finding Your Previous Version

Check your Docker images:

docker images | grep open_notebook

Or check the releases page for version numbers.

Frequently Asked Questions

Do I need to backup before upgrading?

While the upgrade process doesn't modify your data, it's always a good practice to backup:

# Backup your data
tar -czf backup-$(date +%Y%m%d).tar.gz notebook_data surreal_data

Will my bookmarks still work?

Yes! The new frontend still runs on port 8502, so all your bookmarks will continue to work.

Do I need to reconfigure AI models?

No, all your model configurations are stored in the database and will work automatically with the new UI.

Will my API integrations break?

No, the API is completely unchanged. All existing integrations will continue to work.

What if I prefer the old React frontend?

You can rollback to any previous version using the instructions above. However, we recommend trying the new UI as it provides better performance and will receive all future updates.

How do I report issues with the new UI?

Please report any issues on our GitHub Issues page or join our Discord server for help.

New Features in Next.js UI

While the migration maintains feature parity, the new frontend enables:

• Better Performance: Faster loading and navigation
• Improved Responsiveness: Better mobile and tablet support
• Modern Design: Cleaner, more intuitive interface
• Foundation for Future: Enables upcoming features like real-time collaboration

Getting Help

If you encounter any issues during migration:

1. Check the logs: docker compose logs -f
2. Review this guide: Most issues are covered in Troubleshooting
3. Join Discord: discord.gg/37XJPXfz2w
4. Open an issue: GitHub Issues

Post-Migration Checklist

After successfully migrating, complete these steps:

• Verify all notebooks load correctly
• Test source addition and viewing
• Verify notes are accessible
• Test chat functionality
• Check search works as expected
• Verify podcast generation (if used)
• Test any custom API integrations
• Update any deployment documentation you maintain
• Remove old Docker images to free space: docker image prune

---

Questions? Join our Discord community or open an issue on GitHub.