How to Install Node-RED with Docker Compose: Complete Setup

Node-RED is a visual programming environment for wiring together APIs, hardware, and services with minimal code. If you’ve spent time building automation in Home Assistant or writing webhooks, Node-RED solves the same problem differently—by letting you drag nodes onto a canvas and connect them. This guide walks through installing it via Docker Compose, configuring it properly, and connecting it to services like Ollama or OpenAI for intelligent automation.

Why Install Node-RED in Your Homelab

Node-RED excels at gluing things together. A sensor triggers, you process the data, maybe send it to an LLM for analysis, then act on the result. The visual interface means you can iterate fast without rewriting scripts. It’s also lightweight—runs fine on a Raspberry Pi 4 or an old x86 box with 512MB RAM allocated.

The real value appears once you start chaining services. Ingest data from Home Assistant, enriche it with an AI model running on Ollama, store results in InfluxDB, and trigger actions in Home Assistant again. All without touching a Python script or worrying about dependency hell.

That said, Node-RED has a learning curve if you’ve never done visual programming before. The mental model is sound but takes a couple of projects to internalize. And the Node-RED marketplace has quality issues—some community nodes are unmaintained or poorly documented.

Prerequisites and Hardware Requirements

You need Docker and Docker Compose installed. I’m assuming a Linux host; if you’re on Windows or macOS, WSL2 or Docker Desktop will work but add latency if you’re bridging to hardware sensors.

Hardware-wise, Node-RED is forgiving. I run production flows on a Raspberry Pi 4 with 2GB RAM. For a homelab with moderate complexity (under 30 active flows), allocate 512MB memory and 0.5 CPU cores. If you’re building something with heavy AI inference or many concurrent connections, bump it to 1GB and 1 CPU.

Required:

• Docker Engine 20.10+
• Docker Compose 1.29+
• A directory on your host for persistent storage (flows, credentials, node_modules)
• Network access to your homelab services (Home Assistant, MQTT broker, etc.)

Optional but recommended:

• A reverse proxy (Traefik, nginx) if you want to expose Node-RED outside your local network
• Ollama or similar running on your network if you want to use local LLMs
• MQTT broker for sensor data ingestion

Step 1: Create the Directory Structure

Set up a home directory for Node-RED that persists across container restarts.

mkdir -p ~/homelab/node-red/data
cd ~/homelab/node-red

This data directory will hold your flows.json, package.json (installed nodes), and credentials. By mounting it to the container, your configuration survives container updates.

Step 2: Create the Docker Compose File

Create docker-compose.yml in ~/homelab/node-red:

version: '3.8'
services:
  node-red:
    image: nodered/node-red:latest
    container_name: node-red
    restart: unless-stopped
    ports:
      - "1880:1880"
    environment:
      - TZ=UTC
      - NODE_RED_ENABLE_PROJECTS=false
    volumes:
      - ./data:/data
    networks:
      - homelab
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1880/"]
      interval: 30s
      timeout: 5s
      retries: 3

networks:
  homelab:
    driver: bridge

A few notes: Port 1880 is Node-RED’s default. The TZ environment variable sets timezone—change it if you’re not in UTC. NODE_RED_ENABLE_PROJECTS=false keeps things simple for a first install; you can enable it later if you want version control for flows. The healthcheck helps Docker Compose detect if the service dies.

If your homelab runs on a shared Docker network, replace the entire networks section with:

networks:
  homelab:
    external: true

This connects Node-RED to an existing network so it can reach your other services by container name (e.g., http://ollama:11434).

Step 3: Start the Container and Initial Setup

Launch it:

docker-compose up -d

Check the logs to confirm it started cleanly:

docker-compose logs -f node-red

You’ll see something like:

node-red_1  | 15 Jan 12:34:56 - [info] Server now running at http://127.0.0.1:1880/
node-red_1  | 15 Jan 12:34:56 - [info] Settings file  : /data/settings.js
node-red_1  | 15 Jan 12:34:56 - [info] User directory : /data

Open your browser to http://localhost:1880. You’ll see the Node-RED editor—a blank canvas on the left, a palette of nodes on the right, and a sidebar for debugging and configuration.

Step 4: First-Run Configuration and Security

Node-RED ships with no authentication by default. Before exposing it to the network, add a password. Edit the settings file inside the container, or mount a custom one.

The easier approach: Generate a password hash and add it directly. Install bcryptjs locally (or use an online tool carefully) and generate a hash. Then edit data/settings.js to include:

adminAuth: {
    type: "credentials",
    users: [{
        username: "admin",
        password: "$2b$08$...", // bcrypt hash of your password
        permissions: "*"
    }]
},

To generate a hash, run this on your host machine (assuming Node.js is installed):

node -e "console.log(require('bcryptjs').hashSync('your-password', 8))"

Copy the output into settings.js, then restart the container:

docker-compose restart node-red

You’ll now be prompted to log in when accessing the editor. This isn’t bulletproof if Node-RED is exposed to the internet without HTTPS, but it prevents casual access from inside your network.

For internet-facing deployments, use a reverse proxy with TLS termination (Traefik with Let’s Encrypt, or nginx with a cert).

Step 5: Installing Community Nodes for AI Automation

The power of Node-RED emerges when you add nodes for your services. To add Ollama or OpenAI support, use the Manage Palette option in the editor. Click the hamburger menu (top right), select “Manage palette,” then search for the nodes you need.

For Ollama integration, install node-red-contrib-ollama. For OpenAI, install node-red-contrib-openai-api. For MQTT (common in homelab sensor networks), search for mqtt and install the core MQTT nodes.

Alternatively, install nodes by editing data/package.json directly. Add the package name to the dependencies:

{
  "dependencies": {
    "node-red-contrib-ollama": "1.0.5",
    "node-red-contrib-openai-api": "0.2.1"
  }
}

Then restart the container. Docker will rebuild the image and npm will fetch the packages. This takes a minute or two.

After installation, new nodes appear in the palette and you can drag them into your flow. Each node has a config panel where you set API keys, model names, or connection details.

Common Installation and Runtime Gotchas

Flows won’t persist after container restart: This happens if you forget to mount the data volume. Double-check your docker-compose.yml has ./data:/data in the volumes section. If you’ve already lost flows, they’re stored in data/flows.json—check if the file exists on your host before rebuilding.

Node-RED can’t reach other services: If you’re trying to connect to Ollama or Home Assistant and getting connection timeouts, verify they’re on the same Docker network. Use the full container name as the hostname (e.g., ollama:11434, not localhost:11434). If they’re on different networks, you need a shared external network or expose ports on your host.

Memory usage creeps up over time: Node-RED can leak memory if you have debug nodes enabled and they’re logging heavily. Disable debug nodes in production flows, or route them to a file output instead of the debug panel. Also check if you have infinite loops in your flows (node outputting to itself)—they’ll consume CPU and memory quickly.

Installed nodes don’t appear after restart: If you edited package.json manually but the container didn’t rebuild, run docker-compose up -d --build or clear the image and pull fresh.

Settings file keeps reverting: The default settings.js is read-only inside the container. If you want custom settings to stick, mount your own settings.js file into the container instead of relying on the default. Create a settings.js on your host, then add to docker-compose.yml:

volumes:
  - ./data:/data
  - ./settings.js:/data/settings.js

What to Do Next: Building Your First Flow

Start simple. Create a flow that triggers every 60 seconds, fetches a timestamp, and logs it. Drag an inject node onto the canvas, set it to repeat every minute, connect it to a function node that returns a timestamp, then connect that to a debug node. Deploy and watch the debug panel.

Once that works, try something with a real service. If you have Ollama running, add an Ollama node, feed it a fixed prompt, and see the response in the debug panel. Or connect to Home Assistant by adding an events node configured with your HA instance and API token, and trigger a flow when a sensor changes.

Node-RED’s strength is that you can see data flowing through your nodes in real time. Use the debug panel aggressively while building. And don’t worry if your first flow is messy—Node-RED encourages experimentation, and you can always refactor later.

The one thing I’d warn about: community nodes vary wildly in quality and maintenance. Before installing one, check the npm page—look at download trends, open issues, and last update date. An unmaintained node might break when Node-RED updates, and you won’t have a fallback. For critical flows, stick to the core nodes and well-maintained community packages.

FAQ

Can Node-RED run on a Raspberry Pi?

Yes, easily. Node-RED runs on Raspberry Pi 2 and later with as little as 512MB RAM. A Pi 4 with 2GB is ideal for moderate workloads. Install via Docker or download the native Node.js installer from nodered.org for even lower overhead.

How much RAM does Node-RED need?

Allocate 512MB minimum for a small homelab (under 10 flows). 1GB is comfortable for 30+ flows or flows with heavy processing. Monitor actual usage in docker stats—Node-RED typically uses 60–150MB at idle, rising under load.

Can I use Node-RED without Docker?

Yes. Node-RED is a Node.js application and can be installed globally via npm: npm install -g node-red. You’ll manage updates and dependencies manually, but it runs fine on bare metal. Docker is just cleaner for isolation and reproducibility.

What’s the difference between Node-RED and Home Assistant automations?

Home Assistant automations are trigger-condition-action rules, declarative and simple. Node-RED is visual programming with state, loops, and complex logic flow. Use Home Assistant for straightforward automations; Node-RED for multi-step workflows, data transformation, or bridging disparate systems.

Does Node-RED work with OpenAI or local LLMs?

Yes to both. Install node-red-contrib-openai-api for OpenAI, or node-red-contrib-ollama for Ollama. Configure your API key or Ollama endpoint in the node settings, then pass text through the node in your flow. The response comes out the output port and can be logged, stored, or used to trigger other nodes.

Explore Node-RED in our AI Homelab Toolkit.