open-notebook/CONFIGURATION.md

Configuration Guide

API Connection Configuration

Starting from version 1.0.0-alpha, Open Notebook uses a simplified API connection system that automatically configures itself based on your deployment environment.

How It Works

The frontend now automatically discovers the API location at runtime, eliminating the need for complex network configurations. This works for both Docker deployment modes:

• Multi-container (docker-compose with separate SurrealDB)
• Single-container (all services in one container)

Default Configuration

By default, the API is accessible at http://localhost:5055. This works for most local Docker deployments where:

• You access the frontend at http://localhost:8502
• Your browser can directly reach http://localhost:5055

No configuration needed for standard localhost deployments!

Custom Configuration

If you need to change the API URL (e.g., running on a different host, port, or domain), you can configure it using the API_URL environment variable.

Option 1: Using docker-compose (Recommended)

Edit your docker.env file:

API_URL=http://your-server-ip:5055

Or add it to your docker-compose.yml:

services:
  open_notebook:
    image: lfnovo/open_notebook:latest
    ports:
      - "8502:8502"
      - "5055:5055"  # API port must be exposed
    environment:
      - API_URL=http://your-server-ip:5055

Option 2: Using docker run

docker run -e API_URL=http://your-server-ip:5055 \
  -p 8502:8502 \
  -p 5055:5055 \
  lfnovo/open_notebook:latest

Important Notes

1. Port 5055 must be exposed: The browser needs direct access to the API, so port 5055 must be mapped in your Docker configuration.

2. Use the externally accessible URL: The API_URL should be the URL that a browser can reach, not internal Docker networking addresses.

3. Protocol matters: Use http:// for local deployments, https:// if you've set up SSL.

Examples

Running on a different host

API_URL=http://192.168.1.100:5055

Running on a custom domain with SSL

API_URL=https://notebook.example.com/api

Running on a custom port

API_URL=http://localhost:3055

(Remember to update the port mapping in docker-compose accordingly)

Troubleshooting

"Unable to connect to server" error on login:

1. Verify port 5055 is exposed in your Docker configuration
2. Check that API_URL matches the URL your browser can access
3. Try accessing http://localhost:5055/health directly in your browser
4. If that fails, the API isn't running or port isn't exposed

API works but frontend doesn't connect:

1. Check browser console for CORS errors
2. Verify API_URL is set correctly
3. Make sure you're using the same protocol (http/https) throughout

Migration from Previous Versions

If you were previously exposing port 5055 manually or had custom configurations, you may need to:

1. Update your docker.env or environment variables to include API_URL
2. Ensure port 5055 is exposed in your docker-compose.yml (it's now required)
3. Remove any custom Next.js configuration or environment variables you may have added

The default configuration will work for most users without any changes.