docs: Update some outdated docs, move backup config into setup

.gitignore

@@ -3,7 +3,7 @@
 .vscode
 
 # templates
-backup/config.yaml
+setup/backup/config.yaml
 services/fail2ban/jail.local
 services/forgejo/app.ini
 services/matrix/config/homeserver.yaml

README.md

@@ -14,17 +14,19 @@ SOFTWARE.
 
 ## Repo Structure
 
-- `./services` Service definitions  
+- `./services` **Service definitions**
-  One subfolder per service with:
+  - One subfolder per service with:
-  - `docker-compose.yml` for this service and its direct dependencies (e.g. db)
+    - `docker-compose.yml` for this service and its direct dependencies (e.g. databases or workers)
     - Additional config files, possibly as template (see below)
-- `./setup` Host setup  
+- `./setup` **Host setup**
-  Setup information about a possible alpine host system
+  - Setup information about a possible alpine host system
-- `./tasks` Task definitions
+- `./tasks` **Task definitions**
-  - `common.yml`: Base tasks used by other tasks
   - `compose.yml`: Container related tasks e.g. starting, updating, or reading logs
-  - `hot.yml`: Tasks related to host system maintenance
+  - `dev.yml`: Useful tasks during development, e.g. adding locally signed certificates into running containers
+  - `host.yml`: Tasks related to host system maintenance
+  - `manage.yml`: Tasks about managing the list of enabled services
   - `services.yml`: Tasks for specific services
+  - `utils.yml`: Utility tasks, mainly used as part of other tasks
 
 ## Requirements
 
@@ -42,6 +44,10 @@ Copy from `.env.sample` and fill in your values.
 
 ## Deploy
 
+Enable services with `./task mgmt:enable <service directory name>` and check enabled services with `./task mgmt:ls-enable`.
+
+Then run
+
 ```sh
 ./task compose:up
 ```
@@ -59,6 +65,12 @@ Filename pattern: `*.template.*`
 Files matching the pattern are copied with the ".template." infix removed (e.g. forgejo.template.ini -> forgejo.ini).  
 Variables are replaced using shell substitution syntax (`${VARIABLE_NAME_HERE}`) using the current environment and values from `.env`.
 
+_Note:_ Variables cannot contain other variables, only one level of template is possible.
+
 ## Host Setup
 
-A possible alpine based host setup is described in [alpine-setup](./setup/alpine-setup.md).
+A possible alpine based host setup is described in [/setup](./setup/README.md).
+
+## Backup
+
+Notes on backup and a possible config using borgmatic can be found in [/setup/backup](./setup/backup/README.md)

setup/README.md

@@ -23,25 +23,25 @@ setup-alpine
 - apk mirror: `f` (detect automatically)
 - add user to your liking
 - SSH server: `openssh`
-- Select disk: `sda`
+- Select disk: `sda` (depending on your system)
 - Disk Setup: `lvm`, then `sys`
 - Erase disk: `y`
 
-**Setup lvm before reboot!**
+**Setup lvm (see next step) before reboot!**
 
 ### LVM
 
 https://wiki.archlinux.org/title/LVM
 
 ```sh
-# install some needed packages
+# install some needed packages (only installed in live system)
 apk add lvm2-extra e2fsprogs-extra device-mapper
 # list existing LVs
 lvs
 # resize existing and create missing LVs
 lvresize -L <SIZE>G [-r] /dev/vg0/<LV>
 lvcreate -L <SIZE>G -n <LV NAME> vg0
-lvcreate -l 100%FREE -n lv_srv vg0
+lvcreate -l 100%FREE -n <LV NAME> vg0
 # init filesystem for each newly created LV
 mkfs.ext4 /dev/vg0/<LV>
 ```
@@ -51,8 +51,8 @@ LV                LSize  Mount
 lv_root           8.00g  /
 lv_logs           4.00g  /var/log
 lv_containers    20.00g  /var/lib/containers
-lv_srv            =REST  /srv
 lv_swap            =RAM  swap
+lv_srv            =REST  /srv
 ```
 
 ## Reboot into installed system
@@ -91,11 +91,13 @@ sudo -i # use only for setup, it's not good practice to use a root shell!
 
 ### Installed Packages
 
+Enable community repo (uncomment line):
+
 ```sh
 vi /etc/apk/repositories
 ```
 
-Uncomment community repo
+Install needed packages. Check and adjust to your needs.
 
 ```sh
 apk update && apk upgrade && apk add \
@@ -112,9 +114,6 @@ apk update && apk upgrade && apk add \
     tree \
     wireguard-tools \
     zsh \
-
-    # currently not available in alpine 3.18:
-    docker-compose-zsh-completion \
 ```
 
 ### zsh
@@ -192,7 +191,7 @@ https://wiki.alpinelinux.org/wiki/Docker
 https://docs.docker.com/engine/logging/drivers/local/
 
 ```sh
-mkdir /etc/docker
+mkdir -p /etc/docker
 cd /etc/docker
 ln -vs /opt/container-server/setup/docker/daemon.json .
 rc-update add docker
@@ -213,7 +212,7 @@ Set outgoing mail server to localhost
 
 Link the crons:
 ```sh
-mkdir -p /etc/periodic/constantly/
+mkdir -p /etc/periodic/always/
 for part in /opt/container-server/setup/cron/*; do
     ln -vs $part/* /etc/periodic/${part##*/}/
 done
@@ -225,7 +224,7 @@ crontab -e
 ```
 
 Add first line: `MAILTO=cron@<your domain>`  
-Add following cron entry: `*   *   *   *   *   run-parts /etc/periodic/constantly`  
+Add following cron entry: `*   *   *   *   *   run-parts /etc/periodic/always`  
 
 ### cgroup mode
 

setup/backup/README.md

@@ -26,6 +26,8 @@ Therefore, all database containers SHOULD follow a common naming folder scheme.
 
 ## Borgmatic
 
+https://torsion.org/borgmatic/
+
 Create a repo on your backup server, e.g. https://www.borgbase.com
 
 ### Install
@@ -36,6 +38,8 @@ apk add borgmatic
 
 ### Config
 
+See config file for excluded dirs
+
 ```sh
-ln -vs /opt/container-server/backup/config.yaml /etc/borgmatic/config.yaml
+ln -vs /opt/container-server/setup/backup/config.yaml /etc/borgmatic/config.yaml
 ```

setup/backup/config.template.yaml

@@ -31,7 +31,7 @@ checks:
 check_last: 3
 
 before_backup:
-  - /opt/container-server/backup/prepare-backup.sh
+  - /opt/container-server/setup/backup/prepare-backup.sh
 
 after_backup:
-  - /opt/container-server/backup/cleanup-backup.sh
+  - /opt/container-server/setup/backup/cleanup-backup.sh