How to Install Node-red on a VPS

If you’ve ever wished you could wire together APIs, databases, IoT sensors and web services without writing thousands of lines of glue code, Node-RED is exactly what you’ve been looking for. It’s a browser-based flow editor where you drag, drop and connect “nodes” to build automation pipelines in minutes. Think of it as a visual plumbing system for the internet of things and beyond.

Running Node-RED on your own VPS gives you something the managed SaaS alternatives can’t: full ownership. Your flows run 24/7, your credentials never leave your server and you’re not capped by usage limits. This guide walks you through a production-ready installation using Docker, Nginx as a reverse proxy and Let’s Encrypt SSL. By the end you’ll have a secured, publicly accessible Node-RED instance you can actually rely on.

What Is Node-RED?

Originally created by IBM and now a thriving open-source project under the OpenJS Foundation, Node-RED is a low-code programming environment built on Node.js. Its drag-and-drop interface lets you connect hardware devices, APIs and online services using a set of pre-built nodes. You can ingest MQTT messages from a temperature sensor, filter the data with a function node, push it to an InfluxDB database and send a Slack alert when a threshold is crossed. All without a single line of boilerplate setup code.

It’s enormously popular in IoT, home automation (especially Home Assistant integrations), data pipeline prototyping and webhook orchestration. The community has published over 4,000 additional nodes on npm covering everything from Twitter to Modbus to OpenAI. Whatever you’re trying to automate, there’s almost certainly a node for it.

Prerequisites

Before diving in, make sure your environment matches the baseline requirements. Node-RED itself is lightweight but you’ll want headroom for your flows to breathe.

You’ll also need a non-root sudo user and a domain name (or subdomain) with an A record already pointing to your VPS IP. Let’s Encrypt won’t issue a certificate until DNS resolves correctly so set that up first and give it a few minutes to propagate.

Step 1: Update Your Server

Fresh servers often ship with stale package indexes. Start clean.

sudo apt update && sudo apt upgrade -y

Reboot if the upgrade touched the kernel. One quick reboot now saves a lot of head-scratching later.

sudo reboot

Step 2: Install Docker Engine

Ubuntu’s default repositories include an older version of Docker that you don’t want. Pull it straight from Docker’s official repository instead.

First, install the packages needed to add a new apt source.

sudo apt install -y ca-certificates curl gnupg

Add Docker’s GPG key and configure the repository.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo /
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] /
  https://download.docker.com/linux/ubuntu /
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | /
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Now install Docker Engine and the Compose plugin.

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group so you don’t have to prefix every command with sudo.

sudo usermod -aG docker $USER
newgrp docker

Verify everything installed cleanly.

docker --version
docker compose version

Step 3: Create the Project Directory

Good directory hygiene matters. Keep everything Node-RED related in one place so upgrades and backups stay sane.

mkdir -p ~/node-red/{data}
cd ~/node-red

The data subdirectory will hold your flows, credentials and any custom nodes you install. Mounting it as a volume means your work survives container restarts and image upgrades.

Step 4: Write the Docker Compose File

Docker Compose lets you describe your entire service in a single file. Create it now.

nano ~/node-red/docker-compose.yml

Paste in the following configuration.

services:
  node-red:
    image: nodered/node-red:4
    container_name: node-red
    restart: unless-stopped
    environment:
      - TZ=UTC
    ports:
      - "127.0.0.1:1880:1880"
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1880/"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

A few design choices worth calling out here. The port binding 127.0.0.1:1880:1880 exposes Node-RED only on the loopback interface. That means it’s never reachable directly from the internet; all external traffic must come through Nginx. The restart: unless-stopped policy keeps Node-RED running after server reboots without launching it if you manually stop it for maintenance. And pinning to the nodered/node-red:4 major version tag gets you patch updates automatically without surprise major-version jumps.

If your server is in a different timezone, replace UTC with your local TZ identifier (e.g. America/New_York). Node-RED timestamps your flow execution logs so getting the timezone right saves confusion later.

Step 5: Set Correct Ownership on the Data Directory

The official Node-RED Docker image runs as UID 1000 internally. If the mounted data directory is owned by root, Node-RED can’t write its flow files and you’ll see cryptic permission errors on startup.

sudo chown -R 1000:1000 ~/node-red/data

Step 6: Start Node-RED

Launch the container in detached mode.

cd ~/node-red
docker compose up -d

Give it 20-30 seconds then check the container status.

docker compose ps

You should see the container listed as running (healthy) once the healthcheck passes. Tail the logs if anything looks off.

docker compose logs -f node-red

Look for the line Node-RED version: v4.x.x and Server now running at http://127.0.0.1:1880/. That confirms the application started correctly. Press Ctrl+C to exit the log tail.

Step 7: Install and Configure Nginx

Nginx handles the public-facing side: TLS termination, HTTP-to-HTTPS redirects and proxying requests to Node-RED’s local port.

sudo apt install -y nginx

Create a new server block for Node-RED. Replace nodered.yourdomain.com with your actual domain throughout.

sudo nano /etc/nginx/sites-available/node-red

Paste this configuration.

server {
    listen 80;
    server_name nodered.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:1880;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600;
    }
}

The Upgrade and Connection headers are non-negotiable for Node-RED. The editor relies on WebSockets to push live flow updates between your browser and the server. Without those two headers, the editor loads but changes don’t save properly, which is maddening to debug after the fact.

Enable the site and verify the Nginx configuration syntax.

sudo ln -s /etc/nginx/sites-available/node-red /etc/nginx/sites-enabled/
sudo nginx -t

If the test reports syntax is ok and test is successful, reload Nginx.

sudo systemctl reload nginx

Step 8: Obtain an SSL Certificate with Certbot

Nobody should be sending credentials over plain HTTP. Let’s Encrypt gives you a free, auto-renewing certificate in about 60 seconds.

sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d nodered.yourdomain.com

Follow the prompts: enter your email address for renewal notifications and agree to the terms of service. Certbot will automatically update your Nginx configuration to handle HTTPS and redirect port 80 traffic. After it completes, visit https://nodered.yourdomain.com in your browser. The Node-RED editor should load with a green padlock in the address bar.

Step 9: Enable Admin Authentication

Out of the box, Node-RED’s editor is wide open to anyone who reaches it. That’s fine on a localhost-only setup but not on a public server. You need to enable the built-in admin authentication before you do anything else with your new installation.

First, generate a bcrypt password hash. The Node-RED image includes the node-red-admin utility.

docker exec -it node-red node-red-admin hash-pw

Type your chosen password when prompted. The tool prints a hash that looks like $2b$08$.... Copy it.

Now edit the Node-RED settings file inside your data directory.

nano ~/node-red/data/settings.js

Find the adminAuth section (it’s commented out by default) and replace it with the following. Substitute your own username and the hash you just generated.

adminAuth: {
    type: "credentials",
    users: [{
        username: "admin",
        password: "$2b$08$YourGeneratedHashGoesHere",
        permissions: "*"
    }]
},

Save the file then restart the container to apply the change.

cd ~/node-red
docker compose restart

Refresh the editor in your browser. You should now see a login screen. Enter your credentials and you’re in.

Step 10: Open the Firewall

If you’re running UFW (Ubuntu’s default firewall), make sure ports 80 and 443 are open. Port 1880 should stay closed to the public.

sudo ufw allow 'Nginx Full'
sudo ufw status

The output should show Nginx Full with an ALLOW status. Port 1880 should not appear in the list.

Step 11: Install Additional Nodes

Node-RED’s real power comes from its ecosystem. You can install community nodes directly from the editor’s Palette Manager or via the terminal. The terminal method is more reliable for nodes with native dependencies.

To install a node package from the terminal, exec into the running container.

docker exec -it node-red bash

Once inside, use npm to install whatever you need. For example, the popular dashboard UI node:

cd /data
npm install @flowfuse/node-red-dashboard

Exit the container shell and restart Node-RED to load the new nodes.

exit
docker compose restart

Keeping Node-RED Updated

Updating Node-RED with Docker is refreshingly simple. Pull the latest image for your pinned major version then recreate the container. Your flows and data stay untouched because they live in the mounted volume.

cd ~/node-red
docker compose pull
docker compose up -d

Compose detects that the image changed and recreates the container automatically. The whole process takes under a minute. Check the logs afterward to confirm the new version started cleanly.

docker compose logs --tail=20 node-red

Before pulling any update, it’s worth checking the Node-RED release notes for breaking changes. Major version jumps occasionally require settings file adjustments.

Troubleshooting Common Issues

The Editor Loads but Changes Don’t Save

This almost always comes down to WebSocket headers. Check your Nginx config for the Upgrade and Connection proxy headers. If they’re missing or mistyped, the WebSocket connection fails silently and the editor appears to work until you try to deploy a flow. Re-verify with sudo nginx -t after any edit and reload.

Container Exits Immediately on Startup

Permission problems on the data directory are the most common culprit. Run docker compose logs node-red and look for EACCES: permission denied. If you see it, the fix is straightforward.

sudo chown -R 1000:1000 ~/node-red/data
docker compose up -d

Certbot Fails with “Could Not Resolve” Error

DNS propagation can take anywhere from seconds to 48 hours depending on your registrar. Certbot needs to reach your domain from the public internet before it issues a certificate. Use a tool like dig nodered.yourdomain.com or dnschecker.org to confirm the A record is resolving to your VPS IP before running Certbot again.

Node Installation Fails with npm Errors

Some community nodes require native build tools like gcc and python3. The official Node-RED image is slim and omits them. If you regularly install nodes with native dependencies, add a build step to your setup. Exec into the container and run:

apk add --no-cache python3 make g++

Note that the Node-RED image is Alpine-based so you use apk rather than apt for package management inside the container.

The Login Page Doesn’t Appear After Adding adminAuth

A syntax error in settings.js prevents Node-RED from loading the authentication configuration. JavaScript is unforgiving about missing commas and mismatched braces. Check the container logs for a parse error message. The line number in the error points directly to the problem. Fix the syntax issue, restart the container and the login prompt appears.

What to Build Next

With a secured Node-RED instance running, the real fun begins. Here are a few directions worth exploring.

• Home automation dashboard: Connect Node-RED to Home Assistant via the node-red-contrib-home-assistant-websocket package and build custom dashboards for your smart home devices.
• Webhook-to-Slack pipeline: Use the built-in HTTP input node to receive webhooks from GitHub, Stripe or any service and format them into Slack notifications with a function node.
• IoT data logging: Pair Node-RED with InfluxDB and Grafana. Ingest MQTT messages from sensors, store them in InfluxDB and visualize trends in Grafana. All three run beautifully on the same VPS.
• Scheduled data pulls: Use inject nodes as cron triggers to fetch data from REST APIs on a schedule, transform it and push it to a database or spreadsheet.
• Multi-user setup: The adminAuth configuration supports multiple users with granular permissions. Add read-only users for collaborators who can view flows but not modify them.

Node-RED has a way of starting small and expanding to cover more and more of your automation needs. What begins as a simple webhook forwarder often evolves into the connective tissue for an entire stack of services. Your VPS gives you the headroom to grow without hitting platform restrictions or per-flow pricing walls. Start wiring things together and see where it takes you.

SEO Metadata

Title: How to Install Node-RED on a VPS with Docker: A Complete Guide

Slug: how-to-install-node-red-on-a-vps

Meta Description: Learn how to install Node-RED on a VPS using Docker, Nginx and Let’s Encrypt. This step-by-step guide covers deployment, SSL, admin authentication and troubleshooting for a production-ready setup.

The post How to Install Node-red on a VPS appeared first on GreenGeeks.