updates README, housekeeping hosts groups

README.md

@@ -1,18 +1,124 @@
 # cit Ansible Infrastructure
 
+This repository contains the Ansible based infrastructure setup for cit services running on Hetzner virtual machines. It covers initial host bootstrapping, common system configuration, Docker and Docker Compose based application deployment, and ongoing maintenance.
+
+Parts of this setup are inspired by and derived from existing open source projects. See the Open Source Acknowledgements section at the end.
+
+## Requirements
+
+* Ansible installed locally
+* SSH access to Hetzner hosts defined in `inventories/hetzner/hosts.yaml`
+* Host specific variables in `inventories/hetzner/host_vars/`
+* Debian based target systems
+
+## Structure
+
+* `inventories/hetzner/hosts.yaml`
+  * Host definitions and group assignments
+* `inventories/hetzner/host_vars/`
+  * Host specific configuration
+  * Includes Docker Compose projects and service configuration
+* `docker_compose_applications/`
+  * Docker Compose services, one "stack" per folder
+
+## Common Playbooks
+
+The following playbooks cover the most common workflows. Replace `HOSTNAME` with the inventory hostname.
+
+### Init VM
+
+First bootstrap of a freshly created VM. This is usually run once and requires root access.
+
+```sh
+ansible-playbook -e ansible_user=root -i inventories/hetzner playbooks/00-init_hetzer_vm.yaml
+```
+
+### Everything
+
+Maintenance and full (re-)deployment.
+
+```sh
+ansible-playbook -i inventories/hetzner playbooks/01-everything.yaml
+```
+
+### Maintenance
+
+Regular system updates and patching.
+
+```sh
+ansible-playbook -i inventories/hetzner playbooks/02-maintenance.yaml
+```
+
+### "compose up"
+
+Deploy or refresh Docker Compose applications after configuration changes or when adding new services.
+
+```sh
+ansible-playbook -i inventories/hetzner playbooks/04-compose-up.yml
+```
+
+### Rebuild Caddy
+
+Rebuild and reload Caddy only. Useful when reverse proxy configuration changed and full service restarts should be avoided.
+
+```sh
+ansible-playbook -i inventories/hetzner playbooks/05-rebuild-caddy.yml
+```
+
+#### Notes
+
+* Some services such as Stirling PDF have a slow startup time. When only reverse proxy configuration changes are required, prefer the Caddy rebuild playbook.
+
 ## Adding a new Hetzner VM
 
-1. Add the VM to `inventories/hetzner/hosts.yaml`  
-   Set the correct `ansible_host` and `ansible_user`, add it to the correct Debian groups, but aside from that there's no further configuration needed for now.
-2. Initialize the VM using the following command (replace `HOST_NAME_HERE` with the name in the inventory):
-   ```bash
-   ansible-playbook -e ansible_user=root -i inventories/hetzner -l HOST_NAME_HERE playbooks/init_hetzer_vm.yaml
-   ```
-3. Add the VM to the desired groups and set the desired variables.  
-   Do all the work you need to do (like creating new Ansible roles etc.).
-4. Run `ansible-playbook -i inventories/hetzner playbooks/docker-compose.yml`
+1. Add the host to `inventories/hetzner/hosts.yaml`
+   * Set `ansible_host` and `ansible_user`
+2. Bootstrap the VM as root
 
-## Open Source Software Used
+```bash
+ansible-playbook -e ansible_user=root -i inventories/hetzner -l HOSTNAME playbooks/00-init_hetzer_vm.yaml
+```
 
-Source code was taken from the [CCCHH/ansible-infra repo](https://git.hamburg.ccc.de/CCCHH/ansible-infra), where it was licensed under the MIT license.
-A copy of the license can be found under [`licenses/ccchh-ansible_mit_license`](licenses/ccchh-ansible_mit_license).
+3. Add host variables and group assignments in `inventories/hetzner/host_vars/`
+4. Run the desired playbook, usually the full setup
+
+```bash
+ansible-playbook -i inventories/hetzner -l HOSTNAME playbooks/01-everything.yaml
+```
+
+## Adding a new service
+
+The helper script `add-service.sh` can be used to add new services quickly.
+
+### Clone and register a Git repository
+
+```bash
+./add-service.sh git@github.com:example/repo.git
+```
+
+### Clone with a custom service name
+
+```bash
+./add-service.sh git@github.com:example/repo.git my-service
+```
+
+### Create a local scaffold
+
+Creates a new service directory with a template `compose.yaml` including the shared `caddy_net` network.
+
+```bash
+./add-service.sh my-service
+```
+
+After adding or modifying services, deploy them using the compose up playbook.
+
+## Open Source Acknowledgements
+
+Parts of this repository are based on work from the following project:
+
+* CCCHH ansible infra repository
+
+  * Source: [https://git.hamburg.ccc.de/CCCHH/ansible-infra](https://git.hamburg.ccc.de/CCCHH/ansible-infra)
+  * License: MIT
+
+A copy of the MIT license can be found at `licenses/ccchh-ansible_mit_license`.