How-to
Identify the Linux base before installing Node-RED natively
Short answer
Run cat /etc/os-release and uname -m on the running controller before copying anything. ID=debian opens a Debian package workflow; ID=ptxdist with PTXDIST_VERSION 2020.08.0 marks an embedded image where an ARMv7l Node.js tarball needs the hard-float libatomic1_13.2.0-4_armhf.deb staged by the image's own method. The product label never decides this.
On this page
- How do I tell which Linux base my controller is running?
- Does the product label or family name decide the base?
- What changes when /etc/os-release reports ID=ptxdist?
- Why does Node.js on ARMv7l fail without libatomic?
- How much flash space does a native install need?
- What checks prove the install before it runs unattended?
- When is Docker the better path than a native install?
- Questions asked
Run cat /etc/os-release and uname -m on the running controller before you copy anything to it. Those two lines decide the whole installation: an identity such as ID=debian puts a package workflow behind the image, while ID=ptxdist marks a built embedded image where Node.js arrives as an ARMv7l tarball and its libatomic dependency is staged by hand. Families mix bases: a reported edge computer runs Debian, while reported touch-panel and edge-controller images identify as PTXdist 2020.08.0, so the label on the housing never settles the question. This guide is the decision work — identifying the base and architecture first — that comes before any install command.
How do I tell which Linux base my controller is running? #
Run cat /etc/os-release for the base and uname -m for the architecture, on the target itself: ID=debian puts dpkg and apt behind the image, while ID=ptxdist identifies a built embedded image where you assume no package manager until the image documents one.
/etc/os-release is the file the system itself reads for its distribution identity; it needs nothing installed, which makes it the right first command on a minimal image. uname -r adds the kernel version — record it, but it does not decide the install path. If administration runs over SSH, change the root account's password from its initial value before you open that door.
- Open a shell on the running target — SSH or local console — and run
cat /etc/os-release; write downIDandVERSION_IDexactly as printed. - Run
uname -mand record the result:armv7lon the reported compact controllers,x86_64on most box PCs. - Run
uname -rand note the firmware image version alongside it, so the whole record stays tied to one image. - Only then probe the package manager, to confirm what
os-releasealready said: a version answer fromaptconfirms the Debian-style workflow; no answer on a PTXdist image confirms there is none.
Does the product label or family name decide the base? #
No — within one reported controller family the bases split: the edge computer reports a Debian distribution while touch-panel and edge-controller images report PTXDIST_VERSION="2020.08.0", so the running image, not the catalog name, is the only fact that picks the path.
The identity block reported from a touch-panel image reads:
NAME=PTXdist
VERSION="2020.08.0"
ID=ptxdist
VERSION_ID="2020.08.0"
PTXDIST_VERSION="2020.08.0"
PTXDIST_BSP_NAME=TP
PTXDIST_BSP_VERSION="TP-trunk"
PTXDIST_BUILD_DATE="2023-06-22T21:38:49+0000"
Build fields such as PTXDIST_BSP_NAME and PTXDIST_BUILD_DATE describe that one image; read the corresponding block from your own target instead of transferring these values to another controller. Debian and PTXdist are both Linux, and there the similarity ends: different repositories, different package handling, different filesystem layout, different update process. The split reaches down to the firmware — a documented native method for compact ARM controllers was written against firmware image 04.03.03(25) — so record the image version together with the base.
What changes when /etc/os-release reports ID=ptxdist? #
It removes the package-manager assumption: a PTXdist image is generated as a complete board-support image, so Node.js arrives as the ARMv7l tarball pattern node-vxx.xx.xx-linux-armv7l.tar.xz and every dependency is staged by the image's own maintenance method, never through an assumed apt install.
What /etc/os-release shows |
What you do about it |
|---|---|
ID=debian |
A dpkg and apt workflow stands behind the image; install through it |
ID=ptxdist |
Treat the image as built and fixed; place the runtime and libraries through the image's documented process |
On the Debian side, the steps that follow this decision are covered in Install Node-RED natively on a Linux edge computer. On the PTXdist side, note that the libatomic file the method stages carries a .deb filename: that proves the file's packaging format, not that dpkg lives on your target. Use the package handling the image documents, or place the library through the controller's approved image-maintenance process; treating PTXdist as Debian fails quietly later, when package registration and image maintenance diverge.
Native files also become your lifecycle problem. Record the image, base, architecture, runtime version and file locations so a firmware replacement, recovery or backup can account for them. That split between the image and what you add on top of it is the same reasoning behind Choosing an operating system image for an industrial PC.
Why does Node.js on ARMv7l fail without libatomic? #
Because 32-bit ARM does not offer every atomic width as a single instruction, compiled runtime code calls the remainder through libatomic.so.1; when that library is absent, the node binary exits with a load error before npm or Node-RED ever start.
The failure is documented across years of ARM boards: a Node.js package install that could not resolve libatomic.so.1, an nvm install of Node 12.18.4 on an ARM board that errored at first launch, and Node 26-era build images still tripping over a missing libatomic1. Atomic operations are indivisible memory updates — nothing exotic, just a helper library the runtime links.
The ARMv7l userspace on these targets is hard-float, so the matching build is the armhf package; libatomic1_13.2.0-4_armhf.deb is the documented example. npm ships inside the Node.js tarball, so it is not a separate operating-system package on this path. The pass test is one command: run the placed binary with its version flag from the environment that will launch Node-RED, and expect version output with no load error and no executable-format message. If it fails, fix the library — do not touch Node-RED.
How much flash space does a native install need? #
No target documents a minimum, so set the floor yourself: the measured extracted runtime plus the measured dependency tree must leave at least 30% of the partition free after installation, or you choose a different path.
The documented method's first instruction is to check the flash size before installing, and every number is measured on the target: df for free space, du -sh on the extracted tree. Measure again after creating the reserved directories, and keep three persistent locations separate — runtime, global npm content, Node-RED user data — so replacing a runtime never silently deletes flows or credentials.
Worked example with illustrative numbers; the method, not these values, is the specification. Suppose df reports 412 MB free on the reserved partition, the extracted node-v18.18.2-linux-armv7l.tar.xz tree measures 118 MB, and the Node-RED dependency tree measures 96 MB.
- Installed footprint: 118 MB + 96 MB = 214 MB
- Remaining: 412 MB - 214 MB = 198 MB
- Share still free: 198 / 412 ≈ 48%
- Floor at 30%: 412 x 0.30 ≈ 124 MB, and 198 MB clears it
This target passes, so the install proceeds. Numbers that left less than 124 MB free would point to a larger partition or the container path, not a squeezed install that writes the flash full.
What checks prove the install before it runs unattended? #
Five, in this order: version output from the exact runtime you placed, a clean interactive start, a deployed test flow, persistence across a controlled restart, and only then the automatic startup entry.
- From the environment that will launch Node-RED — not only your interactive shell — run the placed
nodeandnpmwith their version flags; both must print versions with no executable-format error and no missing-library message. - Install Node-RED with the npm that came inside that runtime, into the planned location, keeping runtime, global packages and user data separate.
- Start Node-RED interactively and read the startup output: which executable, which user-data directory, which network interface.
- Deploy a minimal test flow from an authorized engineering station, stop the process, start it again, and confirm the flow is still present.
- Configure automatic startup last; a service manager restarts a failing process and can hide a real dependency or permissions failure behind rapid restart loops.
An interactive shell and a service have different search paths and environments, so the interactive proof does not transfer. Acceptance must exercise the same startup path a controller reboot will use, because that is the path that runs unattended.
When is Docker the better path than a native install? #
On an embedded image that already ships a maintained container runtime, Docker is the better default, because the container carries Node-RED's whole dependency tree; go native when the runtime is absent, disallowed by policy, or when the measured flash budget binds.
A native install transfers dependency and update control to you: on a PTXdist image you become the maintainer of the Node runtime and its libatomic across image updates, with no package registry remembering any of it. A container keeps the base image's job and the application's job separate — and from the controller vendor's point of view Node-RED is third-party software either way. The identification work in this article still comes first, because the container runtime itself has to exist on the image you booted.
Questions asked
Does a newer Node.js version remove the libatomic requirement?
No. The requirement comes from the 32-bit ARM ABI, not from the Node.js release: documented missing-library failures span Node 12.18.4 installs and current Node 26 container images. Whatever runtime version you stage on an ARMv7l target, plan to stage the armhf libatomic build with it, and verify with a version-flag run before installing anything on top.
What should uname -m return, and when does libatomic apply?
On the reported compact controllers it returns armv7l, which is the architecture whose Node.js builds link libatomic.so.1. On an x86_64 target you take the linux-x64 tarball instead and this dependency does not arise. Run the command on the booted image rather than trusting a datasheet, because the architecture follows the image, and record the answer next to the os-release values.
Will a firmware update wipe a native Node-RED installation?
Treat it as if it will. Native files sit outside any package registry, so an image replacement or recovery can remove or orphan them without warning. Before any update, back up the Node-RED user-data directory with its flows and credentials, and record the runtime version and file locations so the installation can be rebuilt and retested against the new image.
Is armhf the right library build for an armv7l CPU?
Yes. The armv7l Linux userspace on these targets is hard-float, and armhf is that ABI, so libatomic1_13.2.0-4_armhf.deb is the matching build. A soft-float armel build is the wrong ABI and fails at load time. If the staged library still produces a load error, the hard-float against soft-float mismatch is the first thing to check.