Node-RED on AWS User Guide

Overview

This image runs Node-RED, the open source, flow based, low-code programming tool for wiring together hardware devices, APIs and online services. Built on Node.js, Node-RED provides a browser based editor where you drag nodes from a palette onto a canvas and wire them into flows that react to events, transform messages and call out to services. It ships with a rich set of core nodes for HTTP, MQTT, TCP, WebSocket, file, function and dashboard work, and the built in palette manager lets you install thousands of community nodes from the public catalogue.

Node-RED 5.0.0 is installed globally on Node.js 22 LTS and runs as a dedicated unprivileged nodered system account under a systemd service that starts it on boot and restarts it on failure. The Node-RED user directory, which holds flows.json, the encrypted credentials store, settings.js and any installed extra nodes, lives at /var/lib/node-red, a dedicated, independently resizable EBS data volume that survives instance replacement.

Node-RED ships with no authentication by default, so the runtime binds to the loopback interface only (127.0.0.1:1880) and is never exposed directly. An nginx reverse proxy publishes the flow editor and the admin HTTP API on port 80 with WebSocket support for the live editor. Node-RED's own adminAuth gates the editor with a login page and a bcrypt hashed admin password. That password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/node-red-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the flow editor
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Node-RED. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the flow editor. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass; this is when the per instance admin password is generated.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Node-RED Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=node-red}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Password

The flow editor admin password is unique to your instance and was generated on first boot. Read the credentials file as root:

sudo cat /root/node-red-credentials.txt

The file lists the editor URL, the admin user (admin) and the generated password, along with an example of how to obtain an admin API bearer token. Keep this password somewhere safe.

Step 5: Sign In to the Flow Editor

The Node-RED flow editor is served on port 80 by nginx, which proxies to the runtime on 127.0.0.1:1880. In a browser, go to:

http://<instance-public-ip>/

You are presented with the Node-RED sign in page. Sign in as admin with the password from the credentials file. The flow editor canvas then loads, with the node palette on the left, the workspace in the centre and the information, help and debug sidebar on the right.

To build a flow, drag a node from the palette onto the canvas and wire its output port to the input of the next node. Double click a node to open its edit tray and configure it. The function node, for example, lets you write JavaScript to transform each message as it passes through.

Node-RED ships with a rich set of core nodes, and the palette manager lets you install thousands of community nodes from the public catalogue. Open it from the main menu in the top right with Manage palette, then use the Install tab to search for and add nodes.

When you have wired a flow, click Deploy in the top right to make it live. Flows are stored as JSON in flows.json in the user directory and can be exported, imported and version controlled.

Step 6: Confirm Node-RED Is Running

Over SSH, confirm the runtime and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active nodered nginx
sudo ss -tlnp | grep -E ':(80|1880) '

You should see both services reported as active, the Node-RED runtime listening on 127.0.0.1:1880 (loopback only), and nginx listening on port 80.

Step 7: Use the Admin HTTP API

Node-RED's admin HTTP API is served on the same port 80 behind the same login, so you can manage flows and the runtime programmatically. First obtain a bearer token by posting your credentials to /auth/token. On the instance you can do this over loopback; from outside, use the public IP. Replace <password> with the value from the credentials file:

curl -s http://127.0.0.1/auth/token \
  --data 'client_id=node-red-admin&grant_type=password&scope=*&username=admin&password=<password>'

A successful request returns a JSON object containing an access_token. Pass it as a bearer token on subsequent admin API calls, for example to retrieve the current flows:

curl -s http://127.0.0.1/flows -H 'Authorization: Bearer <access-token>'

The admin API can deploy flows, install nodes and inspect the runtime. See the Node-RED documentation for the full set of endpoints.

Step 8: The Data Volume

The Node-RED user directory lives on a dedicated EBS volume mounted at /var/lib/node-red. This keeps your flows, the encrypted credentials store, settings.js and any installed extra nodes off the operating system disk and lets you resize or snapshot them independently. Confirm the mount with:

df -h /var/lib/node-red

To grow the user directory, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Because the user directory holds all of your flows and configuration, snapshotting this volume captures the complete state of your Node-RED deployment.

Step 9: Enable HTTPS

The flow editor and admin API are served over plain HTTP on port 80 by nginx. For production use, place them behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:1880 exactly as the bundled site does for port 80, keeping the WebSocket upgrade headers in place so the live editor continues to work. Restrict the security group so ports 80 and 443 are reachable only from the networks that need the editor and the API.

Step 10: Backup and Maintenance

Back up your deployment by snapshotting the /var/lib/node-red EBS volume, which captures all of your flows, the encrypted credentials store and installed nodes. You can also export individual flows as JSON from the editor for version control. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; Node-RED and nginx start automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, flow design, node installation, the credentials store, dashboard configuration, MQTT and API integration, TLS and runtime tuning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.