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

> Discover the entry points for the Open Notebook application. Learn how FastAPI, Next.js, and Docker work together to run the backend, frontend, and orchestrate the process.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: architecture
- Published: 2026-06-26

---

**Open Notebook uses three distinct entry points: [`run_api.py`](https://github.com/lfnovo/open-notebook/blob/main/run_api.py) for the FastAPI backend, [`frontend/start-server.js`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/run_api.py) and [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py))

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

### The [`run_api.py`](https://github.com/lfnovo/open-notebook/blob/main/run_api.py) Launcher

Located at the repository root, [`run_api.py`](https://github.com/lfnovo/open-notebook/blob/main/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:

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

```

### The [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) Application Factory

The actual FastAPI instance is constructed in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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:

```javascript
// 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:

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

```

The [`supervisord.conf`](https://github.com/lfnovo/open-notebook/blob/main/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:

```bash

# 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:

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

```

## Summary

- **[`run_api.py`](https://github.com/lfnovo/open-notebook/blob/main/run_api.py)** is the CLI entry point that configures Uvicorn and launches the FastAPI backend on port 5055.
- **[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.