Updated README

README.md

@@ -4,11 +4,17 @@ A repository containing a set of [Ansible](https://www.ansible.com/) roles and p
 
 The main goals of this project are:
 
-* regain control of your data,
-* counter the growing vendor lock-in of big corporations,
-* foster decentralisation and federation,
-* enable individuals but also e.g. educational institutions or NGOs to quickly set up their own infrastructure,
-* provide an overall well integrated set of tools which allows to use one tool together with another.
+- regain control of your data,
+- counter the growing vendor lock-in of big corporations,
+- foster decentralisation and federation,
+- enable individuals but also e.g. educational institutions or NGOs to quickly set up their own infrastructure,
+- provide an overall well integrated set of tools which allows to use one tool together with another.
+
+## Key components
+
+- Docker Compose services
+- Traefik reverse proxy, loadbalancer and TLS terminator with automatic Let's Encrypt support by default
+- Ansible for provisioning and configuration management
 
 ## Services
 
@@ -42,11 +48,11 @@ To give SATT a quick spin, you could easily bootstrap a development VM using Vag
 
 1. [Download](https://www.virtualbox.org/wiki/Downloads) and install Virtualbox ([Documentation](https://www.virtualbox.org/wiki/End-user_documentation))
 
-1. Follow the [guide to install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). This SATT guide assumes Ubuntu 18.04 LTS
+2. Follow the [guide to install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). This SATT guide assumes Ubuntu 18.04 LTS
 
-1. Open Ubuntu through the Windows Start Menu
+3. Open Ubuntu through the Windows Start Menu
 
-1. Inside the Ubuntu Terminal, continue the setup by following the next section.
+4. Inside the Ubuntu Terminal, continue the setup by following the next section.
 
 ### Vagrant + Ansible on Linux
 
@@ -107,3 +113,23 @@ By default, a `vagrant` user will be provisioned (if not already available) and
 - Adapt the inventory and choose the services
 - Configure each desired service by following the README of its role.
 - Run the playbook `site.yml` or one of the service playbooks.
+
+## How does it work?
+
+The provisioning and configuration management tool Ansible is used to access a Linux server (VM, bare-metal) using SSH and provisions a set of roles. Each role consists of Docker Compose services (each containing one or more Docker containers).
+
+Traefik is used as a reverse proxy and TLS terminator. The Docker Compose services feature labels that are recognised and processed by Traefik, resulting in a simple yet effective service discovery. Each service has at least a label stating the desired virtual host under which it is going to respond. Traefik will create required Let's Encrypt certificates for TLS and forward requests for that host to the corresponding service.
+
+### Persistent data and backups
+
+Docker containers are ephemeral by nature. If data should survive when a container gets replaced, it has to stored outside the container and mounted into the container. SATT uses Docker volumes to make persistance easy. Compared to host mounts, with volume mounts you don't have to deal e.g. with permission and owner issues in the container.
+
+Backups are currently only supported for Nextcloud and provided by [Restic](https://restic.net/), specifically [`restic-compose-backup`](https://restic-compose-backup.readthedocs.io/en/latest/) (rcb). With rcb you can backup static volumes but also the relational databases MySQL, MariaDB and Postgres using the corresponding DB dump commands.
+
+Persistent volumes that need to be backed up will be labeled in a way that rcb will find them and also whether it is one of the DBs above which should be backed up.
+
+Restic assumes untrusted environments, hence backups are always encrypted using modern algorithms. [See their website for further details.](https://restic.net)
+
+## Similiar projects
+
+*