diff --git a/dockerfiles/README.md b/dockerfiles/README.md index 61310a2f..3ee4d388 100755 --- a/dockerfiles/README.md +++ b/dockerfiles/README.md @@ -42,12 +42,16 @@ docker run -d --rm --network=host \ |`TZ` |Time zone to display stats correctly. Find your time zone [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | `Europe/Berlin` | |`HOST_USER_GID` |User ID (UID) to map the user in the container to a server user with sufficient read&write permissions on the mapped files | `1000` | |`HOST_USER_ID` |User Group ID (GID) to map the user group in the container to a server user group with sufficient read&write permissions on the mapped files | `1000` | +|`ALWAYS_FRESH_INSTALL` | Setting `ALWAYS_FRESH_INSTALL=true` will delete the content of the `/db` & `/config` folders. For testing purposes. | `N/A` | ### Docker paths +> [!NOTE] +> See also [Backup strategies](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/BACKUPS.md). + | Required | Path | Description | | :------------- | :------------- | :-------------| -| ✅ | `:/home/pi/pialert/config` | Folder which will contain the `pialert.conf` file (see below for details) | +| ✅ | `:/home/pi/pialert/config` | Folder which will contain the `pialert.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/DEVICES_BULK_EDITING.md)) files (see below for details) | | ✅ | `:/home/pi/pialert/db` | Folder which will contain the `pialert.db` file | | | `:/home/pi/pialert/front/log` | Logs folder useful for debugging if you have issues setting up the container | | | `:/etc/pihole/pihole-FTL.db` | PiHole's `pihole-FTL.db` database file. Required if you want to use PiHole DB mapping. | diff --git a/docs/BACKUPS.md b/docs/BACKUPS.md new file mode 100755 index 00000000..b4809f38 --- /dev/null +++ b/docs/BACKUPS.md @@ -0,0 +1,82 @@ +# 💾 Backing things up + +> [!NOTE] +> To backup 99% of your ocnfigurations backup at least the `/config` folder. Please read the whole page (or at least "Scenario 2: Corrupted database") for details. + +There are 3 artifacts that can be used to backup the application: + +| File | Description | Limitations | +|-----------------------|-------------------------------|-------------------------------| +| `/db/pialert.db` | Database file(s) | The database file might be in an uncommitted state or corrupted | +| `/config/pialert.conf` | Configuration file | Doesn't contain settings from the Maintenance section | +| `/config/devices.csv` | CSV file containing device information | Doesn't contain historical data | + +## Data and cackup storage + +To decide on a backup strategy, check where the data is stored: + +### Core Configuration + +The core application configuration is in the `pialert.conf` file (See [Settings System](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/SETTINGS_SYSTEM.md) for details), such as: + +- Notification settings +- Scanner settings +- Scheduled maintenance settings +- UI configuration (80%) + +### Core Device Data + +The core device data is backed up to the `devices_.csv` file via the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/Pi.Alert/tree/main/front/plugins/csv_backup). This file contains data, such as: + +- Device names +- Device Icons +- Device Network configuration +- Device categorization + +### Historical data + +Historical data is stored in the `pialert.db` database (See [Database overview](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/DATABASE.md) for details). This data includes: + +- Plugin objects +- Plugin historical entries +- History of Events, Notifications, Workflow Events +- Presence History + +## 🧭 Backup strategies + +The safest approach to backups is to backup all of the above with, by taking regular file system backups (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_.csv` file, followed by the `pialert.conf` file. + +### Scenario 1: Full backup + +End-result: Full restore + +#### Source artifacts: + +- `/db/pialert.db` (uncorrupted) +- `/config/pialert.conf` + +#### Recovery: + +To restore the application map the above files as described in the [Setup documentation](https://github.com/jokob-sk/Pi.Alert/blob/main/dockerfiles/README.md#docker-paths). + + +### Scenario 2: Corrupted database + +End-result: Partial restore (historical data & Configuration from the Maintenance section will be missing) + +#### Source artifacts: + +- `/config/pialert.conf` +- `/config/devices_.csv` or `/config/devices.csv` + +#### Recovery: + +Even with a corrupted database you can recover what I would argue is 99% of the configuration (except of a couple of settings under Maintenance). + +- map the `/config/pialert.conf` file as described in the [Setup documentation](https://github.com/jokob-sk/Pi.Alert/blob/main/dockerfiles/README.md#docker-paths). +- rename the `devices_.csv` to `devices.csv` and place it in the `/config` folder +- Restore the `devices.csv` backup via the [Maintenance section](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/DEVICES_BULK_EDITING.md) + +