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)
- Checks Node.js 20+
- Creates a
pos-hubsystem 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/envwith default config (never overwrites an existing one) - Installs and starts a systemd service that runs the hub through
scripts/start-hub.sh
file://)? Pass the folder so
the service is allowed to write there:/etc/pos-hub/env is kept — add
LITESTREAM_REPLICA_URL to it by hand (see Backups).3
Edit the configuration
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=trueProtectSystem=strict(read-only root filesystem)ReadWritePaths=/var/lib/pos-hub(only writable path)ProtectHome=true,PrivateTmp=true- Runs as dedicated
pos-hubuser (no shell, no home)
Option 2: Docker
Best for testing or multi-service deployments.Build
From the repository root (notnu_pos_hub/):
Run
LITESTREAM_REPLICA_URL and AWS_* lines to run without
backups. The image includes Litestream; see Backups.
Docker Compose
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 athttp://<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
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).
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
WhenHUB_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
SetLITESTREAM_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”.