Entry Points for the Open Notebook Application: Backend, Frontend, and Docker

Open Notebook uses three distinct entry points: run_api.py for the FastAPI backend, frontend/start-server.js for the Next.js frontend, and a Docker supervisord configuration that orchestrates both.

The lfnovo/open-notebook repository is organized as a dual-component application consisting of a Python backend and a Node.js frontend. Understanding the entry points for the application is essential for both local development and production deployments. Whether you are running the stack via Docker or starting services individually, each component has a specific launch sequence defined in the source code.

Backend Entry Point (run_api.py and api/main.py)

The Python backend exposes a FastAPI application that initializes database connections and registers API routers.

The run_api.py Launcher

Located at the repository root, run_api.py serves as the CLI wrapper that bootstraps the Uvicorn server. The script first inserts the repository root into sys.path to ensure module resolution, then reads environment variables including API_HOST, API_PORT, and API_RELOAD.

It invokes the ASGI server with:

uvicorn.run("api.main:app", host=host, port=port, reload=reload)

The api/main.py Application Factory

The actual FastAPI instance is constructed in api/main.py. This file creates the application object, registers CORS middleware and password-authentication middleware, and includes all API routers (e.g., /api/notebooks, /api/search, /api/chat). A lifespan context manager handles startup tasks, specifically running AsyncMigrationManager to execute database migrations before accepting traffic.

Frontend Entry Point (frontend/start-server.js)

The Next.js frontend is served by a standalone Node.js script generated during the build process.

Standalone Server Initialization

The file frontend/start-server.js constitutes the production entry point for the UI. During the Docker build, the frontend is compiled via npm run build, producing a standalone bundle in frontend/.next/standalone alongside static assets in frontend/.next/static.

The script sets process.env.PORT (defaulting to 8502) and invokes the compiled Next.js server:

// Simplified logic from start-server.js
const server = require('./.next/standalone/server.js');
const port = process.env.PORT || 8502;
server.listen(port);

Docker Orchestration Entry Point

When deploying via Docker, a single process manages both components.

Supervisord Configuration

The Dockerfile defines supervisord as the container's primary command:

CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

The supervisord.conf file (located in the repository root) defines two managed programs:

• api → executes python run_api.py
• frontend → executes node frontend/start-server.js

This exposes port 8502 for the frontend and port 5055 for the API.

Starting Components Locally

For development outside of Docker, you must launch each entry point separately.

Start the backend:

# Option 1: Using the wrapper script

python run_api.py

# Option 2: Direct Uvicorn with hot reload

API_RELOAD=true uvicorn api.main:app --host 0.0.0.0 --port 5055

Start the frontend:

cd frontend
npm ci
npm run build
node start-server.js

Summary

• run_api.py is the CLI entry point that configures Uvicorn and launches the FastAPI backend on port 5055.
• api/main.py contains the application factory that builds the FastAPI instance, registers middleware, and handles database migrations via a lifespan context.
• frontend/start-server.js serves as the production entry point for the Next.js frontend, binding to port 8502 by default.
• Docker supervisord orchestrates both entry points in production containers, exposing ports 5055 and 8502.

Frequently Asked Questions

How do I start the Open Notebook backend locally?

Execute python run_api.py from the repository root, or run uvicorn api.main:app --host 0.0.0.0 --port 5055 directly. The run_api.py script automatically configures the Python path and reads environment variables like API_HOST and API_RELOAD before starting Uvicorn.

What is the purpose of frontend/start-server.js?

This script serves as the production entry point for the Next.js frontend. It loads the compiled standalone application from frontend/.next/standalone and starts the HTTP server on the port defined by the PORT environment variable (defaulting to 8502).

Can I run the frontend and backend separately?

Yes. The architecture is designed to allow independent operation. You can run python run_api.py to start only the API, and node frontend/start-server.js to start only the UI. This is useful for development scenarios where you want to restart one component without affecting the other.

How does the Docker container start both services?

The container uses supervisord as its primary process. The supervisor configuration defines two programs: one that runs python run_api.py for the backend and another that runs node frontend/start-server.js for the frontend. This ensures both services start together and remain running within the single container.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}