n8n: run 3.x natively from the official Debian image

n8n 3.0 is no longer published to npm, only as a Docker image. Its Debian
variant (n8nio/n8n:<version>-debian) is Node.js plus a prebuilt app folder,
so pull it with skopeo + umoci (no container runtime), as immich does for
its libraries, and run /usr/local/lib/node_modules/n8n from /opt/n8n.

The version follows the n8nio/n8n:latest tag (var_n8n_image_tag pins
another one). While that is 2.x, install and update keep using npm as
before; once n8n promotes 3.x, new installs use the image and updates
offer the one-way move from 2.x: back up ~/.n8n, remove the npm package,
switch Node.js to the image's major and swap in the app folder. Declining
(or an unattended run without var_force_breaking_update=yes) stays on npm
2.x.

The image is downloaded and unpacked before n8n stops, so a failure
leaves the install as it was. Unpacking needs Proxmox VE 9.1 or newer.
This commit is contained in:
Rögl-Brunner Michel committed 2026-11-17 11:23:07 +01:00
1 parent 59ea71e043
commit 1cff8634e6
2 files changed
+263 -16

No files matched your search

+179 -5
View File
@@ -16,6 +16,14 @@ var_version="${var_version:-13}"
var_arm64="${var_arm64:-yes}"
var_unprivileged="${var_unprivileged:-1}"
# The n8nio/n8n image tag to follow: "latest" is n8n's current stable release.
# var_n8n_image_tag set to a version (e.g. 3.3.0) pins that release,
# prereleases included.
N8N_IMAGE_TAG="${var_n8n_image_tag:-latest}"
# Moving from 2.x to 3.x cannot be undone, so the update asks first. Unattended,
# var_force_breaking_update=yes answers yes; anything else keeps 2.x.
N8N_FORCE_MAJOR="${var_force_breaking_update:-no}"
header_info "$APP"
variables
color
@@ -30,10 +38,6 @@ function update_script() {
exit
fi
ensure_dependencies build-essential python3-setuptools graphicsmagick
NODE_VERSION="24" setup_nodejs
msg_info "Updating n8n"
if [ ! -f /opt/n8n.env ]; then
sed -i 's|^Environment="N8N_SECURE_COOKIE=false"$|EnvironmentFile=/opt/n8n.env|' /etc/systemd/system/n8n.service
mkdir -p /opt
@@ -46,6 +50,122 @@ EOF
systemctl daemon-reload
fi
ensure_dependencies jq
if ! { command -v skopeo && command -v umoci; } >/dev/null 2>&1 &&
! $STD apt install -y --no-install-recommends skopeo umoci; then
msg_error "Could not install skopeo and umoci, which n8n needs for its updates. n8n was not updated."
exit 105
fi
# n8n 3.x is no longer published to npm, only as a Docker image. 2.x still
# updates through npm; 3.x comes from the image (see fetch_n8n_image).
msg_info "Checking the latest n8n release"
local target
target="$(skopeo inspect --override-os linux --override-arch "$(arch_resolve amd64 arm64)" "docker://docker.io/n8nio/n8n:${N8N_IMAGE_TAG}" 2>/dev/null |
jq -r '.Labels["org.opencontainers.image.version"] // empty')" || true
if [[ ! "$target" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
msg_error "Could not read the n8n version of n8nio/n8n:${N8N_IMAGE_TAG}. n8n was not updated."
exit 115
fi
msg_ok "Latest n8n release is ${target}"
local current=""
if [[ -f /opt/n8n/package.json ]]; then
current="$(cat ~/.n8n-version 2>/dev/null)" || true
[[ -n "$current" ]] || current="$(jq -r '.version // empty' /opt/n8n/package.json)"
if [[ "$current" == "$target" ]]; then
msg_ok "n8n is already at ${target}"
exit
fi
if ((${target%%.*} < 3)); then
msg_warn "n8n ${current} cannot go back to ${target}; nothing was changed."
exit
fi
else
if ((${target%%.*} < 3)); then
update_n8n_npm
exit
fi
local npm_root
npm_root="$(npm root -g 2>/dev/null)" || true
[[ -n "$npm_root" && -f "${npm_root}/n8n/package.json" ]] && current="$(jq -r '.version // empty' "${npm_root}/n8n/package.json")"
echo
msg_warn "n8n ${target} is out. From 3.0 on, n8n is not published to npm any more."
echo -e "${TAB}This update moves n8n ${current:-2.x} to ${target}, unpacked from the official Docker image."
echo -e "${TAB}There is no way back to 2.x afterwards. 3.0 removes legacy nodes (Function, Cron,"
echo -e "${TAB}Interval, Read/Write Binary File, ...). Check Settings > Migration Report in n8n first."
echo -e "${TAB}The SQLite data in ~/.n8n is backed up first; an external database is not."
echo -e "${TAB}Declining keeps n8n on 2.x, which gets security fixes for 12 months after 3.x."
echo
if [[ ! "${N8N_FORCE_MAJOR,,}" =~ ^(1|yes|true|on)$ ]] && ! prompt_confirm "Upgrade n8n to ${target}?" "n" 300; then
msg_warn "Staying on n8n 2.x"
update_n8n_npm
exit
fi
fi
fetch_n8n_image "$target"
msg_info "Stopping n8n"
systemctl stop n8n
msg_ok "Stopped n8n"
if [[ ! -f /opt/n8n/package.json ]]; then
local data_parent backup
data_parent="$(sed -n 's/^N8N_USER_FOLDER=//p' /opt/n8n.env | tail -n1)"
data_parent="${data_parent:-/root}"
if [[ -d "${data_parent}/.n8n" ]]; then
msg_info "Backing up n8n data"
backup="/root/n8n-backup-${current:-2.x}-$(date +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$backup" -C "$data_parent" .n8n
msg_ok "Backed up n8n data to ${backup}"
fi
msg_info "Removing the npm install of n8n"
$STD npm uninstall -g n8n || true
cat <<EOF >/etc/systemd/system/n8n.service
[Unit]
Description=n8n
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
Environment=NODE_ENV=production
EnvironmentFile=/opt/n8n.env
ExecStart=/usr/bin/env n8n start
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
msg_ok "Removed the npm install of n8n"
fi
NODE_VERSION="$N8N_NODE_MAJOR" setup_nodejs
install_n8n_image "$target"
msg_info "Starting n8n"
systemctl start n8n
msg_ok "Started n8n"
msg_ok "Updated successfully!"
exit
}
# n8n 2.x: the npm package, as before.
function update_n8n_npm() {
ensure_dependencies build-essential python3-setuptools graphicsmagick
NODE_VERSION="24" setup_nodejs
local installed latest
installed="$(jq -r '.version // empty' "$(npm root -g)/n8n/package.json" 2>/dev/null)" || true
latest="$(npm view n8n@latest version 2>/dev/null)" || true
if [[ -n "$latest" && "$installed" == "$latest" ]]; then
msg_ok "n8n is already at ${latest}"
return 0
fi
msg_info "Updating n8n"
# n8n-nodes-base 2.46.0 pins both @napi-rs/canvas musl binaries as hard
# dependencies, which no os/cpu/libc combination can satisfy. Drop --force
# once upstream makes them optional again.
@@ -53,7 +173,61 @@ EOF
systemctl restart n8n
msg_ok "Updated n8n"
msg_ok "Updated successfully!"
exit
}
# n8n 3.x: n8nio/n8n:<version>-debian is Node.js plus a prebuilt app folder in
# /usr/local/lib/node_modules/n8n. fetch_n8n_image downloads and unpacks it with
# skopeo + umoci (no container runtime) while n8n still runs, so a failure
# leaves the install as it was. install_n8n_image swaps it in once n8n stopped.
function fetch_n8n_image() {
local version="$1" oci_dir
msg_info "Downloading n8n ${version} (Patience)"
oci_dir="$(mktemp -d)"
# On the same filesystem as /opt/n8n, so the app folder is moved, not copied.
N8N_BUNDLE="$(mktemp -d -p /opt)"
if ! $STD skopeo copy --override-os linux --override-arch "$(arch_resolve amd64 arm64)" "docker://docker.io/n8nio/n8n:${version}-debian" "oci:${oci_dir}:img"; then
rm -rf "$oci_dir" "$N8N_BUNDLE"
msg_error "Could not download n8nio/n8n:${version}-debian. n8n was not updated."
exit 115
fi
if ! $STD umoci unpack --image "${oci_dir}:img" "$N8N_BUNDLE"; then
rm -rf "$oci_dir" "$N8N_BUNDLE"
msg_error "Could not unpack the n8n image. n8n 3.x needs Proxmox VE 9.1 or newer; it was not updated."
exit 105
fi
rm -rf "$oci_dir"
# The native modules in the image are built for its Node.js major version.
N8N_NODE_MAJOR="$(jq -r '.process.env[] | select(startswith("NODE_VERSION=")) | ltrimstr("NODE_VERSION=") | split(".")[0]' "${N8N_BUNDLE}/config.json" 2>/dev/null)" || true
if [[ ! "$N8N_NODE_MAJOR" =~ ^[0-9]+$ || ! -f "${N8N_BUNDLE}/rootfs/usr/local/lib/node_modules/n8n/package.json" ]]; then
rm -rf "$N8N_BUNDLE"
msg_error "The n8n ${version} image does not have the expected layout. n8n was not updated."
exit 1
fi
msg_ok "Downloaded n8n ${version}"
}
function install_n8n_image() {
local version="$1"
msg_info "Installing n8n ${version}"
# The runtime libraries the n8n base image adds on top of Node.js.
ensure_dependencies git openssh-client tzdata ca-certificates graphicsmagick \
libaio1t64 libsasl2-2 libssl3t64 liblz4-1 libzstd1 libxxhash0 zlib1g
rm -rf /opt/n8n
mv "${N8N_BUNDLE}/rootfs/usr/local/lib/node_modules/n8n" /opt/n8n
if [[ -d "${N8N_BUNDLE}/rootfs/usr/share/fonts/truetype/msttcorefonts" ]]; then
mkdir -p /usr/share/fonts/truetype
rm -rf /usr/share/fonts/truetype/msttcorefonts
cp -a "${N8N_BUNDLE}/rootfs/usr/share/fonts/truetype/msttcorefonts" /usr/share/fonts/truetype/
fi
rm -rf "$N8N_BUNDLE"
mkdir -p /usr/local/bin
ln -sf /opt/n8n/bin/n8n /usr/local/bin/n8n
if ! /usr/local/bin/n8n --version 2>/dev/null | grep -qxF "$version"; then
msg_error "n8n ${version} does not start in this container."
exit 1
fi
echo "$version" >~/.n8n-version
msg_ok "Installed n8n ${version}"
}
start
+84 -11
View File
@@ -13,21 +13,90 @@ setting_up_container
network_check
update_os
# n8n 3.x is no longer published to npm, only as a Docker image. Its Debian
# variant (n8nio/n8n:<version>-debian) is Node.js plus a prebuilt app folder, so
# pull it with skopeo + umoci (no container runtime) and run that folder
# natively. n8n 2.x has no Debian image for every release and still comes from
# npm. The version follows the image's "latest" tag, so new installs switch to
# 3.x when n8n promotes it. Unpacking the image needs Proxmox VE 9.1 or newer.
# var_n8n_image_tag set to a version (e.g. 3.3.0) pins that release instead.
N8N_IMAGE_TAG="${var_n8n_image_tag:-latest}"
msg_info "Installing Dependencies"
$STD apt install -y \
build-essential \
python3-setuptools \
graphicsmagick
graphicsmagick \
git \
openssh-client \
tzdata \
ca-certificates \
jq
$STD apt install -y --no-install-recommends skopeo umoci
msg_ok "Installed Dependencies"
NODE_VERSION="24" setup_nodejs
msg_info "Checking the latest n8n release"
N8N_VERSION="$(skopeo inspect --override-os linux --override-arch "$(arch_resolve amd64 arm64)" "docker://docker.io/n8nio/n8n:${N8N_IMAGE_TAG}" 2>/dev/null |
jq -r '.Labels["org.opencontainers.image.version"] // empty')" || true
if [[ ! "$N8N_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
msg_error "Could not read the n8n version of n8nio/n8n:${N8N_IMAGE_TAG}."
exit 115
fi
msg_ok "Latest n8n release is ${N8N_VERSION}"
msg_info "Installing n8n (Patience)"
# n8n-nodes-base 2.46.0 pins both @napi-rs/canvas musl binaries as hard
# dependencies, which no os/cpu/libc combination can satisfy. Drop --force
# once upstream makes them optional again.
$STD npm install -g n8n@latest --force
msg_ok "Installed n8n"
if ((${N8N_VERSION%%.*} >= 3)); then
msg_info "Downloading n8n ${N8N_VERSION} (Patience)"
OCI_DIR="$(mktemp -d)"
# On the same filesystem as /opt/n8n, so the app folder is moved, not copied.
OCI_BUNDLE="$(mktemp -d -p /opt)"
if ! $STD skopeo copy --override-os linux --override-arch "$(arch_resolve amd64 arm64)" "docker://docker.io/n8nio/n8n:${N8N_VERSION}-debian" "oci:${OCI_DIR}:img"; then
rm -rf "$OCI_DIR" "$OCI_BUNDLE"
msg_error "Could not download n8nio/n8n:${N8N_VERSION}-debian."
exit 115
fi
if ! $STD umoci unpack --image "${OCI_DIR}:img" "$OCI_BUNDLE"; then
rm -rf "$OCI_DIR" "$OCI_BUNDLE"
msg_error "Could not unpack the n8n image. n8n 3.x needs Proxmox VE 9.1 or newer."
exit 105
fi
rm -rf "$OCI_DIR"
# The native modules in the image are built for its Node.js major version.
N8N_NODE_MAJOR="$(jq -r '.process.env[] | select(startswith("NODE_VERSION=")) | ltrimstr("NODE_VERSION=") | split(".")[0]' "${OCI_BUNDLE}/config.json" 2>/dev/null)" || true
if [[ ! "$N8N_NODE_MAJOR" =~ ^[0-9]+$ || ! -f "${OCI_BUNDLE}/rootfs/usr/local/lib/node_modules/n8n/package.json" ]]; then
rm -rf "$OCI_BUNDLE"
msg_error "The n8n ${N8N_VERSION} image does not have the expected layout."
exit 1
fi
msg_ok "Downloaded n8n ${N8N_VERSION}"
NODE_VERSION="$N8N_NODE_MAJOR" setup_nodejs
msg_info "Installing n8n ${N8N_VERSION}"
# The runtime libraries the n8n base image adds on top of Node.js.
$STD apt install -y --no-install-recommends libaio1t64 libsasl2-2 libssl3t64 liblz4-1 libzstd1 libxxhash0 zlib1g
mv "${OCI_BUNDLE}/rootfs/usr/local/lib/node_modules/n8n" /opt/n8n
if [[ -d "${OCI_BUNDLE}/rootfs/usr/share/fonts/truetype/msttcorefonts" ]]; then
mkdir -p /usr/share/fonts/truetype
cp -a "${OCI_BUNDLE}/rootfs/usr/share/fonts/truetype/msttcorefonts" /usr/share/fonts/truetype/
fi
rm -rf "$OCI_BUNDLE"
mkdir -p /usr/local/bin
ln -sf /opt/n8n/bin/n8n /usr/local/bin/n8n
if ! /usr/local/bin/n8n --version 2>/dev/null | grep -qxF "$N8N_VERSION"; then
msg_error "n8n ${N8N_VERSION} does not start in this container."
exit 1
fi
echo "$N8N_VERSION" >~/.n8n-version
msg_ok "Installed n8n ${N8N_VERSION}"
else
$STD apt install -y build-essential python3-setuptools
NODE_VERSION="24" setup_nodejs
msg_info "Installing n8n (Patience)"
# n8n-nodes-base 2.46.0 pins both @napi-rs/canvas musl binaries as hard
# dependencies, which no os/cpu/libc combination can satisfy. Drop --force
# once upstream makes them optional again.
$STD npm install -g n8n@latest --force
msg_ok "Installed n8n"
fi
msg_info "Creating Service"
cat <<EOF >/opt/n8n.env
@@ -40,11 +109,15 @@ EOF
cat <<EOF >/etc/systemd/system/n8n.service
[Unit]
Description=n8n
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
Environment=NODE_ENV=production
EnvironmentFile=/opt/n8n.env
ExecStart=n8n start
ExecStart=/usr/bin/env n8n start
Restart=on-failure
[Install]
WantedBy=multi-user.target