vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-06 17:15:38 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

DOCS: Docker guides

Browse Source 
Signed-off-by: jokob-sk <jokob.sk@gmail.com>
This commit is contained in:
jokob-sk
2025-10-29 15:51:31 +11:00
parent 57f3d6f7ab
commit 61de63771b
5 changed files with 419 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
docs/BACKUPS.md
View File

@@ -1,90 +1,162 @@
# Backing things up
# Backing Things Up
> [!NOTE]
> To backup 99% of your configuration backup at least the `/app/config` folder. Please read the whole page (or at least "Scenario 2: Corrupted database") for details.
> Note that database definitions might change over time. The safest way is to restore your older backups into the **same version** of the app they were taken from and then gradually upgarde between releases to the latest version.
> To back up 99% of your configuration, back up at least the `/app/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.
There are 4 artifacts that can be used to backup the application:
---
| File | Description | Limitations |
|-----------------------|-------------------------------|-------------------------------|
| `/db/app.db` | Database file(s) | The database file might be in an uncommitted state or corrupted |
| `/config/app.conf` | Configuration file | Can be overridden with the [`APP_CONF_OVERRIDE` env variable](https://github.com/jokob-sk/NetAlertX/tree/main/dockerfiles#docker-environment-variables). |
| `/config/devices.csv` | CSV file containing device information | Doesn't contain historical data |
| `/config/workflows.json` | A JSON file containing your workflows | N/A |
## What to Back Up
There are four key artifacts you can use to back up your NetAlertX configuration:
## Backup strategies
| File | Description | Limitations |
| ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/db/app.db` | The application database | Might be in an uncommitted state or corrupted |
| `/config/app.conf` | Configuration file | Can be overridden using the [`APP_CONF_OVERRIDE`](https://github.com/jokob-sk/NetAlertX/tree/main/dockerfiles#docker-environment-variables) variable |
| `/config/devices.csv` | CSV file containing device data | Does not include historical data |
| `/config/workflows.json` | JSON file containing your workflows | N/A |
The safest approach to backups is to backup everything, by taking regular file system backups of the `/db` and `/config` folders (I use [Kopia](https://github.com/kopia/kopia)).
---
Arguably, the most time is spent setting up the device list, so if only one file is kept I'd recommend to have a latest backup of the `devices_<timestamp>.csv` or `devices.csv` file, followed by the `app.conf` and `workflows.json` files. You can also download `app.conf` and `devices.csv` file in the Maintenance section:
## Where the Data Lives
![Backup and Restore Section in Maintenance](./img/BACKUPS/Maintenance_Backup_Restore.png)
### Scenario 1: Full backup
End-result: Full restore
#### 💾 Source artifacts:
- `/app/db/app.db` (uncorrupted)
- `/app/config/app.conf`
- `/app/config/workflows.json`
#### 📥 Recovery:
To restore the application map the above files as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
### Scenario 2: Corrupted database
End-result: Partial restore (historical data and some plugin data will be missing)
#### 💾 Source artifacts:
- `/app/config/app.conf`
- `/app/config/devices_<timestamp>.csv` or `/app/config/devices.csv`
- `/app/config/workflows.json`
#### 📥 Recovery:
Even with a corrupted database you can recover what I would argue is 99% of the configuration.
- upload the `app.conf` and `workflows.json` files into the mounted `/app/config/` folder as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
- rename the `devices_<timestamp>.csv` to `devices.csv` and place it in the `/app/config` folder
- Restore the `devices.csv` backup via the [Maintenance section](./DEVICES_BULK_EDITING.md)
## Data and backup storage
To decide on a backup strategy, check where the data is stored:
Understanding where your data is stored helps you plan your backup strategy.
### Core Configuration
The core application configuration is in the `app.conf` file (See [Settings System](./SETTINGS_SYSTEM.md) for details), such as:
Stored in `/app/config/app.conf`.
This includes settings for:
- Notification settings
- Scanner settings
- Scheduled maintenance settings
- UI configuration
* Notifications
* Scanning
* Scheduled maintenance
* UI preferences
### Core Device Data
(See [Settings System](./SETTINGS_SYSTEM.md) for details.)
The core device data is backed up to the `devices_<timestamp>.csv` or `devices.csv` file via the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup). This file contains data, such as:
### Device Data
- Device names
- Device icons
- Device network configuration
- Device categorization
- Device custom properties 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).
Contains:
### Historical data
* Device names, icons, and categories
* Network configuration
* Custom properties
Historical data is stored in the `app.db` database (See [Database overview](./DATABASE.md) for details). This data includes:
### Historical Data
- Plugin objects
- Plugin historical entries
- History of Events, Notifications, Workflow Events
- Presence history
Stored in `/app/db/app.db` (see [Database Overview](./DATABASE.md)).
Contains:
* Plugin data and historical entries
* Event and notification history
* Device presence history
---
## Backup Strategies
The safest approach is to back up **both** the `/db` and `/config` folders regularly. Tools like [Kopia](https://github.com/kopia/kopia) make this simple and efficient.
If you can only keep a few files, prioritize:
1. The latest `devices_<timestamp>.csv` or `devices.csv`
2. `app.conf`
3. `workflows.json`
You can also download the `app.conf` and `devices.csv` files from the **Maintenance** section:
![Backup and Restore Section in Maintenance](./img/BACKUPS/Maintenance_Backup_Restore.png)
---
## Scenario 1: Full Backup and Restore
**Goal:** Full recovery of your configuration and data.
### 💾 What to Back Up
* `/app/db/app.db` (uncorrupted)
* `/app/config/app.conf`
* `/app/config/workflows.json`
### 📥 How to Restore
Map these files into your container as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
---
## Scenario 2: Corrupted Database
**Goal:** Recover configuration and device data when the database is lost or corrupted.
### 💾 What to Back Up
* `/app/config/app.conf`
* `/app/config/workflows.json`
* `/app/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`
3. Restore via the **Maintenance** section under *Devices → Bulk Editing*
This recovers nearly all configuration, workflows, and device metadata.
---
## Docker-Based Backup and Restore
For users running NetAlertX via Docker, you can back up or restore directly from your host system — a convenient and scriptable option.
### Full Backup (File-Level)
1. **Stop the container:**
```bash
docker stop netalertx
```
2. **Create a compressed archive** of your configuration and database volumes:
```bash
docker run --rm -v netalertx_config:/config -v netalertx_db:/db alpine tar -cz /config /db > netalertx-backup.tar.gz
```
3. **Restart the container:**
```bash
docker start netalertx
```
### Restore from Backup
1. **Stop the container:**
```bash
docker stop netalertx
```
2. **Restore from your backup file:**
```bash
docker run --rm -i -v netalertx_config:/config -v netalertx_db:/db alpine tar -C / -xz < netalertx-backup.tar.gz
```
3. **Restart the container:**
```bash
docker start netalertx
```
> This approach uses a temporary, minimal `alpine` container to access Docker-managed volumes. The `tar` command creates or extracts an archive directly from your host’s filesystem, making it fast, clean, and reliable for both automation and manual recovery.
---
## Summary
* Back up `/app/config` for configuration and devices; `/app/db` for history
* Keep regular backups, especially before upgrades
* For Docker setups, use the lightweight `alpine`-based backup method for consistency and portability

200
docs/DOCKER_MAINTENANCE.md Normal file
View File

@@ -0,0 +1,200 @@
# The NetAlertX Container Operator's Guide
This guide assumes you are starting with the official `docker-compose.yml` file provided with the project. We strongly recommend you start with or migrate to this file as your baseline and modify it to suit your specific needs (e.g., changing file paths). While there are many ways to configure NetAlertX, the default file is designed to meet the mandatory security baseline with layer-2 networking capabilities while operating securely and without startup warnings.
This guide provides direct, concise solutions for common NetAlertX administrative tasks. It is structured to help you identify a problem, implement the solution, and understand the details.
## Guide Contents
- Using a Local Folder for Configuration
- Migrating from a Local Folder to a Docker Volume
- Applying a Custom Nginx Configuration
- Mounting Additional Files for Plugins
> [!NOTE]
>
> Other relevant resources
> - [Fixing Permission Issues](./FILE_PERMISSIONS.md)
> - [Handling Backups](./BACKUPS.md)
> - [Accessing Application Logs](./LOGGING.md)
---
## Task: Using a Local Folder for Configuration
### Problem
You want to edit your `app.conf` and other configuration files directly from your host machine, instead of using a Docker-managed volume.
### Solution
1. Stop the container:
```bash
docker-compose down
```
2. (Optional but Recommended) Back up your data using the method in Part 1.
3. Create a local folder on your host machine (e.g., `/data/netalertx_config`).
4. Edit `docker-compose.yml`:
* **Comment out** the `netalertx_config` volume entry.
* **Uncomment** and **set the path** for the "Example custom local folder" bind mount entry.
```yaml
...
volumes:
# - type: volume
# source: netalertx_config
# target: /app/config
# read_only: false
...
# Example custom local folder called /data/netalertx_config
- type: bind
source: /data/netalertx_config
target: /app/config
read_only: false
...
```
5. (Optional) Restore your backup.
6. Restart the container:
```bash
docker-compose up -d
```
### 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.
---
## Task: Migrating from a Local Folder to a Docker Volume
### Problem
You are currently using a local folder (bind mount) for your configuration (e.g., `/data/netalertx_config`) and want to switch to the recommended Docker-managed volume (`netalertx_config`).
### Solution
1. Stop the container:
```bash
docker-compose down
```
2. Edit `docker-compose.yml`:
* **Comment out** the bind mount entry for your local folder.
* **Uncomment** the `netalertx_config` volume entry.
```yaml
...
volumes:
- type: volume
source: netalertx_config
target: /app/config
read_only: false
...
# Example custom local folder called /data/netalertx_config
# - type: bind
# source: /data/netalertx_config
# target: /app/config
# read_only: false
...
```
3. (Optional) Initialize the volume:
```bash
docker-compose up -d && docker-compose down
```
4. Run the migration command (**replace `/data/netalertx_config` with your actual path**):
```bash
docker run --rm -v netalertx_config:/config -v /data/netalertx_config:/local-config alpine \
sh -c "tar -C /local-config -c . | tar -C /config -x"
```
5. Restart the container:
```bash
docker-compose up -d
```
### About This Method
This uses a temporary `alpine` container that mounts *both* your source folder (`/local-config`) and destination volume (`/config`). The `tar ... | tar ...` command safely copies all files, including hidden ones, preserving structure.
---
## Task: Applying a Custom Nginx Configuration
### Problem
You need to override the default Nginx configuration to add features like LDAP, SSO, or custom SSL settings.
### Solution
1. Stop the container:
```bash
docker-compose down
```
2. Create your custom config file on your host (e.g., `/data/my-netalertx.conf`).
3. Edit `docker-compose.yml`:
```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
...
```
4. Restart the container:
```bash
docker-compose up -d
```
### About This Method
Docker’s bind mount overlays your host file (`my-netalertx.conf`) on top of the default file inside the container. The container remains read-only, but Nginx reads your file as if it were the default.
---
## Task: Mounting Additional Files for Plugins
### Problem
A plugin (like `DHCPLSS`) needs to read a file from your host machine (e.g., `/var/lib/dhcp/dhcpd.leases`).
### Solution
1. Stop the container:
```bash
docker-compose down
```
2. Edit `docker-compose.yml` and add a new line under the `volumes:` section:
```yaml
...
volumes:
...
# Mount for DHCPLSS plugin
- /var/lib/dhcp/dhcpd.leases:/mnt/dhcpd.leases:ro
...
```
3. Restart the container:
```bash
docker-compose up -d
```
4. In the NetAlertX web UI, configure the plugin to read from:
```
/mnt/dhcpd.leases
```
### About This Method
This maps your host file to a new, read-only (`:ro`) location inside the container. The plugin can then safely read this file without exposing anything else on your host filesystem.

23
docs/FILE_PERMISSIONS.md
View File

@@ -21,3 +21,26 @@ Option to set specific user UID and GID can be useful for host system users need
|----------------|--------|---------|-----------|----------|-------------|---------------------------------------------------------------------|
| `/app/config` | nginx | PUID (default 102) | www-data | PGID (default 82) | rwxr-xr-x | Ensure `nginx` can read/write; other users can read if in `www-data` |
| `/app/db` | nginx | PUID (default 102) | www-data | PGID (default 82) | rwxr-xr-x | Same as above |
### Fixing Permission Problems
The container fails to start with "Permission Denied" errors. This typically happens when your data volumes (`netalertx_config`, `netalertx_db`) are "owned" by the `root` user (UID 0) from a previous install, but the secure container must run as the `netalertx` user (UID 20211).
### Solution
1. Run the container **once** as the `root` user (`--user "0"`) to trigger the built-in fix-it mode:
```bash
docker run -it --rm --name netalertx-fix --user "0" \
-v netalertx_config:/app/config \
-v netalertx_db:/app/db \
netalertx:latest
```
2. Wait for the logs to show a **magenta warning** and confirm permissions are being fixed. The container will then hang (this is intentional).
3. Press **Ctrl+C** to stop the fix-it container.
4. Start your container normally (e.g., with `docker-compose up -d` or your standard `docker run` command).
### About This Method
The container’s startup script detects it is running as `root` (UID 0). It automatically runs the `chown` command to fix the permissions on your volume files, setting them to the correct `20211` user. It then hangs (`sleep infinity`) to prevent you from *ever* running the application as `root`, forcing you to restart securely.

59
docs/LOGGING.md
View File

@@ -1,11 +1,9 @@
# Logging
NetAlertX comes with several logs that help to identify application issues.
For plugin-specific log debugging, please read the [Debug Plugins](./DEBUG_PLUGINS.md) guide.
When debugging any issue, increase the `LOG_LEVEL` Setting as per the [Debug tips](./DEBUG_TIPS.md) documentation.
NetAlertX comes with several logs that help to identify application issues. These include ngnix logs, app, or plugin logs. For plugin-specific log debugging, please read the [Debug Plugins](./DEBUG_PLUGINS.md) guide.
> [!NOTE]
> When debugging any issue, increase the `LOG_LEVEL` Setting as per the [Debug tips](./DEBUG_TIPS.md) documentation.
## Main logs
@@ -24,3 +22,54 @@ If a Plugin supplies data to the main app it's done either vie a SQL query or vi
The data is in most of the cases then displayed in the application under _Integrations -> Plugins_ (or _Device -> Plugins_ if the plugin is supplying device-specific data).
![Plugin objects](./img/LOGGING/logging_integrations_plugins.png)
## Viewing Logs on the File System
You cannot find any log files on the filesystem. The container is `read-only` and writes logs to a temporary in-memory filesystem (`tmpfs`) for security and performance. The application follows container best-practices by writing all logs to the standard output (`stdout`) and standard error (`stderr`) streams. Docker's logging driver (set in `docker-compose.yml`) captures this stream automatically, allowing you to access it with the `docker logs <image_name>` command.
* **To see all logs since the last restart:**
```bash
docker logs netalertx
```
* **To watch the logs live (live feed):**
```bash
docker logs -f netalertx
```
## Enabling Persistent File-Based Logs
The default logs are erased every time the container restarts because they are stored in temporary in-memory storage (`tmpfs`). If you need to keep a persistent, file-based log history, follow the steps below.
> [!NOTE]
> This might lead to performance degradation so this approach is only suggested when activelly debuging issues. See the [Performance optimization](./PERFORMANCE.md) documentation for details.
1. Stop the container:
```bash
docker-compose down
```
2. Edit your `docker-compose.yml` file:
* **Comment out** the `/app/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"
...
volumes:
...
# Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
- /home/adam/netalertx_logs:/app/log
...
```
3. Restart the container:
```bash
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 *exact same location* inside the container.

1
mkdocs.yml
View File

@@ -17,6 +17,7 @@ nav:
- Docker Compose: DOCKER_COMPOSE.md
- Docker File Permissions: FILE_PERMISSIONS.md
- Docker Updates: UPDATES.md
- Docker Maintenance: DOCKER_MAINTENANCE.md
- Other:
- Synology Guide: SYNOLOGY_GUIDE.md
- Portainer Stacks: DOCKER_PORTAINER.md