Skip to content
Klutch.sh Docs

Deploying a Node-red App

Introduction

Node-RED is an open-source flow-based development tool built on Node.js for wiring APIs, devices, and services. Deploying Node-RED with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for flows and credentials—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Node-RED Dockerfile (GitHub is the only supported git source)
  • Optional credentials for external services you wire into your flows

For onboarding, see the Quick Start.

Architecture and ports

  • Node-RED serves HTTP on internal port 1880; choose HTTP traffic.
  • Persistent storage is required for flows, settings, and credentials.

Repository layout

node-red/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t node-red-local .
docker run -p 1880:1880 node-red-local

Dockerfile for Node-RED (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM nodered/node-red:3.1


ENV PORT=1880


EXPOSE 1880
CMD ["npm", "start", "--", "--userDir", "/data"]

Notes:

  • Pin the image tag (e.g., 3.1.x) for stability; update intentionally.
  • Add extra nodes or custom packages by extending the image and running npm install for your dependencies.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=1880
  • Optional security: NODE_RED_USERNAME, NODE_RED_PASSWORD (configure in settings.js), or use NODE_RED_CREDENTIAL_SECRET for encrypted credentials.
  • Optional external service keys used by your flows.

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=npm install
  • NIXPACKS_START_CMD=npm start -- --userDir /data
  • NIXPACKS_NODE_VERSION=18

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /data — flows.json, creds, and installed nodes.

Ensure this path is writable inside the container.

Deploy Node-RED on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 1880.
  4. Add the environment variables above, including any credential secrets and service keys.
  5. Attach a persistent volume for /data sized for your flows and installed nodes.
  6. Deploy. Access Node-RED at https://example-app.klutch.sh and start building flows.

Sample API usage

Hit the admin API (read-only example):

Terminal window
curl -X GET "https://example-app.klutch.sh/flows" \
  -H "Node-RED-API-Version: v2"

Import a flow (requires admin auth if enabled):

Terminal window
curl -X POST "https://example-app.klutch.sh/flows" \
  -H "Content-Type: application/json" \
  -d '{"flows":[{"id":"1","type":"tab","label":"Demo"}]}'

Health checks and production tips

  • Add an HTTP probe to / or /healthz if you expose one.
  • Enforce HTTPS at the edge; forward internally to port 1880.
  • Secure the editor with user/password or an auth strategy; keep credential secrets in Klutch.sh.
  • Monitor /data usage; resize before it fills.
  • Pin image versions and test upgrades in staging; back up /data before updates.

Node-RED on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 1880 configured, and flows persisted, you can deliver reliable automation without extra YAML or workflow overhead.