Skip to content

Node-RED: Authentik, URLs, and IaC

Status: deployed 2026-08-04

This page records the River Oaks Node-RED authentication and URL migration. It is an operational reference for IT, not a replacement for the source configuration in the riveroaks/infra repository.

Current state

The active River Oaks Node-RED editors are protected by Authentik OIDC and are reachable through the internal-only *.nodered.riveroaks.cc namespace:

Instance Canonical editor URL Runtime
Studio https://studio.nodered.riveroaks.cc studio-nr VM
MPR https://mpr.nodered.riveroaks.cc mpr-nr VM
MDF https://mdf.nodered.riveroaks.cc mdf-nr VM
Telegram https://telegram.nodered.riveroaks.cc telegram-nr VM
DB https://db.nodered.riveroaks.cc rocc-db-local on rocc-db

The DB instance is part of this migration. Its browser/editor routes require Authentik, while /public/... remains available without a browser login for existing Portal, webhook, and automation callers.

The historical Archive instance has no active backend and was not restored or included as a live target.

Authentication and network policy

  • Authentik is the OIDC provider for every active editor.
  • Each Node-RED Authentik application is bound to the IT group. Users outside IT must not be admitted to the editor.
  • An admitted Authentik profile receives the Node-RED editor permissions configured in the corresponding settings.js.
  • The dedicated wildcard certificate covers *.nodered.riveroaks.cc.
  • Internal DNS points the canonical hosts to rocc-db (10.200.24.42).
  • Nginx allows only private network ranges (10/8, 172.16/12, and 192.168/16) for the canonical editor routes and denies other sources.

The editor is protected at /. The DB exception is deliberately limited to /public; do not remove that split without auditing Portal and automation callers first.

URL compatibility

The migration did not immediately remove old names because other services may still contain Node-RED URLs. The following compatibility aliases remain in place and were verified during the migration:

  • studio-nr.riveroaks.cc and edit-studio-nr.riveroaks.cc
  • mpr-nr.riveroaks.cc and edit-mpr-nr.riveroaks.cc
  • mdf-nr.riveroaks.cc and edit-mdf-nr.riveroaks.cc
  • telegram-nr.riveroaks.cc and edit-telegram-nr.riveroaks.cc
  • db-nr.riveroaks.cc

The old db.nodered.ro.church DNS name is also preserved for dependency cleanup. During the August migration its legacy external edge returned HTTP 403. An external probe on 2026-10-28 instead failed TLS hostname recognition, so that historical response is not a current health guarantee. It is not the canonical internal editor URL. Do not delete or repoint it until remaining callers have been identified.

The active Portal callers were changed to canonical .nodered.riveroaks.cc names in the riveroaks/portal repository. Home Assistant and any other external automation owners still need to be checked before compatibility aliases are retired.

Git and IaC source of truth

The riveroaks/infra repository owns the deployable Node-RED configuration:

Configuration Repository location
Flows, settings, packages nodered/instances/<instance>/
Deployment target and commands deploy/targets/nodered/
Authentik OIDC blueprints apps/authentik/blueprints/custom/*-nodered.yaml
Nginx virtual hosts nginx/hosts/rocc-db/sites-enabled/
Private-network access snippet nginx/hosts/rocc-db/snippets/nodered-internal.conf

Managed files include flows.json, settings.js, package.json, package-lock.json, the shared Authentik strategy, and the target's Authentik client configuration. Credentials, flows_cred.json, client secrets, environment files, installed modules, and other runtime secrets stay on the host and must not be committed.

Making a Node-RED change

  1. Treat the editor/host as a place to test or capture a change, not the permanent source of truth.
  2. Export or copy the resulting flow/configuration into the matching nodered/instances/<instance>/ directory. Remove credentials and secrets.
  3. Update the corresponding manifest or blueprint when the runtime or authentication behavior changes.
  4. Run the repository validation and target health checks.
  5. Open an MR, review it, and deploy from the merged branch.

An editor-side flow or settings.js change that is not captured in Git is runtime drift. A later IaC deployment can overwrite managed files, so record important editor changes before deploying anything else to that instance.

The DB target has an explicit DB_NODERED_MIGRATION deployment gate because its flows have more dependencies. It should be deployed and verified last when performing a fleet-wide change.

Verification and rollback

The 2026 migration was completed through:

  • IaC MR !56, merged as 7a149b3.
  • Portal MR !328, merged as 6001ce5.
  • Final merged-main IaC pipeline 6060: all validation, Nginx, DB deployment, and Node-RED verification jobs passed.
  • Portal pipeline 6054: tests and deployment passed.

Post-deployment checks confirmed:

  • All five canonical editors return the Authentik login page over valid TLS.
  • Legacy .riveroaks.cc aliases still respond.
  • Portal returns HTTP 200.
  • DB /public compatibility probes return the expected application response without redirecting to browser login.
  • All Node-RED health checks and PM2 processes are online.

The rollout was protected by Proxmox snapshots named nodered-pre-merge-20260804-182845 for VMIDs 100, 103, 104, 105, and 106. On rocc-db, root-only pre-merge archives were stored under:

/root/nginx-preswap-backups/merge-pre-20260804-182845/

The deployment mechanism also keeps per-release backups of managed files and Nginx pre-swap archives. Use those backups or the Proxmox snapshots for a rollback; do not restore flows_cred.json or other secrets from Git.

Remaining work

  1. Audit Home Assistant and other external automations for old DB and *.nodered.ro.church URLs.
  2. Keep compatibility aliases until those callers are migrated and observed using the canonical names.
  3. Decide whether the old db.nodered.ro.church edge should be retired or converted into an intentional internal compatibility route.
  4. Continue monitoring the wildcard certificate renewal and normal Proxmox backups.