Skip to main content

Prerequisites

  • Node.js 20+ on the hub machine
  • Raspberry Pi 4/5 (recommended) or any ARM64/AMD64 Linux machine
  • Network: Hub and terminals must be on the same LAN
  • Odoo: Accessible from the hub (for token validation and event forwarding)

Option 1: Bare-metal install (systemd)

Best for dedicated Raspberry Pi deployments.
1

Copy the source to the hub machine

2

Run the installer (as root)

The installer:
  • Checks Node.js 20+
  • Creates a pos-hub system user
  • Creates /var/lib/pos-hub/ data directory
  • Builds the protocol and hub packages
  • Installs Litestream for backups (checksum-verified; a failed download is a warning, not an error)
  • Creates /etc/pos-hub/env with default config (never overwrites an existing one)
  • Installs and starts a systemd service that runs the hub through scripts/start-hub.sh
Backing up to a USB drive or mounted share (file://)? Pass the folder so the service is allowed to write there:
Upgrading an existing hub: run the installer again so the service picks up the new start command. Your /etc/pos-hub/env is kept — add LITESTREAM_REPLICA_URL to it by hand (see Backups).
3

Edit the configuration

Required changes:
Use a dedicated Odoo user for the hub, not admin. The hub refuses to start while ODOO_USER or ODOO_PASSWORD is empty, or the password is admin, and while FISCAL_PLUGIN is not dr-ncf or none. It exits with code 78 and says why in journalctl -u pos-hub.
4

Restart the service

Service management

Security hardening

The systemd unit includes:
  • NoNewPrivileges=true
  • ProtectSystem=strict (read-only root filesystem)
  • ReadWritePaths=/var/lib/pos-hub (only writable path)
  • ProtectHome=true, PrivateTmp=true
  • Runs as dedicated pos-hub user (no shell, no home)

Option 2: Docker

Best for testing or multi-service deployments.

Build

From the repository root (not nu_pos_hub/):
Supports both ARM64 (Raspberry Pi) and AMD64 (x86 servers).

Run

Leave out the LITESTREAM_REPLICA_URL and AWS_* lines to run without backups. The image includes Litestream; see Backups.

Docker Compose

The Docker image includes a built-in health check (30s interval, 5s timeout, 3 retries).

CLI tool

events and reset-leases read protected endpoints. Set HUB_TOKEN to a POS access token for them: HUB_TOKEN=<token> pos-hub events. stats and drain read the public /health. During development:

Example output: pos-hub stats

Hub dashboard

Access at http://<hub-ip>:8766/ — a self-contained HTML page with:
  • Stats grid: Connected terminals, active leases, total orders, pending/forwarded events
  • Terminals table: ID, device, role, last seen
  • Leases table: Order reference, terminal, role, expiry
  • Event log: Last 50 events with type, reference, status, timestamp
  • Reset All Data button: Clears all SQLite data with confirmation
Auto-refreshes every 3 seconds. No external dependencies (all CSS/JS inline). Sign-in. The page and GET /health are public. Every other endpoint needs a POS access token:
  • any POS user’s token for reading orders, tables, events and alerts;
  • a manager’s token for admin actions (revert, reforward, lock release, webhook).
On the hub machine itself (http://localhost:8766/), reads need no token. Turn this off with HUB_LOOPBACK_READS=false if a reverse proxy on the same machine forwards LAN traffic, because every proxied request would look local. From other devices, the dashboard asks for a token on the first refusal and keeps it in the browser. The hub remembers a token that passed for 60 seconds, so polling doesn’t call Odoo on every refresh.

mDNS discovery

When HUB_MDNS_ENABLED=true (default), the hub advertises itself on the local network:
  • Service type: _pos-hub._tcp
  • Name: “POS Hub”
  • Port: value of HUB_HTTP_PORT
mDNS doesn’t work well in Docker. Disable it with HUB_MDNS_ENABLED=false for container deployments.

Enabling hub mode in Odoo

These values are included in the bootstrap payload and read by createTransport() on the frontend.

Data persistence

Backups

Set LITESTREAM_REPLICA_URL (in /etc/pos-hub/env, or -e for Docker) to stream the hub’s database to S3, an S3-compatible store, a USB drive (file://, install with POS_HUB_BACKUP_DIR) or another machine (sftp://). A replaced disk is restored automatically on the next start. Confirm with curl http://hub:8766/health → "backup": {"mode": "litestream"}. Details: nu_pos_hub/README.md → “Backups”.

Monitoring checklist