// docs / instances

Instances

An instance is one Node-RED runtime: one Docker container, one subdomain, one /data volume, one set of resource limits. Everything you do day-to-day in Openflow happens to an instance.

Lifecycle

An instance is always in one of five states. The state machine is intentionally simple.

From the dashboard:

• Create inserts the row. Nothing is running yet. You pick a subdomain, a template, and resource limits.
• Start creates and starts the container. Pulls the template image if it isn't cached locally.
• Stop sends SIGTERM with a 10-second timeout, then SIGKILL.
• Restart is stop-then-start. Recreates the container, so config changes (env vars, aliases, palette) apply.
• Delete stops the container, removes it, deletes the row, deletes data/instances/<id>/. Permanent.

The same operations are available through the API at /api/instances/:id/{start,stop,delete}.

Templates

A template is a Docker image plus default resource bounds. Openflow ships two:

Both images are upstream Node-RED with three additions baked in:

• passport-custom for the magic-token authentication strategy.
• An Openflow-flavored settings.js that promotes the launch token to a long-lived cookie.
• The in-editor toolbar (/opt/openflow/toolbar.js, served via Node-RED's editorTheme.page).

Admins can register additional templates from the Admin tab. Any image that runs upstream Node-RED 3.x or 4.x and respects the same env-var contract will work.

Resource limits

Memory and CPU limits are per-instance, in the instance's settings. Defaults come from the template; overrides are bounded by the template's min/max. Limits are enforced by Docker (--memory and --cpus); a flow exceeding memory gets OOM-killed and the container restarts via the unless-stopped policy.

Palette modules

Extra npm packages that the entrypoint installs into /data before Node-RED starts. Configured per-instance as a list of npm specs:

node-red-contrib-postgresql@0.14.2
node-red-contrib-redis

The first start installs them, subsequent starts are a fast no-op once cached. Adding or removing a palette module requires a restart.

Env vars

Per-instance environment variables, set through the dashboard, are exposed to the flow like any other env var. The container also gets a set of platform-injected ones (prefixed OPENFLOW_) which you cannot shadow. See the configuration reference for the full list.

Subdomain aliases

An instance can answer to more than one URL slug. Useful for renames: the primary slug becomes analytics-v2, but legacy callers keep hitting analytics. Add the old slug as an alias from the Danger Zone tab.

Each alias becomes a Docker network alias on the same container (nodered-<alias>), so nginx's wildcard subdomain block resolves all of them to the same upstream without per-host configuration.

operational note Adding or removing an alias requires a restart, because Docker network aliases are pinned at container-create time. The UI says so on the response toast; the restartNeeded flag in the API response carries the same signal. A 502 from nginx after adding an alias means the restart hasn't happened yet.

Duplicate

From the Danger Zone tab. Pick a new subdomain, optionally a new project, optionally a new display name. The new instance:

• Gets a fresh magic token and a fresh MQTT username/password pair.
• Copies the source's /data directory verbatim, so flows, palette installs, and any node-state come along.
• Carries the source's credentialSecret, so its encrypted credentials decrypt.
• Starts stopped. Click Start when you're ready.

The original is untouched. Useful for promoting a working flow into a new environment, or for forking a sandbox before a risky change.