// docs

Openflow documentation

Ten pages, grouped into four sections. Install covers the three shapes a deploy can take, architecture covers what runs where and why, and the rest covers the day-to-day.

What Openflow is

A self-hosted, multi-tenant Node-RED platform. One Docker container per instance, on its own subdomain, with isolated /data, isolated resource limits, and isolated MQTT namespacing. A single manager process (the Openflow backend, written in Fastify + TypeScript) supervises the lot, owns Postgres, and serves a small React UI.

The whole thing fits on a single host with Docker and a Postgres. Larger deploys move Postgres off-box and put an ALB or a Kubernetes ingress in front. The architecture doesn't change.

What Openflow is not

  • It is not a Node-RED fork. We host upstream Node-RED images, unmodified except for the authentication shim in settings.js and the Openflow toolbar that injects into editorTheme.page.
  • It is not a paid product with an open-source loss-leader. The repository is the whole project, Apache-2.0.
  • It is not a SaaS. No tenant runs in our infrastructure. There is no infrastructure but yours.

How the docs are organized

Four sections, ordered roughly by what you'll want to read first.

Getting started

  • install — the three real deploy shapes: Docker Compose on one host, the one-line installer for a fresh Ubuntu box, and the Helm chart for a Kubernetes cluster.
  • configuration — the .env file, every key that matters, what's manager-level vs per-instance, how to apply changes.

Using it

  • projects — the access model: projects own instances, members access projects, roles are deliberately few.
  • instances — lifecycle, templates, resource limits, palette modules, env vars, aliases, duplicating.
  • backups & snapshots — two distinct concepts, kept separate on purpose, with the restore procedures for each.
  • authentication — sign-in methods, passkeys, TOTP, the magic-token model for editor SSO, admin roles.

Integrations

  • mqtt — the EMQX broker, per-project mountpoint isolation, connecting external clients, ports and TLS.
  • ai assistant — the Claude-backed editor helper, what it can do, what data leaves the box, how to turn it off.

Reference

  • architecture — request flow end-to-end, magic-token in detail, MQTT mountpoint enforcement, snapshots vs backups.
  • troubleshooting — the foot-guns we've actually hit, written as symptom → cause → fix.

Reading order

If you are evaluating: skim architecture first to confirm the shape matches what you want. If it does, follow install with the smallest shape (single-host Docker Compose) to get a feel.

If you know you want to run it: go straight to install, then configuration. Architecture will make more sense after one instance is running.

If something has gone wrong: jump to troubleshooting. If your symptom isn't listed, open a discussion on the repo so we can add it.