vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-07 09:36:05 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

/data and /tmp standarization

Browse Source
This commit is contained in:
Adam Outler
2025-11-04 22:26:35 +00:00
parent 90a07c61eb
commit 5b871865db
250 changed files with 7462 additions and 4940 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/API_OLD.md
View File

@@ -141,7 +141,7 @@ The endpoints are updated when objects in the API endpoints are changed.
### Location of the endpoints
In the container, these files are located under the `/app/api/` folder. You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
In the container, these files are located under the API directory (default: `/tmp/api/`, configurable via `NETALERTX_API` environment variable). You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
### Available endpoints
@@ -332,7 +332,7 @@ Grafana template sample: [Download json](./samples/API/Grafana_Dashboard.json)
## API Endpoint: /log files
This API endpoint retrieves files from the `/app/log` folder.
This API endpoint retrieves files from the `/tmp/log` folder.
- Endpoint URL: `php/server/query_logs.php?file=<file name>`
- Host: `same as front end (web ui)`
@@ -357,7 +357,7 @@ This API endpoint retrieves files from the `/app/log` folder.
## API Endpoint: /config files
To retrieve files from the `/app/config` folder.
To retrieve files from the `/data/config` folder.
- Endpoint URL: `php/server/query_config.php?file=<file name>`
- Host: `same as front end (web ui)`

26
docs/BACKUPS.md
View File

@@ -1,7 +1,7 @@
# Backing Things Up
> [!NOTE]
> To back up 99% of your configuration, back up at least the `/app/config` folder.
> To back up 99% of your configuration, back up at least the `/data/config` folder.
> Database definitions can change between releases, so the safest method is to restore backups using the **same app version** they were taken from, then upgrade incrementally.
---
@@ -25,7 +25,7 @@ Understanding where your data is stored helps you plan your backup strategy.
### Core Configuration
Stored in `/app/config/app.conf`.
Stored in `/data/config/app.conf`.
This includes settings for:
* Notifications
@@ -37,7 +37,7 @@ This includes settings for:
### Device Data
Stored in `/app/config/devices_<timestamp>.csv` or `/app/config/devices.csv`, created by the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup).
Stored in `/data/config/devices_<timestamp>.csv` or `/data/config/devices.csv`, created by the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup).
Contains:
* Device names, icons, and categories
@@ -46,7 +46,7 @@ Contains:
### Historical Data
Stored in `/app/db/app.db` (see [Database Overview](./DATABASE.md)).
Stored in `/data/db/app.db` (see [Database Overview](./DATABASE.md)).
Contains:
* Plugin data and historical entries
@@ -77,9 +77,9 @@ You can also download the `app.conf` and `devices.csv` files from the **Maintena
### 💾 What to Back Up
* `/app/db/app.db` (uncorrupted)
* `/app/config/app.conf`
* `/app/config/workflows.json`
* `/data/db/app.db` (uncorrupted)
* `/data/config/app.conf`
* `/data/config/workflows.json`
### 📥 How to Restore
@@ -93,14 +93,14 @@ Map these files into your container as described in the [Setup documentation](ht
### 💾 What to Back Up
* `/app/config/app.conf`
* `/app/config/workflows.json`
* `/app/config/devices_<timestamp>.csv` (rename to `devices.csv` during restore)
* `/data/config/app.conf`
* `/data/config/workflows.json`
* `/data/config/devices_<timestamp>.csv` (rename to `devices.csv` during restore)
### 📥 How to Restore
1. Copy `app.conf` and `workflows.json` into `/app/config/`
2. Rename and place `devices_<timestamp>.csv` → `/app/config/devices.csv`
1. Copy `app.conf` and `workflows.json` into `/data/config/`
2. Rename and place `devices_<timestamp>.csv` → `/data/config/devices.csv`
3. Restore via the **Maintenance** section under *Devices → Bulk Editing*
This recovers nearly all configuration, workflows, and device metadata.
@@ -157,6 +157,6 @@ For users running NetAlertX via Docker, you can back up or restore directly from
## Summary
* Back up `/app/config` for configuration and devices; `/app/db` for history
* Back up `/data/config` for configuration and devices; `/data/db` for history
* Keep regular backups, especially before upgrades
* For Docker setups, use the lightweight `alpine`-based backup method for consistency and portability

8
docs/COMMON_ISSUES.md
View File

@@ -14,9 +14,9 @@ The app uses the MAC address as an unique identifier for devices. If a new MAC i
Make sure you [File permissions](./FILE_PERMISSIONS.md) are set correctly.
* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/app/log`.
* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /app/db/app.db`.
* If still facing issues, try to map the app.db file (⚠ not folder) to `:/app/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details)
* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/tmp/log`.
* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /data/db/app.db`.
* If still facing issues, try to map the app.db file (⚠ not folder) to `:/data/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details)
### Container restarts / crashes
@@ -49,7 +49,7 @@ Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your d
### Losing my settings and devices after an update
If you lose your devices and/or settings after an update that means you don't have the `/app/db` and `/app/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command.
If you lose your devices and/or settings after an update that means you don't have the `/data/db` and `/data/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command.
### The application is slow

2
docs/DEBUG_PHP.md
View File

@@ -27,7 +27,7 @@ Sometimes, the UI might not be accessible. In that case, you can access the logs
3. **Check the PHP application error log:**
```bash
cat /app/log/app.php_errors.log
cat /tmp/log/app.php_errors.log
```
These logs will help identify syntax issues, fatal errors, or startup problems when the UI fails to load properly.

4
docs/DEBUG_TIPS.md
View File

@@ -14,8 +14,8 @@ Start the container via the **terminal** with a command similar to this one:
```bash
docker run --rm --network=host \
-v local/path/netalertx/config:/app/config \
-v local/path/netalertx/db:/app/db \
-v local/path/netalertx/config:/data/config \
-v local/path/netalertx/db:/data/db \
-e TZ=Europe/Berlin \
-e PORT=20211 \
ghcr.io/jokob-sk/netalertx:latest

83
docs/DOCKER_COMPOSE.md
View File

@@ -31,61 +31,46 @@ services:
- NET_BIND_SERVICE # Required to bind to privileged ports (nbtscan)
volumes:
- type: volume # Persistent Docker-managed Named Volume for storage of config files
source: netalertx_config # the default name of the volume is netalertx_config
target: /app/config # inside the container mounted to /app/config
read_only: false # writable volume
# Example custom local folder called /home/user/netalertx_config
# - type: bind
# source: /home/user/netalertx_config
# target: /app/config
# read_only: false
# ... or use the alternative format
# - /home/user/netalertx_config:/app/config:rw
- type: volume # NetAlertX Database partiton
source: netalertx_db
target: /app/db
- type: volume # Persistent Docker-managed named volume for config + database
source: netalertx_data
target: /data # `/data/config` and `/data/db` live inside this mount
read_only: false
- type: volume # Future proof mount. During the migration to a
source: netalertx_data # future version, app and db will be migrated to
target: /data # the /data partition. This will reduce the
read_only: false # overhead and pain in the upcoming migration.
# Example custom local folder called /home/user/netalertx_data
# - type: bind
# source: /home/user/netalertx_data
# target: /data
# read_only: false
# ... or use the alternative format
# - /home/user/netalertx_data:/data:rw
- type: bind # Bind mount for timezone consistency
source: /etc/localtime
source: /etc/localtime # Alternatively add environment TZ: America/New York
target: /etc/localtime
read_only: true
# Mount your DHCP server file into NetAlertX for a plugin to access
# - path/on/host/to/dhcp.file:/resources/dhcp.file
# Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
# - /path/on/host/log:/app/log
# Tempfs mounts for writable directories in a read-only container and improve system performance
# All mounts have noexec,nosuid,nodev for security purposes no devices, no suid/sgid and no execution of binaries
# async where possible for performance, sync where required for correctness
# tmpfs mount consolidates writable state for a read-only container and improves performance
# uid=20211 and gid=20211 is the netalertx user inside the container
# mode=1700 gives rwx------ permissions to the netalertx user only
# mode=1700 grants rwx------ permissions to the netalertx user only
tmpfs:
# Speed up logging. This can be commented out to retain logs between container restarts
- "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# Speed up API access as frontend/backend API is very chatty
- "/app/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,sync,noatime,nodiratime"
# Required for customization of the nginx listen addr/port without rebuilding the container
- "/services/config/nginx/conf.active:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# /services/config/nginx/conf.d is required for nginx and php to start
- "/services/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# /tmp is required by php for session save this should be reworked to /services/run/tmp
- "/tmp:uid=2Key-Value Pairs: 20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# Comment out to retain logs between container restarts - this has a server performance impact.
- "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# Retain logs - comment out tmpfs /tmp if you want to retain logs between container restarts
# Please note if you remove the /tmp mount, you must create and maintain sub-folder mounts.
# - /path/on/host/log:/tmp/log
# - "/tmp/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# - "/tmp/nginx:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# - "/tmp/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
environment:
LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} # Listen for connections on all interfaces
PORT: ${PORT:-20211} # Application port
GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} # GraphQL API port (passed into APP_CONF_OVERRIDE at runtime)
NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0} # 0=kill all services and restart if any dies. 1 keeps running dead services.
# NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0} # 0=kill all services and restart if any dies. 1 keeps running dead services.
# Resource limits to prevent resource exhaustion
mem_limit: 2048m # Maximum memory usage
@@ -101,10 +86,8 @@ services:
# Always restart the container unless explicitly stopped
restart: unless-stopped
volumes: # Persistent volumes for configuration and database storage
netalertx_config: # Configuration files
netalertx_db: # Database files
netalertx_data: # For future config/db upgrade
volumes: # Persistent volume for configuration and database storage
netalertx_data:
```
Run or re-run it:
@@ -163,8 +146,8 @@ However, if you prefer to have direct, file-level access to your configuration f
```yaml
...
volumes:
- netalertx_config:/app/config:rw #short-form volume (no /path is a short volume)
- netalertx_db:/app/db:rw
- netalertx_config:/data/config:rw #short-form volume (no /path is a short volume)
- netalertx_db:/data/db:rw
...
```
@@ -174,14 +157,14 @@ Make sure to replace `/home/adam/netalertx-files` with your actual path. The for
```yaml
...
volumes:
# - netalertx_config:/app/config:rw
# - netalertx_db:/app/db:rw
- /home/adam/netalertx-files/config:/app/config:rw
- /home/adam/netalertx-files/db:/app/db:rw
# - netalertx_config:/data/config:rw
# - netalertx_db:/data/db:rw
- /home/adam/netalertx-files/config:/data/config:rw
- /home/adam/netalertx-files/db:/data/db:rw
...
```
Now, any files created by NetAlertX in `/app/config` will appear in your `/home/adam/netalertx-files/config` folder.
Now, any files created by NetAlertX in `/data/config` will appear in your `/home/adam/netalertx-files/config` folder.
This same method works for mounting other things, like custom plugins or enterprise NGINX files, as shown in the commented-out examples in the baseline file.

16
docs/DOCKER_INSTALLATION.md
View File

@@ -25,9 +25,9 @@ Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and scree
```yaml
docker run -d --rm --network=host \
-v local_path/config:/app/config \
-v local_path/db:/app/db \
--mount type=tmpfs,target=/app/api \
-v local_path/config:/data/config \
-v local_path/db:/data/db \
--mount type=tmpfs,target=/tmp/api \
-e PUID=200 -e PGID=300 \
-e TZ=Europe/Berlin \
-e PORT=20211 \
@@ -58,10 +58,10 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
| Required | Path | Description |
| :------------- | :------------- | :-------------|
| ✅ | `:/app/config` | Folder which will contain the `app.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files |
| ✅ | `:/app/db` | Folder which will contain the `app.db` database file |
| | `:/app/log` | Logs folder useful for debugging if you have issues setting up the container |
| | `:/app/api` | A simple [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files. |
| ✅ | `:/data/config` | Folder which will contain the `app.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files |
| ✅ | `:/data/db` | Folder which will contain the `app.db` database file |
| | `:/tmp/log` | Logs folder useful for debugging if you have issues setting up the container |
| | `:/tmp/api` | A simple [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable. |
| | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). |
| | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REVERSE_DNS.md). |
@@ -70,7 +70,7 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
### Initial setup
- If unavailable, the app generates a default `app.conf` and `app.db` file on the first run.
- The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/back) in the `/app/config/` folder directly
- The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/back) in the `/data/config/` folder directly
#### Setting up scanners

12
docs/DOCKER_MAINTENANCE.md
View File

@@ -51,13 +51,13 @@ You want to edit your `app.conf` and other configuration files directly from you
volumes:
# - type: volume
# source: netalertx_config
# target: /app/config
# target: /data/config
# read_only: false
...
# Example custom local folder called /data/netalertx_config
- type: bind
source: /data/netalertx_config
target: /app/config
target: /data/config
read_only: false
...
```
@@ -70,7 +70,7 @@ You want to edit your `app.conf` and other configuration files directly from you
### About This Method
This replaces the Docker-managed volume with a "bind mount." This is a direct mapping between a folder on your host computer (`/data/netalertx_config`) and a folder inside the container (`/app/config`), allowing you to edit the files directly.
This replaces the Docker-managed volume with a "bind mount." This is a direct mapping between a folder on your host computer (`/data/netalertx_config`) and a folder inside the container (`/data/config`), allowing you to edit the files directly.
---
@@ -97,13 +97,13 @@ You are currently using a local folder (bind mount) for your configuration (e.g.
volumes:
- type: volume
source: netalertx_config
target: /app/config
target: /data/config
read_only: false
...
# Example custom local folder called /data/netalertx_config
# - type: bind
# source: /data/netalertx_config
# target: /app/config
# target: /data/config
# read_only: false
...
```
@@ -149,7 +149,7 @@ You need to override the default Nginx configuration to add features like LDAP,
```yaml
...
# Use a custom Enterprise-configured nginx config for ldap or other settings
- /data/my-netalertx.conf:/services/config/nginx/conf.active/netalertx.conf:ro
- /data/my-netalertx.conf:/tmp/nginx/active-config/netalertx.conf:ro
...
```
4. Restart the container:

10
docs/DOCKER_PORTAINER.md
View File

@@ -45,18 +45,18 @@ services:
restart: unless-stopped
volumes:
- ${APP_FOLDER}/netalertx/config:/app/config
- ${APP_FOLDER}/netalertx/db:/app/db
- ${APP_FOLDER}/netalertx/config:/data/config
- ${APP_FOLDER}/netalertx/db:/data/db
# Optional: logs (useful for debugging setup issues, comment out for performance)
- ${APP_FOLDER}/netalertx/log:/app/log
- ${APP_FOLDER}/netalertx/log:/tmp/log
# API storage options:
# (Option 1) tmpfs (default, best performance)
- type: tmpfs
target: /app/api
target: /tmp/api
# (Option 2) bind mount (useful for debugging)
# - ${APP_FOLDER}/netalertx/api:/app/api
# - ${APP_FOLDER}/netalertx/api:/tmp/api
environment:
- TZ=${TZ}

6
docs/DOCKER_SWARM.md
View File

@@ -44,9 +44,9 @@ services:
ports:
- 20211:20211
volumes:
- /mnt/YOUR_SERVER/netalertx/config:/app/config:rw
- /mnt/YOUR_SERVER/netalertx/db:/netalertx/app/db:rw
- /mnt/YOUR_SERVER/netalertx/logs:/netalertx/app/log:rw
- /mnt/YOUR_SERVER/netalertx/config:/data/config:rw
- /mnt/YOUR_SERVER/netalertx/db:/netalertx/data/db:rw
- /mnt/YOUR_SERVER/netalertx/logs:/netalertx/tmp/log:rw
environment:
- TZ=Europe/London
- PORT=20211

30
docs/FILE_PERMISSIONS.md
View File

@@ -11,13 +11,15 @@ NetAlertX requires certain paths to be writable at runtime. These paths should b
| Path | Purpose | Notes |
| ------------------------------------ | ----------------------------------- | ------------------------------------------------------ |
| `/app/config` | Application configuration | Persistent volume recommended |
| `/app/db` | Database files | Persistent volume recommended |
| `/app/log` | Logs | Can be `tmpfs` for speed or host volume to retain logs |
| `/app/api` | API cache | Use `tmpfs` for faster access |
| `/services/config/nginx/conf.active` | Active nginx configuration override | `tmpfs` recommended or customized file mounted |
| `/services/run` | Runtime directories for nginx & PHP | `tmpfs` required |
| `/tmp` | PHP session save directory | `tmpfs` required |
| `/data/config` | Application configuration | Persistent volume recommended |
| `/data/db` | Database files | Persistent volume recommended |
| `/tmp/log` | Logs | Lives under `/tmp`; optional host bind to retain logs |
| `/tmp/api` | API cache | Subdirectory of `/tmp` |
| `/tmp/nginx/active-config` | Active nginx configuration override | Mount `/tmp` (or override specific file) |
| `/tmp/run` | Runtime directories for nginx & PHP | Subdirectory of `/tmp` |
| `/tmp` | PHP session save directory | Backed by `tmpfs` for runtime writes |
> Mounting `/tmp` as `tmpfs` automatically covers all of its subdirectories (`log`, `api`, `run`, `nginx/active-config`, etc.).
> All these paths will have **UID 20211 / GID 20211** inside the container. Files on the host will appear owned by `20211:20211`.
@@ -33,8 +35,8 @@ Sometimes, permission issues arise if your existing host directories were create
```bash
docker run -it --rm --name netalertx --user "0" \
-v local/path/config:/app/config \
-v local/path/db:/app/db \
-v local/path/config:/data/config \
-v local/path/db:/data/db \
ghcr.io/jokob-sk/netalertx:latest
```
@@ -60,16 +62,12 @@ services:
- NET_BIND_SERVICE
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
environment:
- TZ=Europe/Berlin
- PORT=20211
tmpfs:
- "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
- "/app/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,sync,noatime,nodiratime"
- "/services/config/nginx/conf.active:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
- "/services/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
tmpfs:
- "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
```

12
docs/LOGGING.md
View File

@@ -9,7 +9,7 @@ NetAlertX comes with several logs that help to identify application issues. Thes
You can find most of the logs exposed in the UI under _Maintenance -> Logs_.
If the UI is inaccessible, you can access them under `/app/log`.
If the UI is inaccessible, you can access them under `/tmp/log`.
![Logs](./img/LOGGING/maintenance_logs.png)
@@ -52,18 +52,18 @@ The default logs are erased every time the container restarts because they are s
2. Edit your `docker-compose.yml` file:
* **Comment out** the `/app/log` line under the `tmpfs:` section.
* **Comment out** the `/tmp/log` line under the `tmpfs:` section.
* **Uncomment** the "Retain logs" line under the `volumes:` section and set your desired host path.
```yaml
...
tmpfs:
# - "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# - "/tmp/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
...
volumes:
...
# Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
- /home/adam/netalertx_logs:/app/log
# Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
- /home/adam/netalertx_logs:/tmp/log
...
```
3. Restart the container:
@@ -72,4 +72,4 @@ The default logs are erased every time the container restarts because they are s
docker-compose up -d
```
This change stops Docker from mounting a temporary in-memory volume at `/app/log`. Instead, it "bind mounts" a persistent folder from your host computer (e.g., `/data/netalertx_logs`) to that *same location* inside the container.
This change stops Docker from mounting a temporary in-memory volume at `/tmp/log`. Instead, it "bind mounts" a persistent folder from your host computer (e.g., `/data/netalertx_logs`) to that *same location* inside the container.

58
docs/MIGRATION.md
View File

@@ -43,7 +43,7 @@ A banner message will appear at the top of the web UI reminding you to update yo
> [!TIP]
> If you have trouble accessing past backups, config or database files you can copy them into the newly mapped directories, for example by running this command in the container: `cp -r /app/config /home/pi/pialert/config/old_backup_files`. This should create a folder in the `config` directory called `old_backup_files` containing all the files in that location. Another approach is to map the old location and the new one at the same time to copy things over.
> If you have trouble accessing past backups, config or database files you can copy them into the newly mapped directories, for example by running this command in the container: `cp -r /data/config /home/pi/pialert/config/old_backup_files`. This should create a folder in the `config` directory called `old_backup_files` containing all the files in that location. Another approach is to map the old location and the new one at the same time to copy things over.
#### New Docker mount locations
@@ -51,8 +51,8 @@ The internal application path in the container has changed from `/home/pi/pialer
| Old mount point | New mount point |
|----------------------|---------------|
| `/home/pi/pialert/config` | `/app/config` |
| `/home/pi/pialert/db` | `/app/db` |
| `/home/pi/pialert/config` | `/data/config` |
| `/home/pi/pialert/db` | `/data/db` |
If you were mounting files directly, please note the file names have changed:
@@ -104,10 +104,10 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config:/app/config # 🆕 This has changed
- local/path/db:/app/db # 🆕 This has changed
- local/path/config:/data/config # 🆕 This has changed
- local/path/db:/data/db # 🆕 This has changed
# (optional) useful for debugging if you have issues setting up the container
- local/path/logs:/app/log # 🆕 This has changed
- local/path/logs:/tmp/log # 🆕 This has changed
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -150,10 +150,10 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config/app.conf:/app/config/app.conf # 🆕 This has changed
- local/path/db/app.db:/app/db/app.db # 🆕 This has changed
- local/path/config/app.conf:/data/config/app.conf # 🆕 This has changed
- local/path/db/app.db:/data/db/app.db # 🆕 This has changed
# (optional) useful for debugging if you have issues setting up the container
- local/path/logs:/app/log # 🆕 This has changed
- local/path/logs:/tmp/log # 🆕 This has changed
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -190,10 +190,10 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
# (optional) useful for debugging if you have issues setting up the container
- local/path/logs:/app/log
- local/path/logs:/tmp/log
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -207,10 +207,10 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
# (optional) useful for debugging if you have issues setting up the container
- local/path/logs:/app/log
- local/path/logs:/tmp/log
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -234,10 +234,10 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
# (optional) useful for debugging if you have issues setting up the container
- local/path/logs:/app/log
- local/path/logs:/tmp/log
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -253,8 +253,8 @@ services:
```sh
docker run -it --rm --name netalertx --user "0" \
-v local/path/config:/app/config \
-v local/path/db:/app/db \
-v local/path/config:/data/config \
-v local/path/db:/data/db \
ghcr.io/jokob-sk/netalertx:latest
```
@@ -273,24 +273,16 @@ services:
- NET_BIND_SERVICE # 🆕 New line
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
# (optional) useful for debugging if you have issues setting up the container
#- local/path/logs:/app/log
#- local/path/logs:/tmp/log
environment:
- TZ=Europe/Berlin
- PORT=20211
# 🆕 New "tmpfs" section START 🔽
tmpfs:
# Speed up logging. This can be commented out to retain logs between container restarts
- "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# Speed up API access as frontend/backend API is very chatty
- "/app/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,sync,noatime,nodiratime"
# Required for customization of the nginx listen addr/port without rebuilding the container
- "/services/config/nginx/conf.active:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# /services/config/nginx/conf.d is required for nginx and php to start
- "/services/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# /tmp is required by php for session save this should be reworked to /services/run/tmp
tmpfs:
# All writable runtime state resides under /tmp; comment out to persist logs between restarts
- "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
# 🆕 New "tmpfs" section END 🔼
```

12
docs/PERFORMANCE.md
View File

@@ -62,7 +62,7 @@ For example, the **ICMP plugin** allows you to specify a regular expression to s
## Storing Temporary Files in Memory
On systems with slower I/O speeds, you can optimize performance by storing temporary files in memory. This primarily applies to the `/app/api` and `/app/log` folders.
On systems with slower I/O speeds, you can optimize performance by storing temporary files in memory. This primarily applies to the API directory (default: `/tmp/api`, configurable via `NETALERTX_API`) and `/tmp/log` folders.
Using `tmpfs` reduces disk writes and improves performance. However, it should be **disabled** if persistent logs or API data storage are required.
@@ -80,15 +80,15 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
# (Optional) Useful for debugging setup issues
- local/path/logs:/app/log
- local/path/logs:/tmp/log
# (API: OPTION 1) Store temporary files in memory (recommended for performance)
- type: tmpfs # ◀ 🔺
target: /app/api # ◀ 🔺
target: /tmp/api # ◀ 🔺
# (API: OPTION 2) Store API data on disk (useful for debugging)
# - local/path/api:/app/api
# - local/path/api:/tmp/api
environment:
- TZ=Europe/Berlin
- PORT=20211

12
docs/REVERSE_DNS.md
View File

@@ -42,9 +42,9 @@ services:
image: "ghcr.io/jokob-sk/netalertx:latest"
restart: unless-stopped
volumes:
- /home/netalertx/config:/app/config
- /home/netalertx/db:/app/db
- /home/netalertx/log:/app/log
- /home/netalertx/config:/data/config
- /home/netalertx/db:/data/db
- /home/netalertx/log:/tmp/log
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -68,9 +68,9 @@ services:
image: "ghcr.io/jokob-sk/netalertx:latest"
restart: unless-stopped
volumes:
- ./config/app.conf:/app/config/app.conf
- ./db:/app/db
- ./log:/app/log
- ./config/app.conf:/data/config/app.conf
- ./db:/data/db
- ./log:/tmp/log
- ./config/resolv.conf:/etc/resolv.conf # Mapping the /resolv.conf file for better name resolution
environment:
- TZ=Europe/Berlin

4
docs/REVERSE_PROXY.md
View File

@@ -499,8 +499,8 @@ Mapping the updated file (on the local filesystem at `/appl/docker/netalertx/def
```bash
docker run -d --rm --network=host \
--name=netalertx \
-v /appl/docker/netalertx/config:/app/config \
-v /appl/docker/netalertx/db:/app/db \
-v /appl/docker/netalertx/config:/data/config \
-v /appl/docker/netalertx/db:/data/db \
-v /appl/docker/netalertx/default:/etc/nginx/sites-available/default \
-e TZ=Europe/Amsterdam \
-e PORT=20211 \

2
docs/SECURITY_FEATURES.md
View File

@@ -48,7 +48,7 @@ Here’s a breakdown of the defensive layers you get, right out of the box using
**Methodology:** All writable locations are treated as untrusted, temporary, and non-executable by default.
* **In-Memory Volatile Storage:** The `docker-compose.yml` configuration maps all temporary directories (e.g., `/app/log`, `/app/api`, `/tmp`) to in-memory `tmpfs` filesystems. They do not exist on the host's disk.
* **In-Memory Volatile Storage:** The `docker-compose.yml` configuration maps all temporary directories (e.g., `/tmp/log`, `/tmp/api`, `/tmp`) to in-memory `tmpfs` filesystems. They do not exist on the host's disk.
* **Volatile Data:** Because these locations exist only in RAM, their contents are **instantly and irrevocably erased** when the container is stopped. This provides a "self-cleaning" mechanism that purges any attacker-dropped files or payloads on every single restart.

12
docs/SYNOLOGY_GUIDE.md
View File

@@ -40,10 +40,10 @@ services:
network_mode: "host"
restart: unless-stopped
volumes:
- local/path/config:/app/config
- local/path/db:/app/db
- local/path/config:/data/config
- local/path/db:/data/db
# (optional) useful for debugging if you have issues setting up the container
- local/path/logs:/app/log
- local/path/logs:/tmp/log
environment:
- TZ=Europe/Berlin
- PORT=20211
@@ -57,10 +57,10 @@ services:
```yaml
volumes:
- /volume1/app_storage/netalertx/config:/app/config
- /volume1/app_storage/netalertx/db:/app/db
- /volume1/app_storage/netalertx/config:/data/config
- /volume1/app_storage/netalertx/db:/data/db
# (optional) useful for debugging if you have issues setting up the container
# - local/path/logs:/app/log <- commented out with # ⚠
# - local/path/logs:/tmp/log <- commented out with # ⚠
```
![Adjusting docker-compose](./img/SYNOLOGY/08_Adjust_docker_compose_volumes.png)

6
docs/WEB_UI_PORT_DEBUG.md
View File

@@ -62,11 +62,11 @@ In the container execute and investigate:
`cat /var/log/nginx/error.log`
`cat /app/log/app.php_errors.log`
`cat /tmp/log/app.php_errors.log`
### 8. Make sure permissions are correct
> [!TIP]
> You can try to start the container without mapping the `/app/config` and `/app/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership.
> You can try to start the container without mapping the `/data/config` and `/data/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership.
Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/app/db` and `app/config` directories.
Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/data/db` and `app/config` directories.

2
docs/docker-troubleshooting/excessive-capabilities.md
View File

@@ -23,7 +23,7 @@ Limit capabilities to only those required:
- NET_ADMIN
- NET_BIND_SERVICE
```
- Remove any unnecessary `--cap-add` flags from docker run commands
- Remove any unnecessary `--cap-add` or `--privileged` flags from docker run commands
## Additional Resources

6
docs/docker-troubleshooting/mount-configuration-issues.md
View File

@@ -24,9 +24,9 @@ Review and correct your volume mounts in docker-compose.yml:
Example volume configuration:
```yaml
volumes:
- ./data/db:/app/db
- ./data/config:/app/config
- ./data/log:/app/log
- ./data/db:/data/db
- ./data/config:/data/config
- ./data/log:/tmp/log
```
## Additional Resources

2
docs/docker-troubleshooting/nginx-configuration-mount.md
View File

@@ -20,7 +20,7 @@ If you want to use a custom port, create a bind mount for the nginx configuratio
- Add to your docker-compose.yml:
```yaml
volumes:
- /path/to/nginx-config:/app/system/services/active/config
- /path/to/nginx-config:/tmp/nginx/active-config
environment:
- PORT=your_custom_port
```