// docs / install

Install

Three shapes. Pick the one that matches your environment. All three end the same way: a manager running on port 4071 behind nginx, EMQX on 1883/8883, and Postgres holding state.

Prerequisites

• A domain you control. Openflow uses wildcard subdomains for each instance, so you need an A or ALIAS record for both example.com and *.example.com.
• A wildcard TLS certificate. The Docker Compose deploy includes a Let's Encrypt DNS-01 helper; bring your own DNS API token. The Helm chart expects cert-manager.
• Linux host with Docker 24+ for single-host shapes. Kubernetes 1.28+ for the cluster shape.
• Postgres 14+. The Docker Compose includes one; the Helm chart expects an external one.

Docker Compose, single host

The reference deploy. One box, Docker, the manager, Postgres, EMQX, nginx, everything in compose.yml.

$ git clone https://github.com/skaag/openflow
$ cd openflow
$ cp .env.example .env

Edit .env. The minimum keys:

# public apex domain, no scheme
ROOT_DOMAIN=example.com

# the manager builds instance URLs as `subdomain.${MANAGER_URL hostname}`
MANAGER_URL=https://example.com

# 64-byte random strings, no quotes
SESSION_SECRET=…
JWT_SECRET=…

# optional: enables the in-editor AI assistant
ANTHROPIC_API_KEY=…

Then bring everything up:

$ docker compose up -d
$ docker compose logs -f manager
# wait for: "Openflow manager listening on :4071"

Open https://example.com. The first account you create becomes the platform admin. Create a project, create an instance, click Launch.

One-line installer (fresh host)

For a brand-new Ubuntu 22.04+ box with nothing on it. Installs Docker, Postgres, nginx, certbot, the manager, and bootstraps the compose stack above.

$ curl -L openflow.ing/install | sh
# interactively asks for:
#   ROOT_DOMAIN
#   admin email (for Let's Encrypt + first account)
#   DNS provider for DNS-01 cert challenge
# brings the manager up on :443

The script is committed in the repo as install.sh, vendored without obfuscation. Read it before running if you want.

Kubernetes (Helm)

For multi-node clusters. Expects an external Postgres, cert-manager for TLS, and either an ALB ingress (AWS) or nginx-ingress.

$ helm repo add openflow https://openflow.ing/charts
$ helm repo update
$ helm install openflow openflow/openflow \
        --namespace openflow --create-namespace \
        -f values.yaml

Minimum values.yaml:

rootDomain: example.com
managerUrl: https://example.com

postgres:
  external: true
  url: postgres://openflow:****@db.svc.cluster.local:5432/openflow

emqx:
  enabled: true

ingress:
  className: alb
  certificate: arn:aws:acm:us-west-1:…:certificate/…

The chart provisions a manager Deployment, an EMQX StatefulSet, and one Deployment per existing instance. New instances spin up new Deployments on demand. Instance containers run with the same image and resource model as the single-host deploy.

First boot

Once the manager answers on https://<root>/healthz:

• Visit https://<root>/ in a browser. Create the first user. That user becomes the platform admin automatically.
• Create a project. Projects own instances; access is granted via project membership.
• Create an instance. Pick a template (Node-RED 3.x or 4.x). Click Start.
• Click Launch. The instance opens authenticated. The first time it boots, the entrypoint installs any palette modules you configured, then starts Node-RED on 1880.

That is the whole install. Next: architecture.