Skip to content

Bare metal Installer rework #1173

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jokob-sk merged 5 commits into from
Sep 12, 2025
Merged

Bare metal Installer rework #1173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
db42d7f
Installer-rework
ingoratsdorf Sep 11, 2025
e0ffe8b
Delete old Debian12 files
ingoratsdorf Sep 11, 2025
9943c98
DOC updates
ingoratsdorf Sep 12, 2025
e00f266
CodeRabbit suggestions
ingoratsdorf Sep 12, 2025
8f00a28
Numbering sequence corrected
ingoratsdorf Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 34 additions & 14 deletions docs/HW_INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,49 +7,69 @@ To download and install NetAlertX on the hardware/server directly use the `curl`
>
> 🙏 Looking for maintainers for this installation method 🙂 Current community volunteers:
> - [slammingprogramming](https://github.com/slammingprogramming)
> - [ingoratsdorf](https://github.com/ingoratsdorf)
>
> There is no guarantee that the install script or any other script will gracefully handle other installed software.
> Data loss is a possibility, **it is recommended to install NetAlertX using the supplied Docker image**.

A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may
> [!WARNING]
> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may
be dangerous, as you cannot see the code that's about to be executed on your system.

Alternatively you can download the installation script `install/install.debian.sh` from the repository and check the code yourself (beware other scripts are
downloaded too - only from this repo).
If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will fo its best to install NetAlertX on your system.

Alternatively you can download the installation script from the repository and check the code yourself.

Comment on lines +15 to 22
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix wording and markdownlint issues in the WARNING block.

Correct typo and remove blank line/multiple spaces after blockquote symbols to satisfy MD027/MD028.

-> [!WARNING]
-> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may
-be dangerous, as you cannot see the code that's about to be executed on your system.
+> [!WARNING]
+> A warning about the method below: piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may be dangerous,
+> as you cannot see the code that's about to be executed on your system.
 
-If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will fo its best to install NetAlertX on your system.
+If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will do its best to install NetAlertX on your system.
 
-Alternatively you can download the installation script from the repository and check the code yourself.
+Alternatively, you can download the installation script from the repository and review the code yourself.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
> [!WARNING]
> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may
be dangerous, as you cannot see the code that's about to be executed on your system.
Alternatively you can download the installation script `install/install.debian.sh` from the repository and check the code yourself (beware other scripts are
downloaded too - only from this repo).
If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will fo its best to install NetAlertX on your system.
Alternatively you can download the installation script from the repository and check the code yourself.
> [!WARNING]
> A warning about the method below: piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may be dangerous,
> as you cannot see the code that's about to be executed on your system.
If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will do its best to install NetAlertX on your system.
Alternatively, you can download the installation script from the repository and review the code yourself.
🤖 Prompt for AI Agents 
In docs/HW_INSTALL.md around lines 15 to 22, the WARNING block contains a typo
("fo" → "do") and has extra blank lines/multiple spaces after the blockquote
markers causing MD027/MD028 violations; update the sentence to "it will do its
best to install NetAlertX on your system.", remove the stray blank line and any
extra spaces after the ">" markers so the blockquote lines are contiguous and
properly formatted, and ensure the warning text reads clearly without
leading/trailing extra whitespace.

NetAlertX will be installed in `/app` and run on port number `20211`.

Some facts about what and where something will be changed/installed by the HW install setup (may not contain everything!):

- dependencies will be installed from the respective system repos
- required python modules will be installed
- `/app` directory will be deleted and newly created
- `/app` will contain the whole repository (downloaded by `install/install.debian.sh`)
- `/app` will contain the whole repository (downloaded by the install script)
- The default NGINX site `/etc/nginx/sites-enabled/default` will be disabled (sym-link deleted or backed up to `sites-available`)
- `/var/www/html/netalertx` directory will be deleted and newly created
- `/etc/nginx/conf.d/netalertx.conf` will be sym-linked to `/app/install/netalertx.debian.conf`
- `/etc/nginx/conf.d/netalertx.conf` will be sym-linked to the appropriate installer location (depending on your system installer script)
- Some files (IEEE device vendors info, ...) will be created in the directory where the installation script is executed

## Limitations

- No system service is provided. NetAlertX must be started using `/app/install/start.debian.sh`.
- No system service is provided. NetAlertX must be started using `/app/install/<system>/start.<system>.sh`.
- No checks for other running software is done.
- Only tested to work on Debian Bookworm (Debian 12).
- Only tested to work on the system listed in the install directory.
- **EXPERIMENTAL** and not recommended way to install NetAlertX.

## 📥 Installation via CURL

> [!TIP]
> If the below fails try grabbing and installing one of the [previous releases](https://github.com/jokob-sk/NetAlertX/releases) and run the installation from the zip package.

These commands will download the `install.debian12.sh` script from the GitHub repository, make it executable with `chmod`, and then run it using `./install.debian12.sh`.

Make sure you have the necessary permissions to execute the script.


## 📥 Debian 12 (Bookworm)

### Installation via curl
```bash
curl -o install.debian.sh https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/install.debian.sh && sudo chmod +x install.debian.sh && sudo ./install.debian.sh
curl -o install.debian12.sh https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/debian12/install.debian12.sh && sudo chmod +x install.debian12.sh && sudo ./install.debian12.sh
```

## 📥 Installation via WGET
### Installation via wget

```bash
wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/install.debian.sh -O install.debian.sh && sudo chmod +x install.debian.sh && sudo ./install.debian.sh
wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/debian12/install.debian12.sh -O install.debian12.sh && sudo chmod +x install.debian12.sh && sudo ./install.debian12.sh
```

These commands will download the `install.debian.sh` script from the GitHub repository, make it executable with `chmod`, and then run it using `./install.debian.sh`.
## 📥 Ubuntu 24 (Noble Numbat)

Make sure you have the necessary permissions to execute the script.
### Installation via curl
```bash
curl -o install.ubuntu24.sh https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/ubuntu24/install.ubuntu24.sh && sudo chmod +x install.ubuntu24.sh && sudo ./install.ubuntu24.sh
```

### Installation via wget

```bash
wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/ubuntu24/install.ubuntu24.sh -O install.ubuntu24.sh && sudo chmod +x install.ubuntu24.sh && sudo ./install.ubuntu24.sh
```
90 changes: 58 additions & 32 deletions docs/REVERSE_PROXY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,13 @@

> Submitted by amazing [cvc90](https://github.com/cvc90) 🙏


> [!NOTE]
> There are 2 NGINX files for NetAlertX, one for the bare-metal Debian install (`netalertx.debian.conf`), and one for the docker container (`netalertx.template.conf`). Both can be found in the [install](https://github.com/jokob-sk/NetAlertX/tree/main/install) folder. Map, or use, the one appropriate for your setup.
> There are various NGINX config files for NetAlertX, some for the bare-metal install, currently Debian 12 and Ubuntu 24 (`netalertx.conf`), and one for the docker container (`netalertx.template.conf`).
>
> The first one you can find in the respective bare metal installer folder `/app/install/\<system\>/netalertx.conf`.
> The docker one can be found in the [install](https://github.com/jokob-sk/NetAlertX/tree/main/install) folder. Map, or use, the one appropriate for your setup.

<br/>

## NGINX HTTP Configuration (Direct Path)

Expand All @@ -26,9 +30,11 @@

`nginx -s reload` or `systemctl restart nginx`

4. Once NGINX restarts, you should be able to access the proxy website at http://netalertx/
4. Check your config with `nginx -t`. If there are any issues, it will tell you.

<br>
5. Once NGINX restarts, you should be able to access the proxy website at http://netalertx/

<br/>

## NGINX HTTP Configuration (Sub Path)

Expand All @@ -50,13 +56,15 @@
}
```

3. Activate the new website by running the following command:
3. Check your config with `nginx -t`. If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`nginx -s reload` or `systemctl restart nginx`

4. Once NGINX restarts, you should be able to access the proxy website at http://netalertx/netalertx/
5. Once NGINX restarts, you should be able to access the proxy website at http://netalertx/netalertx/

<br>
<br/>

## NGINX HTTP Configuration (Sub Path) with module ngx_http_sub_module

Expand Down Expand Up @@ -86,13 +94,15 @@
}
```

3. Activate the new website by running the following command:
3. Check your config with `nginx -t`. If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`nginx -s reload` or `systemctl restart nginx`

4. Once NGINX restarts, you should be able to access the proxy website at http://netalertx/netalertx/
5. Once NGINX restarts, you should be able to access the proxy website at http://netalertx/netalertx/

<br>
<br/>

**NGINX HTTPS Configuration (Direct Path)**

Expand All @@ -113,13 +123,15 @@
}
```

3. Activate the new website by running the following command:
3. Check your config with `nginx -t`. If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`nginx -s reload` or `systemctl restart nginx`

4. Once NGINX restarts, you should be able to access the proxy website at https://netalertx/
5. Once NGINX restarts, you should be able to access the proxy website at https://netalertx/

<br>
<br/>

**NGINX HTTPS Configuration (Sub Path)**

Expand All @@ -143,13 +155,15 @@
}
```

3. Activate the new website by running the following command:
3. Check your config with `nginx -t`. If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`nginx -s reload` or `systemctl restart nginx`

4. Once NGINX restarts, you should be able to access the proxy website at https://netalertx/netalertx/
5. Once NGINX restarts, you should be able to access the proxy website at https://netalertx/netalertx/

<br>
<br/>

## NGINX HTTPS Configuration (Sub Path) with module ngx_http_sub_module

Expand Down Expand Up @@ -181,13 +195,15 @@
}
```

3. Activate the new website by running the following command:
3. Check your config with `nginx -t`. If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`nginx -s reload` or `systemctl restart nginx`

4. Once NGINX restarts, you should be able to access the proxy website at https://netalertx/netalertx/
5. Once NGINX restarts, you should be able to access the proxy website at https://netalertx/netalertx/

<br>
<br/>

## Apache HTTP Configuration (Direct Path)

Expand All @@ -204,13 +220,15 @@
</VirtualHost>
```

3. Activate the new website by running the following command:
3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`a2ensite netalertx` or `service apache2 reload`

4. Once Apache restarts, you should be able to access the proxy website at http://netalertx/
5. Once Apache restarts, you should be able to access the proxy website at http://netalertx/

<br>
<br/>

## Apache HTTP Configuration (Sub Path)

Expand All @@ -229,13 +247,15 @@
</VirtualHost>
```

3. Activate the new website by running the following command:
3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`a2ensite netalertx` or `service apache2 reload`

4. Once Apache restarts, you should be able to access the proxy website at http://netalertx/
5. Once Apache restarts, you should be able to access the proxy website at http://netalertx/

<br>
<br/>

## Apache HTTPS Configuration (Direct Path)

Expand All @@ -255,13 +275,15 @@
</VirtualHost>
```

3. Activate the new website by running the following command:
3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`a2ensite netalertx` or `service apache2 reload`

4. Once Apache restarts, you should be able to access the proxy website at https://netalertx/
5. Once Apache restarts, you should be able to access the proxy website at https://netalertx/

<br>
<br/>

## Apache HTTPS Configuration (Sub Path)

Expand All @@ -283,11 +305,15 @@
</VirtualHost>
```

3. Activate the new website by running the following command:
3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you.

4. Activate the new website by running the following command:

`a2ensite netalertx` or `service apache2 reload`

4. Once Apache restarts, you should be able to access the proxy website at https://netalertx/netalertx/
5. Once Apache restarts, you should be able to access the proxy website at https://netalertx/netalertx/

<br/>

## Reverse proxy example by using LinuxServer's SWAG container.

Expand Down Expand Up @@ -349,12 +375,13 @@ location ^~ /netalertx/ {
}
```

<br/>

## Traefik

> Submitted by [Isegrimm](https://github.com/Isegrimm) 🙏 (based on this [discussion](https://github.com/jokob-sk/NetAlertX/discussions/449#discussioncomment-7281442))

Asuming the user already has a working Traefik setup, this is what's needed to make NetAlertX work at a URL like www.domain.com/netalertx/.
Assuming the user already has a working Traefik setup, this is what's needed to make NetAlertX work at a URL like www.domain.com/netalertx/.

Note: Everything in these configs assumes '**www.domain.com**' as your domainname and '**section31**' as an arbitrary name for your certificate setup. You will have to substitute these with your own.

Expand Down Expand Up @@ -480,4 +507,3 @@ docker run -d --rm --network=host \
ghcr.io/jokob-sk/netalertx:latest

```

7 changes: 4 additions & 3 deletions install/install.debian.sh → install/debian12/install.debian12.sh
100755 → 100644
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
#!/usr/bin/env bash

# 🛑 Important: This is only used for the bare-metal install 🛑
# Update /install/start.debian.sh in most cases is preferred
# Update /install/start.debian12.sh in most cases is preferred

echo "---------------------------------------------------------"
echo "[INSTALL] Run install.debian.sh"
echo "[INSTALL] Run install.debian12.sh"
echo "---------------------------------------------------------"

# Set environment variables
Expand Down Expand Up @@ -35,4 +35,5 @@ if [ ! -f $INSTALL_DIR/front/buildtimestamp.txt ]; then
fi

# Start NetAlertX
"$INSTALL_DIR/install/start.debian.sh"
chmod +x "$INSTALL_DIR/install/debian12/start.debian12.sh"
"$INSTALL_DIR/install/debian12/start.debian12.sh"
5 changes: 2 additions & 3 deletions install/install_dependencies.debian.sh → ...debian12/install_dependencies.debian12.sh
100755 → 100644
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env bash

echo "---------------------------------------------------------"
echo "[INSTALL] Run install_dependencies.debian.sh"
echo "[INSTALL] Run install_dependencies.debian12.sh"
echo "---------------------------------------------------------"

# ❗ IMPORTANT - if you modify this file modify the root Dockerfile as well ❗
Expand All @@ -23,12 +23,11 @@ sudo apt-get install nginx nginx-core mtr php-fpm php8.2-fpm php-cli php8.2 php8
sudo phpenmod -v 8.2 sqlite3

# setup virtual python environment so we can use pip3 to install packages
apt-get install python3.11-venv -y
apt-get install python3-venv -y
python3 -m venv myenv
source myenv/bin/activate

Comment on lines 25 to 29
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Virtualenv created in an indeterminate directory.

Because this script can be invoked from anywhere, creating “myenv” in CWD is brittle. Create and activate the venv relative to the script’s own directory.

-# setup virtual python environment so we can use pip3 to install packages
-apt-get install python3-venv -y
-python3 -m venv myenv
-source myenv/bin/activate
+# setup virtual python environment so we can use pip3 to install packages
+apt-get install -y python3-venv
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+python3 -m venv "${SCRIPT_DIR}/.venv"
+source "${SCRIPT_DIR}/.venv/bin/activate"

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In install/debian12/install_dependencies.debian12.sh around lines 25-29, the
script creates the virtualenv in the current working directory ("myenv"), which
is brittle; change it to create and activate the venv relative to the script
file (not CWD). Resolve this by computing the script directory (the directory of
"${BASH_SOURCE[0]}"), create the venv inside that directory (e.g., a subpath
like "$SCRIPT_DIR/.venv" or similar), and source the activate script from that
absolute path so the venv location is deterministic regardless of where the
script is invoked.

update-alternatives --install /usr/bin/python python /usr/bin/python3 10

# install packages thru pip3
pip3 install openwrt-luci-rpc asusrouter asyncio aiohttp graphene flask flask-cors unifi-sm-api tplink-omada-client wakeonlan pycryptodome requests paho-mqtt scapy cron-converter pytz json2table dhcp-leases pyunifi speedtest-cli chardet python-nmap dnspython librouteros yattag git+https://github.com/foreign-sub/aiofreepybox.git

6 changes: 3 additions & 3 deletions install/netalertx.debian.conf → install/debian12/netalertx.conf
100755 → 100644
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ server {
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_connect_timeout 75;
fastcgi_send_timeout 600;
fastcgi_read_timeout 600;
}
fastcgi_send_timeout 600;
fastcgi_read_timeout 600;
}
}
Loading