Node.js sites

How a Node.js site runs

The panel creates a systemd unit, aurapanel-site-<domain>.service, that starts your application as the site's Linux user on a loopback port, and an nginx server block that proxies the domain to that port with HTTPS. You never write the unit or the server block; you deploy code and the panel starts it.

Node versions are installed under Services → Node Versions from nodejs.org release tarballs into /opt/aurapanel/node/<version>/, with node, npm, npx and corepack available on the PATH. Each site pins a version; change it in the site's settings.

Create the site

1. Install a Node version under Services if none is present.
2. Sites → Add site → Node.js. Enter the domain, choose the Node version, accept the suggested app port (the next free loopback port) and pick a supervisor: systemd runs your start command directly; PM2 runs it under pm2-runtime inside the same unit.
3. Create. The unit exists but has nothing to run yet, so the site shows the panel's placeholder until you deploy.

Deploy your code

Put the application in the document root, /home/<user>/htdocs/<domain>/, by any means: the File Browser, SFTP, git clone as the site user, rsync from CI. Then either press Install dependencies on the site, or do it from a shell:

sudo -u <site-user> -i
cd ~/htdocs/example.com
npm ci --omit=dev          # or pnpm / yarn — the panel detects the lockfile
npm run build              # if your app has a build step
exit
sudo systemctl restart aurapanel-site-example.com

Install dependencies does the same: it installs with the package manager your lockfile implies (npm, pnpm or yarn), runs the build script if there is one, re-applies the unit and server block, restarts the service and probes it. A tick box does a clean install first.

How the start command is chosen

The command is resolved every time the unit starts, in this order, so the first deploy and every later one are treated the same:

1. An explicit start file set in the site's settings.
2. The start script in package.json, run with the detected package manager.
3. The main field in package.json.
4. server.js, index.js or app.js in the document root.

Environment your app receives

A .env file in the document root is loaded first, so your own variables go there. PORT and HOST are reserved.

Restarts and crashes

The unit has Restart=always with a 3-second delay that backs off to 5 minutes. If the process fails to start more than five times in a minute, systemd parks it as failed so a crash loop does not consume the server; fix the cause, then restart from the site or with systemctl restart aurapanel-site-<domain>. Stops are given 10 seconds before the process is killed.

Logs

Your application's stdout and stderr go to the journal, shown on the site's Logs tab and available on the server for about seven days:

journalctl -u aurapanel-site-example.com -f

nginx's access and error logs for the domain are in /home/<user>/logs/. See Logs and monitoring.

Common messages

Bun is not bundled; use npm, pnpm or yarn.