octobot-node 0.0.1

OctoBot Node

OctoBot Node

Run any OctoBot, anywhere, with ease

This project is related to OctoBot.

Usage

CLI

OctoBot-Node provides a command-line interface (CLI) for starting the server and managing the application.

Basic Usage

Start the server with default settings:

python start.py

Or if installed via pip:

octobot_node

CLI Options

• -v, --version: Show OctoBot-Node current version
• --host HOST: Host to bind the server to (default: 0.0.0.0)
• --port PORT: Port to bind the server to (default: 8000)
• --workers WORKERS: Number of worker processes (default: 1)
• --reload: Enable auto-reload for development (only works with single worker)

Examples

Start the server on a custom host and port:

python start.py --host 127.0.0.1 --port 9000

Start with multiple workers for production:

python start.py --workers 4

Start in development mode with auto-reload:

python start.py --reload

Show version:

python start.py --version

With Redis

For using Redis as the scheduler backend:

docker run -p 6379:6379 --name redis -d redis redis-server --save 60 1 --loglevel warning

Developers

Prerequisites

Before proceeding, ensure you have Python 3.10+ and Node.js 20+ installed on your system.

Once you have installed Python and Node.js, run the following commands:

npm install
pip install -r requirements.txt
cp .env.sample .env

Web UI

The Web UI can be used in two modes: static and dynamic (development). The Web UI is built using React, Vite, TanStack and shadcn-ui.

Static Web UI

If you do not need to modify the Web UI code, it is recommended to use the static mode for better performance. To build the static assets, run:

npm run build

After building, start the FastAPI server. The static Web UI will be available at http://localhost:8000/app.

Dynamic (Development) Web UI

If you plan to actively develop or modify the Web UI, use the dynamic development mode. This provides hot-reload and the latest changes instantly. To run the Web UI in development mode, use:

npm run ui:dev

This will start the development server, typically available at http://localhost:3000. You can access the UI separately while developing. For API integration during development, make sure your FastAPI backend server is running simultaneously. The development server will proxy API requests to the backend as configured.

OpenAPI

Whenever you update or add routes in octobot_node/app/api, you need to regenerate the OpenAPI specification and the UI OpenAPI client. This can be done easily with the provided script:

bash ./generate-client.sh

API Server

The API server is built using FastAPI and provides the backend REST endpoints and websocket interface for OctoBot Node.

Running the FastAPI Server

You can start the API server using the CLI (recommended):

python start.py --workers 1

Or directly with uvicorn:

uvicorn octobot_node.app.main:app --host 0.0.0.0 --port 8000 --workers 1

• By default, the server runs on http://localhost:8000.
• You can configure environment variables via .env, including host, port, and scheduler/backend settings.
• For development: Use --reload flag or fewer workers (e.g. --workers 1), so that code changes are picked up more easily.
• For production: Increase the number of workers using --workers option.

Environment Variables

Some key .env variables:

• SCHEDULER_BACKEND (redis, sqlite, etc.)
• SCHEDULER_REDIS_URL (if using Redis)
• SCHEDULER_SQLITE_FILE (if using SQLite)
• SCHEDULER_NODE_TYPE ("master" or "worker")
• SCHEDULER_WORKERS (number of consumer workers)

See .env.sample for all options, and adjust as needed.

Scheduler

The task scheduler is automatically started together with the FastAPI server through import of the octobot_node/app/scheduler module. The scheduler uses Huey for task queue management.

• No manual launch needed — scheduler and consumers are managed by the FastAPI app on startup.
• Configuration for the scheduler backend (Redis or SQLite) is picked up from environment variables.
• When SCHEDULER_NODE_TYPE=worker, background consumers process tasks automatically. When set to master, consumer threads are skipped by design.