How to Self-Host Node-RED with Docker Compose

What Is Node-RED?

Node-RED is a flow-based programming tool for wiring together hardware devices, APIs, and online services. Built on Node.js, it provides a browser-based editor for creating automation flows by dragging and connecting nodes. Originally created by IBM for IoT prototyping, it’s become a general-purpose automation platform. If n8n is the self-hosted Zapier, Node-RED is the self-hosted visual programming environment — more flexible, more technical, and deeply integrated with the IoT ecosystem.

Updated March 2026: Verified with latest Docker images and configurations.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
512 MB of free RAM
1 GB of free disk space
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  node-red:
    image: nodered/node-red:4.1.7
    container_name: node-red
    restart: unless-stopped
    ports:
      - "1880:1880"
    environment:
      TZ: "UTC"                                # Set to your timezone
      # NODE_RED_CREDENTIAL_SECRET: "change_this_secret"  # Uncomment to encrypt credentials at rest
    volumes:
      - node-red_data:/data
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:1880/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  node-red_data:

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server-ip:1880 in your browser
The flow editor opens immediately — no login required by default
Enable authentication immediately (see Configuration below) — the editor allows arbitrary code execution
Test with a simple flow: drag an “inject” node and a “debug” node, connect them, click Deploy

Configuration

Securing with Authentication

Node-RED has no authentication by default. This is dangerous — anyone with access can execute arbitrary JavaScript on your server.

Create a password hash:

docker compose exec node-red node -e "console.log(require('bcryptjs').hashSync('your_password', 8))"

Then mount a custom settings.js file. Create settings.js alongside your docker-compose.yml:

module.exports = {
    flowFile: 'flows.json',
    credentialSecret: "change_this_to_a_random_string",
    adminAuth: {
        type: "credentials",
        users: [{
            username: "admin",
            password: "$2a$08$HASH_FROM_ABOVE",  // Replace with bcrypt hash
            permissions: "*"
        }]
    },
    uiPort: process.env.PORT || 1880,
    diagnostics: {
        enabled: true,
        ui: true
    },
    logging: {
        console: {
            level: "info",
            metrics: false,
            audit: false
        }
    }
};

Update Docker Compose to mount it:

volumes:
  - node-red_data:/data
  - ./settings.js:/data/settings.js:ro

Installing Additional Nodes

Node-RED has a library of 5,000+ community nodes. Install from the editor:

Click the hamburger menu (top-right) → Manage palette
Go to the Install tab
Search for nodes (e.g., node-red-contrib-home-assistant-websocket)
Click Install

Or install via the command line:

docker compose exec node-red npm install node-red-contrib-home-assistant-websocket
docker compose restart node-red

Environment Variables

Variable	Description	Default
`TZ`	Timezone	`UTC`
`NODE_RED_CREDENTIAL_SECRET`	Encryption key for stored credentials	(none)
`NODE_RED_ENABLE_PROJECTS`	Enable git-based project management	`false`
`NODE_OPTIONS`	Node.js runtime flags	(none)

Advanced Configuration (Optional)

Projects Feature

Enable git-based version control for flows:

environment:
  NODE_RED_ENABLE_PROJECTS: "true"

This adds a Projects tab in the editor where you can initialize a git repo, commit flow changes, and push/pull from remotes.

Home Assistant Integration

Node-RED is one of the most popular Home Assistant automation tools:

Install node-red-contrib-home-assistant-websocket via the palette manager
Add a Home Assistant server node with your HA URL and a long-lived access token
Use HA event nodes, service call nodes, and entity nodes to build automations

Dashboard UI

Create web dashboards from your flows:

docker compose exec node-red npm install node-red-dashboard
docker compose restart node-red

Access the dashboard at http://your-server-ip:1880/ui.

Running with Lower Privileges

By default, the Node-RED container runs as the node-red user (UID 1000). If you need to match a specific host UID:

environment:
  PUID: "1000"
  PGID: "1000"

Reverse Proxy

Nginx Proxy Manager config:

Scheme: http
Forward Hostname: node-red
Forward Port: 1880
Websockets Support: Enable (required for the editor)

See Reverse Proxy Setup for full configuration.

Backup

# Back up all flows, credentials, and installed nodes
docker run --rm -v node-red_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/node-red-backup-$(date +%Y%m%d).tar.gz /data

Key files in the data volume:

flows.json — your automation flows
flows_cred.json — encrypted credentials
settings.js — configuration
node_modules/ — installed community nodes
package.json — node dependency list

See Backup Strategy for a complete backup approach.

Troubleshooting

Flows Not Deploying

Symptom: Click Deploy but nothing happens, or flows show errors. Fix: Check the debug sidebar (bug icon) for error messages. Common cause: a node has missing credentials or a required community node isn’t installed. Check logs:

docker compose logs node-red

Community Nodes Not Loading After Restart

Symptom: Nodes show as “unknown” after container restart. Fix: Ensure the data volume is persistent. If nodes were installed inside the container without a volume mount, they’re lost on restart. Reinstall via the palette manager or add them to a package.json in the data volume.

Cannot Access Editor Remotely

Symptom: Editor loads locally but not from other machines. Fix: Check that port 1880 is open in your firewall. If using a reverse proxy, ensure WebSocket support is enabled — the editor requires WebSocket connections.

High Memory Usage

Symptom: Node-RED consuming excessive RAM. Fix: Large flows with many nodes can consume significant memory. Set a memory limit:

environment:
  NODE_OPTIONS: "--max-old-space-size=512"

Credential Decryption Errors

Symptom: “Error loading credentials” after restoring from backup. Fix: The credentialSecret in settings.js (or NODE_RED_CREDENTIAL_SECRET env var) must match the value used when credentials were originally encrypted. If you lost the secret, you’ll need to re-enter credentials for all nodes.

Resource Requirements

RAM: ~100 MB idle, ~200-500 MB with complex flows and many nodes
CPU: Low — event-driven, minimal processing between triggers
Disk: ~300 MB for the application, plus storage for installed nodes and flow data

Verdict

Node-RED is the most flexible self-hosted automation tool. It’s more powerful than n8n for IoT and hardware integration, but has a steeper learning curve. The visual flow editor is excellent once you learn it, and the 5,000+ community nodes cover almost any integration you can imagine. For pure API-to-API automation (Zapier-style), n8n is more approachable. For IoT, Home Assistant integration, or anything involving MQTT, serial devices, or custom protocols, Node-RED is the right tool.

Frequently Asked Questions

Can Node-RED replace n8n or Zapier?

Node-RED overlaps with n8n for API-to-API automation, but they target different users. n8n is closer to Zapier — drag-and-drop connectors for SaaS services with a polished UI. Node-RED is a visual programming environment — more flexible but more technical. If you’re wiring IoT devices, MQTT brokers, serial ports, or custom protocols, Node-RED is the right tool. For connecting Slack to Google Sheets, n8n is more approachable.

Is Node-RED secure enough for production use?

Node-RED has no authentication by default — the flow editor allows arbitrary JavaScript execution on your server. You must enable adminAuth in settings.js before exposing it to any network. With authentication enabled, HTTPS via a reverse proxy, and proper firewall rules, Node-RED is production-ready. Many enterprises use it in industrial automation environments.

How do I persist installed nodes across container restarts?

Mount the /data directory as a persistent volume (as shown in the Docker Compose above). Community nodes installed via the palette manager are stored in /data/node_modules/. Without a persistent volume, all installed nodes are lost when the container restarts.

Can Node-RED connect to Home Assistant?

Yes — it’s one of the most popular Home Assistant automation tools. Install the node-red-contrib-home-assistant-websocket palette via the editor or CLI. This provides event listener, service call, and entity state nodes. Many users prefer Node-RED for complex automations that are difficult to express in Home Assistant’s YAML or UI-based automations.

How much RAM does Node-RED need?

Node-RED itself uses ~100 MB idle. Complex flows with many nodes can push this to 200-500 MB. The main memory factor is installed community nodes and concurrent flow executions. You can cap memory with NODE_OPTIONS="--max-old-space-size=512". A Raspberry Pi with 1 GB RAM runs Node-RED comfortably for typical home automation use cases.

Can I version control my flows?

Yes. Enable the Projects feature with NODE_RED_ENABLE_PROJECTS=true. This adds a git-based version control UI in the editor — initialize a repository, commit flow changes, and push/pull from remote Git repos. Alternatively, export flows manually as JSON from the editor menu and commit them to your own repository.