Legendary Arena Lab

Node Runtime

wiki

Node Runtime

Migration in progress. api.legendary-arena.com and its PostgreSQL are moving off Render onto a self-hosted DigitalOcean Ubuntu droplet fronted by Cloudflare, per docs/PLAN.md . Until decommission, Render stays warm as the rollback target.

Summary

This page provisions the Node.js toolchain the game server runs on. fnm installs the pinned Node into a shared, world-readable directory, a stable /opt/node link points at it, and pnpm is installed alongside. The build and the systemd service both use /opt/node/bin directly, so nothing depends on a per-user fnm setup.

Mechanics

The owning artifact is infra/scripts/10-node.ps1 . It requires root, runs under Set-StrictMode, and stops on the first failing command (including native commands such as apt-get). In order:

  1. Prereqs. Confirms the operator user exists, then installs curl, ca-certificates, and unzip.

  2. fnm. Downloads fnm-linux.zip from the latest fnm release into /opt/fnm/fnm. Skipped if the binary is already there.

  3. Node. Installs the pinned Node with FNM_DIR=/opt/fnm/node-versions and points /opt/node at the installation:

    NODE_VERSION = 24.18.0
    /opt/fnm/node-versions/node-versions/v24.18.0/installation   # the real install
    /opt/node -> that installation                               # what everything uses
    

    fnm’s default FNM_DIR is the invoking user’s home. Run as root, that put Node under /root, where the operator-owned service could not reach it; the shared directory is the fix.

  4. pnpm. npm install --global pnpm@10.32.1 into /opt/node, so /opt/node/bin/pnpm exists for every user.

  5. Shell profile. Writes /etc/profile.d/la-node.sh so login shells put /opt/node/bin on PATH.

  6. Verify. Prints node --version and pnpm --version as the operator user, which proves the service account can run them.

The pinned 24.18.0 matches the engine repo’s .node-version and Render’s NODE_VERSION (D-24205); pnpm 10.32.1 matches the engine’s packageManager field.

Interactions

  • Deploy Server — builds with /opt/node/bin/pnpm; run this page first.
  • Provision Droplet — cloud-init creates the operator user this script requires.
  • The la-server unit runs /opt/node/bin/node directly (see Deploy Server ).

Edge Cases

  • Version must match .node-version. Per docs/PLAN.md (D-24205), a newer Node is a different system, not a compatible upgrade. To upgrade, change NODE_VERSION here, in the engine repo’s .node-version, and in render.yaml together; re-running the script re-points /opt/node.
  • /opt/node is load-bearing. The systemd unit and the deploy script use that path. Do not remove it while the service is running.
  • pnpm version follows packageManager. Changing PNPM_VERSION without the engine’s packageManager field drifts the toolchain.
  • GitHub fetch at provision time. The fnm download uses GitHub’s release API; a network blip or rate limit fails the step. Re-run; it is idempotent.

Execute

# Default provision (operator user, Node 24.18.0, pnpm 10.32.1)
sudo pwsh -File /opt/la-lab/infra/scripts/10-node.ps1

Verify

sudo -u operator /opt/node/bin/node --version
# Expected: v24.18.0

sudo -u operator env PATH=/opt/node/bin:/usr/bin:/bin pnpm --version
# Expected: 10.32.1

The provision smoke workflow runs this script twice on a fresh Ubuntu 24.04 runner (install and idempotent re-run).

References