jokob-sk/netalertx -> netalertx/netalertx

Signed-off-by: jokob-sk <jokob.sk@gmail.com>
This commit is contained in:
jokob-sk
2026-02-04 21:21:05 +11:00
parent 984b5cd780
commit 76d37edc63
15 changed files with 63 additions and 53 deletions

View File

@@ -56,14 +56,14 @@ docker run -d \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \ -e PORT=20211 \
-e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \ -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
ghcr.io/jokob-sk/netalertx:latest ghcr.io/netalertx/netalertx:latest
``` ```
Note: Your `/local_data_dir` should contain a `config` and `db` folder. Note: Your `/local_data_dir` should contain a `config` and `db` folder.
To deploy a containerized instance directly from the source repository, execute the following BASH sequence: To deploy a containerized instance directly from the source repository, execute the following BASH sequence:
```bash ```bash
git clone https://github.com/jokob-sk/NetAlertX.git git clone https://github.com/netalertx/NetAlertX.git
cd NetAlertX cd NetAlertX
docker compose up --force-recreate --build docker compose up --force-recreate --build
# To customize: edit docker-compose.yaml and run that last command again # To customize: edit docker-compose.yaml and run that last command again

View File

@@ -21,7 +21,7 @@ docker run \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \ -e PORT=20211 \
-e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \ -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
ghcr.io/jokob-sk/netalertx:latest ghcr.io/netalertx/netalertx:latest
``` ```
@@ -34,7 +34,7 @@ Note: Your `/local_data_dir` should contain a `config` and `db` folder.
If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is: If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is:
`ghcr.io/jokob-sk/netalertx-dev:latest` `ghcr.io/netalertx/netalertx-dev:latest`
> ⚠ Please backup your DB and config beforehand! > ⚠ Please backup your DB and config beforehand!

View File

@@ -8,26 +8,26 @@ Before starting development, please review the following guidelines.
### Priority Order (Highest to Lowest) ### Priority Order (Highest to Lowest)
1. 🔼 Fixing core bugs that lack workarounds 1. 🔼 Fixing core bugs that lack workarounds
2. 🔵 Adding core functionality that unlocks other features (e.g., plugins) 2. 🔵 Adding core functionality that unlocks other features (e.g., plugins)
3. 🔵 Refactoring to enable faster development 3. 🔵 Refactoring to enable faster development
4. 🔽 UI improvements (PRs welcome, but low priority) 4. 🔽 UI improvements (PRs welcome, but low priority)
### Design Philosophy ### Design Philosophy
The application architecture is designed for extensibility and maintainability. It relies heavily on configuration manifests via plugins and settings to dynamically build the UI and populate the application with data from various sources. The application architecture is designed for extensibility and maintainability. It relies heavily on configuration manifests via plugins and settings to dynamically build the UI and populate the application with data from various sources.
For details, see: For details, see:
- [Plugins Development](PLUGINS_DEV.md) (includes video) - [Plugins Development](PLUGINS_DEV.md) (includes video)
- [Settings System](SETTINGS_SYSTEM.md) - [Settings System](SETTINGS_SYSTEM.md)
Focus on **core functionality** and integrate with existing tools rather than reinventing the wheel. Focus on **core functionality** and integrate with existing tools rather than reinventing the wheel.
Examples: Examples:
- Using **Apprise** for notifications instead of implementing multiple separate gateways - Using **Apprise** for notifications instead of implementing multiple separate gateways
- Implementing **regex-based validation** instead of one-off validation for each setting - Implementing **regex-based validation** instead of one-off validation for each setting
> [!NOTE] > [!NOTE]
> UI changes have lower priority. PRs are welcome, but please keep them **small and focused**. > UI changes have lower priority. PRs are welcome, but please keep them **small and focused**.
## Development Environment Set Up ## Development Environment Set Up
@@ -43,7 +43,7 @@ The following steps will guide you to set up your environment for local developm
### 1. Download the code: ### 1. Download the code:
- `mkdir /development` - `mkdir /development`
- `cd /development && git clone https://github.com/jokob-sk/NetAlertX.git` - `cd /development && git clone https://github.com/netalertx/NetAlertX.git`
### 2. Create a DEV .env_dev file ### 2. Create a DEV .env_dev file
@@ -59,13 +59,13 @@ PORT=22222 # make sure this port is unique on your whole network
DEV_LOCATION=/development/NetAlertX DEV_LOCATION=/development/NetAlertX
APP_DATA_LOCATION=/volume/docker_appdata APP_DATA_LOCATION=/volume/docker_appdata
# Make sure your GRAPHQL_PORT setting has a port that is unique on your whole host network # Make sure your GRAPHQL_PORT setting has a port that is unique on your whole host network
APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"} APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"}
# ALWAYS_FRESH_INSTALL=true # uncommenting this will always delete the content of /config and /db dirs on boot to simulate a fresh install # ALWAYS_FRESH_INSTALL=true # uncommenting this will always delete the content of /config and /db dirs on boot to simulate a fresh install
``` ```
### 3. Create /db and /config dirs ### 3. Create /db and /config dirs
Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`. Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`.
- `mkdir /volume/docker_appdata/netalertx` - `mkdir /volume/docker_appdata/netalertx`
- `mkdir /volume/docker_appdata/netalertx/db` - `mkdir /volume/docker_appdata/netalertx/db`
@@ -82,9 +82,9 @@ You can then modify the python script without restarting/rebuilding the containe
## Tips ## Tips
A quick cheat sheet of useful commands. A quick cheat sheet of useful commands.
### Removing the container and image ### Removing the container and image
A command to stop, remove the container and the image (replace `netalertx` and `netalertx-netalertx` with the appropriate values) A command to stop, remove the container and the image (replace `netalertx` and `netalertx-netalertx` with the appropriate values)
@@ -98,23 +98,23 @@ Most code changes can be tested without rebuilding the container. When working o
![image](./img/DEV/Maintenance_Logs_Restart_server.png) ![image](./img/DEV/Maintenance_Logs_Restart_server.png)
2. If above doesn't work, SSH into the container and kill & restart the main script loop 2. If above doesn't work, SSH into the container and kill & restart the main script loop
- `sudo docker exec -it netalertx /bin/bash` - `sudo docker exec -it netalertx /bin/bash`
- `pkill -f "python /app/server" && python /app/server & ` - `pkill -f "python /app/server" && python /app/server & `
3. If none of the above work, restart the docker container. 3. If none of the above work, restart the docker container.
- This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted. - This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted.
## Contributing & Pull Requests ## Contributing & Pull Requests
### Before submitting a PR, please ensure: ### Before submitting a PR, please ensure:
✔ Changes are **backward-compatible** with existing installs. ✔ Changes are **backward-compatible** with existing installs.
✔ No unnecessary changes are made. ✔ No unnecessary changes are made.
✔ New features are **reusable**, not narrowly scoped. ✔ New features are **reusable**, not narrowly scoped.
✔ Features are implemented via **plugins** if possible. ✔ Features are implemented via **plugins** if possible.
### Mandatory Test Cases ### Mandatory Test Cases
@@ -122,15 +122,15 @@ Most code changes can be tested without rebuilding the container. When working o
- Existing DB/config compatibility. - Existing DB/config compatibility.
- Notification testing: - Notification testing:
- Email - Email
- Apprise (e.g., Telegram) - Apprise (e.g., Telegram)
- Webhook (e.g., Discord) - Webhook (e.g., Discord)
- MQTT (e.g., Home Assistant) - MQTT (e.g., Home Assistant)
- Updating Settings and their persistence. - Updating Settings and their persistence.
- Updating a Device - Updating a Device
- Plugin functionality. - Plugin functionality.
- Error log inspection. - Error log inspection.
> [!NOTE] > [!NOTE]
> Always run all available tests as per the [Testing documentation](API_TESTS.md). > Always run all available tests as per the [Testing documentation](API_TESTS.md).

View File

@@ -17,7 +17,7 @@ services:
netalertx: netalertx:
#use an environmental variable to set host networking mode if needed #use an environmental variable to set host networking mode if needed
container_name: netalertx # The name when you docker contiainer ls container_name: netalertx # The name when you docker contiainer ls
image: ghcr.io/jokob-sk/netalertx:latest image: ghcr.io/netalertx/netalertx:latest
network_mode: ${NETALERTX_NETWORK_MODE:-host} # Use host networking for ARP scanning and other services network_mode: ${NETALERTX_NETWORK_MODE:-host} # Use host networking for ARP scanning and other services
read_only: true # Make the container filesystem read-only read_only: true # Make the container filesystem read-only

View File

@@ -31,7 +31,7 @@ docker run -d --rm --network=host \
--tmpfs /tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700 \ --tmpfs /tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700 \
-e PORT=20211 \ -e PORT=20211 \
-e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \ -e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \
ghcr.io/jokob-sk/netalertx:latest ghcr.io/netalertx/netalertx:latest
``` ```
> Runtime UID/GID: The image defaults to a service user `netalertx` (UID/GID 20211). A separate readonly lock owner also uses UID/GID 20211 for 004/005 immutability. You can override the runtime UID/GID at build (ARG) or run (`--user` / compose `user:`) but must align writable mounts (`/data`, `/tmp*`) and tmpfs `uid/gid` to that choice. > Runtime UID/GID: The image defaults to a service user `netalertx` (UID/GID 20211). A separate readonly lock owner also uses UID/GID 20211 for 004/005 immutability. You can override the runtime UID/GID at build (ARG) or run (`--user` / compose `user:`) but must align writable mounts (`/data`, `/tmp*`) and tmpfs `uid/gid` to that choice.

View File

@@ -35,9 +35,9 @@ services:
netalertx: netalertx:
container_name: netalertx container_name: netalertx
# Use this line for stable release # Use this line for stable release
image: "ghcr.io/jokob-sk/netalertx:latest" image: "ghcr.io/netalertx/netalertx:latest"
# Or, use this for the latest development build # Or, use this for the latest development build
# image: "ghcr.io/jokob-sk/netalertx-dev:latest" # image: "ghcr.io/netalertx/netalertx-dev:latest"
network_mode: "host" network_mode: "host"
restart: unless-stopped restart: unless-stopped
cap_drop: # Drop all capabilities for enhanced security cap_drop: # Drop all capabilities for enhanced security
@@ -48,7 +48,7 @@ services:
- NET_BIND_SERVICE - NET_BIND_SERVICE
- CHOWN - CHOWN
- SETUID - SETUID
- SETGID - SETGID
volumes: volumes:
- ${APP_FOLDER}/netalertx/config:/data/config - ${APP_FOLDER}/netalertx/config:/data/config
- ${APP_FOLDER}/netalertx/db:/data/db - ${APP_FOLDER}/netalertx/db:/data/db

View File

@@ -44,7 +44,7 @@ Use the following Compose snippet to deploy NetAlertX with a **static LAN IP** a
```yaml ```yaml
services: services:
netalertx: netalertx:
image: ghcr.io/jokob-sk/netalertx:latest image: ghcr.io/netalertx/netalertx:latest
... ...
networks: networks:
swarm-ipvlan: swarm-ipvlan:

View File

@@ -32,12 +32,22 @@ NetAlertX is a lightweight, flexible platform for monitoring networks, tracking
![Event-Driven Alerts](./img/FEATURES/Event-Driven_Alerts.png) ![Event-Driven Alerts](./img/FEATURES/Event-Driven_Alerts.png)
- **Real-Time Notifications**: Receive immediate alerts for new devices, disconnected devices, or unexpected changes. - **Real-Time Notifications**: Receive immediate alerts for new devices, disconnected devices, or unexpected changes.
- **Customizable Triggers**: Define rules based on device type, IP ranges, presence, or other network parameters. - **Customizable Filters and Rules**: Define rules based on device type, IP ranges, presence, or other network parameters.
- **Alert Deduplication & Suppression**: Avoid unnecessary noise with smart alert handling. - **Alert Deduplication & Suppression**: Avoid unnecessary noise with smart alert handling.
- **Historical Logs**: Maintain a complete timeline of network events for review and reporting. - **Historical Logs**: Maintain a complete timeline of network events for review and reporting.
--- ---
## Workflows for implementing Business rules
![orkflows](./img/WORKFLOWS/workflows.png)
- **Custom rules**: Cretae custom flows and update device information based to scan results.
- **Customizable Triggers**: Define rules based on any device data, including device type, IP ranges, presence, or other network parameters.
- **Automated Updates**: Automate repetitive tasks, making network management more efficient.
---
## Multi-Channel Notification ## Multi-Channel Notification
![Multi-Channel Notification](./img/FEATURES/Multi-Channel_Notifications.png) ![Multi-Channel Notification](./img/FEATURES/Multi-Channel_Notifications.png)

View File

@@ -12,7 +12,7 @@ docker run --rm --network=host \
-v /etc/localtime:/etc/localtime:ro \ -v /etc/localtime:/etc/localtime:ro \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \ -e PORT=20211 \
ghcr.io/jokob-sk/netalertx:latest ghcr.io/netalertx/netalertx:latest
``` ```
> [!WARNING] > [!WARNING]
@@ -70,7 +70,7 @@ If you use a custom `PUID` (e.g. `0`) and `GUID` (e.g. `100`) make sure you also
docker run -it --rm --name netalertx --user "0" \ docker run -it --rm --name netalertx --user "0" \
-v /local_data_dir:/data \ -v /local_data_dir:/data \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
ghcr.io/jokob-sk/netalertx:latest ghcr.io/netalertx/netalertx:latest
``` ```
2. Wait for logs showing **permissions being fixed**. The container will then **hang intentionally**. 2. Wait for logs showing **permissions being fixed**. The container will then **hang intentionally**.
@@ -95,7 +95,7 @@ docker run -it --rm --name netalertx --user "0" \
services: services:
netalertx: netalertx:
container_name: netalertx container_name: netalertx
image: "ghcr.io/jokob-sk/netalertx" image: "ghcr.io/netalertx/netalertx"
network_mode: "host" network_mode: "host"
cap_drop: # Drop all capabilities for enhanced security cap_drop: # Drop all capabilities for enhanced security
- ALL - ALL

View File

@@ -318,7 +318,7 @@ As per user feedback, weve re-introduced the ability to control which user th
services: services:
netalertx: netalertx:
container_name: netalertx container_name: netalertx
image: "ghcr.io/jokob-sk/netalertx" image: "ghcr.io/netalertx/netalertx"
network_mode: "host" network_mode: "host"
cap_drop: cap_drop:
- ALL - ALL

View File

@@ -80,9 +80,9 @@ services:
netalertx: netalertx:
container_name: netalertx container_name: netalertx
# Use this line for the stable release # Use this line for the stable release
image: "ghcr.io/jokob-sk/netalertx:latest" image: "ghcr.io/netalertx/netalertx:latest"
# Or use this line for the latest development build # Or use this line for the latest development build
# image: "ghcr.io/jokob-sk/netalertx-dev:latest" # image: "ghcr.io/netalertx/netalertx-dev:latest"
network_mode: "host" network_mode: "host"
restart: unless-stopped restart: unless-stopped

View File

@@ -39,7 +39,7 @@ You can specify the DNS server in the docker-compose to improve name resolution
services: services:
netalertx: netalertx:
container_name: netalertx container_name: netalertx
image: "ghcr.io/jokob-sk/netalertx:latest" image: "ghcr.io/netalertx/netalertx:latest"
... ...
dns: # specifying the DNS servers used for the container dns: # specifying the DNS servers used for the container
- 10.8.0.1 - 10.8.0.1

View File

@@ -37,8 +37,8 @@ services:
netalertx: netalertx:
container_name: netalertx container_name: netalertx
# use the below line if you want to test the latest dev image # use the below line if you want to test the latest dev image
# image: "ghcr.io/jokob-sk/netalertx-dev:latest" # image: "ghcr.io/netalertx/netalertx-dev:latest"
image: "ghcr.io/jokob-sk/netalertx:latest" image: "ghcr.io/netalertx/netalertx:latest"
network_mode: "host" network_mode: "host"
restart: unless-stopped restart: unless-stopped
cap_drop: # Drop all capabilities for enhanced security cap_drop: # Drop all capabilities for enhanced security

View File

@@ -57,7 +57,7 @@
virtualisation.oci-containers = { virtualisation.oci-containers = {
containers = { containers = {
netalertx = { netalertx = {
image = "ghcr.io/jokob-sk/netalertx:${cfg.imageTag}"; image = "ghcr.io/netalertx/netalertx:${cfg.imageTag}";
autoStart = true; autoStart = true;
extraOptions = [ extraOptions = [
"--network=host" "--network=host"

View File

@@ -185,7 +185,7 @@ printf "%b\n" "${GREEN}[INSTALLING] ${RESET}Cloning app
printf "%b\n" "--------------------------------------------------------------------------" printf "%b\n" "--------------------------------------------------------------------------"
mkdir -p "$INSTALL_DIR" mkdir -p "$INSTALL_DIR"
git clone https://github.com/jokob-sk/NetAlertX.git "$INSTALL_DIR/" git clone https://github.com/netalertx/NetAlertX.git "$INSTALL_DIR/"
if [ ! -f "$INSTALL_DIR/front/buildtimestamp.txt" ]; then if [ ! -f "$INSTALL_DIR/front/buildtimestamp.txt" ]; then
date +%s > "$INSTALL_DIR/front/buildtimestamp.txt" date +%s > "$INSTALL_DIR/front/buildtimestamp.txt"