Docs: Node Panel

1Install

Log in to a fresh server over SSH as root and run this one command. It downloads Node Panel and starts the installer, which takes about 5 to 15 minutes.

curl -fsSL https://nodepanel.putulmail.com/nodepanel.tar.gz -o nodepanel.tar.gz && mkdir -p nodepanel-src && tar xzf nodepanel.tar.gz -C nodepanel-src && cd nodepanel-src && sudo bash install.sh

At the end the installer prints the panel address. Open it in your browser (see First login).

Requirements

Ubuntu 22.04 or 24.04, Debian 12, or AlmaLinux / Rocky Linux 8 or 9. A fresh server is best.
Root access, and a root password (you log in to the panel with it).
At least 1 GB of RAM; 2 GB or more for WordPress, mail and several apps.
Open in your cloud provider's firewall: 80, 443, 53 (TCP and UDP) and the panel port 2083. The server's own firewall is opened by the installer.

Options

Use another panel port than 2083:

cd nodepanel-src && sudo PANEL_PORT=7800 bash install.sh

AlmaLinux / Rocky with SELinux enforcing: the panel's PHP cannot start its root helper until you allow it. Either write your own policy, or make only the web server's domain permissive:

cd nodepanel-src && sudo NP_SELINUX_PERMISSIVE_HTTPD=1 bash install.sh

2First login

Open https://YOUR-SERVER-IP:2083 in your browser.
The panel starts with a self-signed certificate, so the browser warns once: choose Advanced, then Proceed. Add a domain for the panel later under Security to get a real certificate.
Sign in as root with the server's root password. The panel has no separate admin password: change the root password and the panel login changes with it.

If root has no password yet (some providers only give an SSH key), set one first with passwd.

3Update

Every panel checks once a day for a new release. When one is out, the bell at the top of the panel shows it (and your alert e-mail or Telegram, if you set them up on the Monitoring page).

From the panel (easiest)

Open Server > System updates.
Read what's new in the Node Panel card and click Update now.
The panel downloads the release, checks its checksum and signature, and runs the installer in update mode. It restarts on the way; the page follows along and shows the log. Reload when it says it is done.

Not seeing the new version yet? Click Check now on the same card.

Over SSH

The install command is also the update command: on a server that already has Node Panel, the installer sees it and runs in update mode.

curl -fsSL https://nodepanel.putulmail.com/nodepanel.tar.gz -o nodepanel.tar.gz && rm -rf nodepanel-src && mkdir nodepanel-src && tar xzf nodepanel.tar.gz -C nodepanel-src && cd nodepanel-src && sudo bash install.sh

It prints Existing installation found — update mode near the start. It still walks through every step, so the output looks like an install, but steps that are already done are left alone.

What an update keeps and replaces

Kept

Panel settings, port and database password (config.php)
Apps, sites and their files (/home/np_*)
All databases (MariaDB, PostgreSQL)
Domains, DNS zones, SSL certificates
E-mail domains and mailboxes
Backups (/var/nodepanel/backups)
Users, monitoring history, activity log

Replaced

The panel's own code: /opt/nodepanel/panel and /opt/nodepanel/bin
The panel's nginx config (same port)
New database tables or columns are added; nothing is dropped
PHP-FPM and nginx restart: the panel is away for a minute or two, sites keep running

Files you put inside /opt/nodepanel/panel or /opt/nodepanel/bin by hand are removed by an update (those folders are made identical to the release). Keep your own files elsewhere.

4Commands

Run these over SSH as root (or with sudo).

Command	What it does
`passwd`	Changes the root password, which is also the panel login. You can change it from the panel too: Settings > Users > Change password.
`nodepanel-unlock`	Emergency unlock when the panel keeps you out: clears the panel IP allowlist, turns off two-factor login, clears login rate limits and all fail2ban bans.
`nodepanel-unlock --ssh-password`	The same, and turns SSH password login back on if the panel had switched it off.
`ufw allow 2083/tcp`	Opens the panel port in the firewall (Ubuntu / Debian).
`firewall-cmd --permanent --add-port=2083/tcp && firewall-cmd --reload`	The same on AlmaLinux / Rocky.
`fail2ban-client status sshd`	Shows the IPs banned for failed SSH logins. `fail2ban-client unban 1.2.3.4` lets one back in.

Services

Command	What it does
`systemctl status nginx`	Web server and reverse proxy. `nginx -t` checks its configuration, `systemctl reload nginx` applies it.
`systemctl status php8.3-fpm`	Runs the panel (and PHP sites). On AlmaLinux / Rocky it is `php83-php-fpm`.
`systemctl restart nginx php8.3-fpm`	Restarts the panel when it does not answer.
`systemctl status mariadb pdns`	Database server and DNS server.
`ls /etc/cron.d/nodepanel*`	The panel's scheduled jobs: backups, monitoring, traffic, update check.

Easier: Server > Services in the panel shows every service with Start, Restart and Stop buttons.

Apps

Each app runs as its own Linux user np_NAME and systemd service np-NAME (NAME is the app's name in the panel).

Command	What it does
`systemctl status np-NAME`	Is the app running, and its last lines of output.
`systemctl restart np-NAME`	Restarts it (the same as Restart in the panel).
`journalctl -u np-NAME -f`	Follows the app's log live. Ctrl+C to stop.
`systemctl list-units 'np-*'`	All app services and their state.
`ls /home/np_NAME`	The app's files.

Node.js versions

Install several Node.js versions side by side and pick one per app. Manage them in the panel under Applications > Node.js versions. They are kept in /opt/nodepanel/node/<version>.

Install — choose a version from the nodejs.org list (or type a custom version) and press Install. It is downloaded and SHA256-verified.
Make default — sets the server-wide default used by new apps and by the node / npm commands on the shell.
Uninstall — press the trash button next to a version to remove it from the server.

A version cannot be uninstalled while it is the default (set another one as default first), or while an app still uses it — the panel names those apps so you can move them to another version first.

Logs

File	What is in it
`/var/log/nodepanel/apps/`	Output of every app.
`/var/log/nodepanel/panel-php.log`	Errors of the panel itself.
`/var/log/nodepanel/auth.log`	Panel sign-ins and failures (read by fail2ban).
`/var/log/nodepanel/panel-update.log`	The last panel update started from the panel.
`/var/log/nodepanel/apt.log`	System package updates started from Server > System updates.
`/var/log/nginx/error.log`	Web server errors.

# the last 50 lines, then follow new ones
tail -n 50 -f /var/log/nodepanel/panel-php.log

Updates

Command	What it does
`grep NP_VERSION /opt/nodepanel/panel/inc/bootstrap.php`	The installed panel version.
`php /opt/nodepanel/bin/update-check.php now`	Asks for the latest release right away (the panel does it once a day).
`systemctl status nodepanel-self-update`	Is an update started from the panel still running.
`tail -f /var/log/nodepanel/panel-update.log`	Follows that update's output.
`apt update && apt upgrade`	System packages on Ubuntu / Debian (`dnf upgrade` on AlmaLinux / Rocky). The panel's System updates page does the same.

5Files and folders

Path	What it is
`/opt/nodepanel/panel`	The panel (web part). `config.php` in it holds the database password: keep it private.
`/opt/nodepanel/bin`	The panel's root helper and background jobs.
`/opt/nodepanel/node/`	Installed Node.js versions.
`/home/np_NAME`	One app or site: its files and home folder.
`/etc/nodepanel/env/`	Each app's environment variables (root only).
`/var/nodepanel/backups`	Local backups.
`/etc/nginx/conf.d/np-*.conf`	One nginx file per domain, written by the panel: change sites in the panel, not here.
`/var/log/nodepanel`	Panel and app logs.

6Troubleshooting

The panel does not open in the browser

Check the cloud provider's firewall first (port 2083), then the server's own:

ufw allow 2083/tcp; systemctl restart nginx php8.3-fpm

Still nothing? nginx -t shows a broken configuration, systemctl status php8.3-fpm shows whether the panel's PHP runs.

I am locked out (IP allowlist, two-factor, too many attempts)

sudo nodepanel-unlock

Then sign in again and set up the allowlist or two-factor login on the Security page.

I forgot the panel password

It is the server's root password. Log in over SSH (or your provider's web console) and set a new one:

passwd

An update failed

The log shows the step that stopped:

tail -n 80 /var/log/nodepanel/panel-update.log

Your apps and data are not touched by a failed update. Fix what the log says (often a full disk or a package mirror that was down) and run the update again, from the panel or over SSH.

An app is down

systemctl status np-NAME
journalctl -u np-NAME -n 100

The last lines usually name the error (a missing module, a wrong environment variable, the port in use). Fix it in the app's page in the panel and press Restart.

7Update check and privacy

Once a day each panel asks nodepanel.putulmail.com for the latest release. With it, the panel sends: a random install ID, the panel version, the hostname, the operating system, the panel port, the number of apps, and the result of its last self-update. Nothing else: no domains, no files, no passwords.

Turn the report off in Settings > General > Panel updates > Report this server. The panel then only reads the latest version, and the bell still tells you about new releases.

Every release is signed. A panel installs an update only when the signature matches the Node Panel release key, so a package changed by anyone else is refused.

Documentation