Running on Proxmox - how to install?

[antamy]

I'm trying to get this running in a Proxmox LXC but I am running into trouble. I'm not sure if I'm just misunderstanding the instructions.

I created a new Debian 13 LXC and ran the bare-metal install script wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh -O proxmox-install-netalertx.sh && chmod +x proxmox-install-netalertx.sh && ./proxmox-install-netalertx.sh. This all appeared to work, but I couldn't access the application. So I executed the start up script at /app/install/<system>/start.<system>.sh substituting <system> with debian12 (there is no debian13). This installed a bunch more stuff and then started the application, which promptly stopped with this error:

[INSTALL] 🚀 Starting app - navigate to your <server IP>:
/opt/venv/lib/python3.13/site-packages/requests/__init__.py:113: RequestsDependencyWarning: urllib3 (2.6.3) or chardet (7.2.0)/charset_normalizer (3.4.6) doesn't match a supported version!
  warnings.warn(
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/app//server/__main__.py", line 30, in <module>
    from api import update_api
  File "/app//server/api.py", line 31, in <module>
    from api_server.api_server_start import start_server
  File "/app//server/api_server/api_server_start.py", line 8, in <module>
    from models.device_instance import DeviceInstance  # noqa: E402
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app//server/models/device_instance.py", line 7, in <module>
    from front.plugins.plugin_helper import is_mac, normalize_mac
ModuleNotFoundError: No module named 'front'

Any ideas on what I'm doing wrong or how to correct this?

Thanks

[jokob-sk]

Hi - currently worked on here: #1491

Proxmox install is community supported so relying on others to keep it up to date and test as I don't run proxmox myself. Feel free to help out too.

[antamy]

ok. I spent some time with Claude analyzing this and have pasted the full findings in the following post. I'm not sure that all of Claude's assertions on this are correct, however applying the fixes in the sequence listed got me up and running. Hopefully the maintainers can fix the script. @JVKeller, @heinemannj.

[antamy]

NetAlertX on Proxmox LXC — Bare-Metal Installation Fix Guide

Debian 13 (Trixie) | March 2026 | Community-contributed workaround

---

Background

The official NetAlertX bare-metal install script (proxmox-install-netalertx.sh) has a sequencing bug on Debian 13: it installs and attempts to restart nginx before the nginx configuration file has been written. Because the script runs with set -e, this failure aborts the entire installation, leaving the system in a half-configured state.

Additionally, the application codebase was written primarily for Docker and contains several hardcoded paths (/data/, /tmp/api/, /tmp/log/) that Docker creates automatically via volume mounts but which do not exist in a bare-metal environment. The proxmox install script is intended to handle these but does not, because it never gets past the nginx failure.

This guide manually completes what the install script would have done, and adds the path mappings the app requires.

---

Prerequisites

• Fresh Debian 13 LXC in Proxmox (recommended: 2 cores, 2GB RAM, 8GB disk)
• LXC must be privileged or have nesting enabled for tmpfs mounts
• Network access from the LXC to the internet (for apt and git clone)
• Run all commands as root

---

Part 1: Run the Official Install Script

Run the official Proxmox install script. It will fail partway through — this is expected.

wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh \
  -O proxmox-install-netalertx.sh
chmod +x proxmox-install-netalertx.sh
./proxmox-install-netalertx.sh

The script will stop with an error similar to:

Job for nginx.service failed because the control process exited with error code.

⚠️ Do NOT run start.debian12.sh. That script targets a different install path and will create a conflicting Python venv at /opt/venv, causing a ModuleNotFoundError for the front module.

Despite the failure, the script will have completed the git clone. Verify:

ls /app/server /app/front /app/config /app/install

All four directories should exist before proceeding.

---

Part 2: Fix Nginx and Complete the Installation

2.1 Unblock Nginx

Nginx failed because its config file didn't exist yet. Create a placeholder so it can start:

touch /etc/nginx/conf.d/netalertx.conf
systemctl start nginx
systemctl status nginx   # confirm Active: active (running)

2.2 Set Up Python Environment

The script installs from install/proxmox/requirements.txt which is incomplete. Install from the root requirements.txt instead:

source /opt/myenv/bin/activate
pip install --upgrade pip
pip install -r /app/requirements.txt

2.3 Configure Nginx

# Remove default site if present
rm -f /etc/nginx/sites-enabled/default
Create web UI symlink
ln -sfn /app/front /var/www/html/netalertx
Copy nginx config from installer and link it
cp /app/install/proxmox/netalertx.conf /app/config/netalertx.conf

ln -sfn /app/config/netalertx.conf /etc/nginx/conf.d/netalertx.conf
Test and restart nginx
nginx -t

/etc/init.d/nginx restart

2.4 Copy Starter DB and Config

mkdir -p /app/db
cp -u /app/back/app.conf /app/config/app.conf
cp -u /app/back/app.db /app/db/app.db

2.5 Create /data Path Mappings

The Python server hardcodes /data/ as the root for config, db, log, and api. Map these to the actual locations:

mkdir -p /data
ln -sfn /app/config /data/config
ln -sfn /app/db     /data/db
ln -sfn /tmp/log    /data/log
ln -sfn /tmp/api    /data/api

⚠️ The /app/api and /app/log entries in the repo are already symlinks pointing to /tmp/api and /tmp/log respectively (baked into the git repo). Do not symlink /data/api to /app/api — this creates a circular reference causing a "Too many levels of symbolic links" error.

2.6 Create tmpfs Runtime Directories

The app writes runtime state to /tmp/api and /tmp/log. These must exist and be owned by www-data:

mkdir -p /tmp/api
mkdir -p /tmp/log/plugins
touch /tmp/log/app.log /tmp/log/execution_queue.log /tmp/log/app_front.log
touch /tmp/log/app.php_errors.log /tmp/log/stderr.log /tmp/log/stdout.log /tmp/log/db_is_locked.log
touch /tmp/api/user_notifications.json
chown -R www-data:www-data /tmp/api /tmp/log

2.7 Start PHP

/etc/init.d/php8.4-fpm start

2.8 Set Permissions

chgrp -R www-data /app
chmod -R ug+rwX,o-rwx /app
chown -R www-data:www-data /app/db/app.db
chown -R www-data:www-data /tmp/api /tmp/log

2.9 Grant arp-scan Sudo Privileges

The service runs as www-data but arp-scan requires root to send raw packets. Without this, ARPSCAN will silently fail with a sudoers error and no devices will ever be discovered:

echo "www-data ALL=(root) NOPASSWD: /usr/sbin/arp-scan" > /etc/sudoers.d/netalertx-arpscan
chmod 440 /etc/sudoers.d/netalertx-arpscan
visudo -c -f /etc/sudoers.d/netalertx-arpscan

---

Part 3: Create the Systemd Service

3.1 Create the Start Script

Substitute your LXC's IP address for YOUR_LXC_IP below:

cat > /app/start.netalertx.sh << 'EOF'
#!/usr/bin/env bash
source /opt/myenv/bin/activate
export PYTHONPATH=/app
echo "Starting NetAlertX - navigate to http://YOUR_LXC_IP:20211"
cd /app
python server/
EOF
chmod +x /app/start.netalertx.sh

3.2 Create the Systemd Unit

cat > /etc/systemd/system/netalertx.service << 'EOF'
[Unit]
Description=NetAlertX Service
After=network-online.target nginx.service
Wants=network-online.target
[Service]

Type=simple

User=www-data

Group=www-data

ExecStartPre=/bin/bash -c 'mkdir -p /tmp/api /tmp/log/plugins && chown -R www-data:www-data /tmp/api /tmp/log'

ExecStart=/app/start.netalertx.sh

WorkingDirectory=/app

Restart=on-failure

RestartSec=5

StandardOutput=journal

StandardError=journal
[Install]

WantedBy=multi-user.target

EOF

⚠️ The ExecStartPre line recreates /tmp/api and /tmp/log on every service start. This is necessary because /tmp is cleared on reboot.

3.3 Enable and Start

systemctl daemon-reload
systemctl enable netalertx.service
systemctl start netalertx.service
sleep 5
systemctl status netalertx.service

The service should show Active: active (running). Check the journal if it doesn't:

journalctl -u netalertx.service -n 50 --no-pager

---

Part 4: Verify

Navigate to http://YOUR_LXC_IP:20211 in a browser. You should see the NetAlertX dashboard.

On first launch the app will initialize its database and begin scanning. The ARPSCAN plugin runs on a schedule — check the Devices tab after a few minutes. You can also trigger an immediate scan from the UI via Plugins → ARPSCAN → Run Now.

The journal should show plugin loading messages (ARPSCAN, AVAHISCAN, etc.) without any Python tracebacks.

---

Root Cause Summary

Issue	Root Cause
nginx fails mid-install	Script attempts nginx restart before netalertx.conf exists; set -e aborts everything
ModuleNotFoundError: front	Running start.debian12.sh creates /opt/venv instead of /opt/myenv, and doesn't set PYTHONPATH=/app
app.conf not found at /data/config	App hardcodes /data/ (Docker volume path); bare-metal install never creates this mapping
Missing pydantic	install/proxmox/requirements.txt is incomplete; root requirements.txt has the full list
Too many symlink levels	/app/api already points to /tmp/api in the repo; symlinking /tmp/api back to /app/api creates a loop
/tmp/api and /tmp/log missing	Docker creates these via volume mounts; bare-metal has nothing creating them, and they are lost on reboot
No devices discovered	arp-scan requires root; www-data service user is not in sudoers for /usr/sbin/arp-scan

---