docs: improve formatting and wording a bit to make things clearer

docs/create-new-web-service-vm.md

@@ -5,36 +5,47 @@ Let's assume that you want to add a new web service `example.hamburg.ccc.de` whi
 ## IP, DNS, VM
 
 1. Allocate a fresh [IPv6 in Netbox in the 2a00:14b0:42:102::/64 net](https://netbox.hamburg.ccc.de/ipam/prefixes/47/ip-addresses/). This will be the management address for the VM. 
-2. Add an entry `example.hosts.hamburg.ccc.de` with that AAAA to the name server (`ns-intern`).
+2. On `ns-intern`:
-3. Add an entry `example.hamburg.ccc.de` as a CNAME for `public-reverse-proxy` to the same zone.
+   1. Add an entry `example.hosts.hamburg.ccc.de` as an AAAA pointing to the allocated IP.
-4. Commit and reload the zone.
+   2. Add an entry `example.hamburg.ccc.de` as a CNAME for `public-reverse-proxy` to the same zone.
-5. Create a new VM on chaosknoten, for example by cloning the Debian template 9023. Give it the name `example`.
+   3. Commit and reload the zone.
-6. Edit the ethernet interface to be connected to `vmbr0`, VLAN tag `2`.
+3. On Chaosknoten:
-7. Configure the IPv6 address in the Cloud-Init section. Leave IPv4 set to DHCP.
+   1. Create a new VM, for example by cloning the Debian template 9023.  
-8. Make sure the VM is started at boot (options).
+      Give it the name `example`.
-9. Adjust any other VM parameters as needed.
+   2. Edit the ethernet interface to be connected to `vmbr0`, VLAN tag `2`.
-10. Boot the VM.
+   3. Configure the IPv6 address in the Cloud-Init section. Leave IPv4 set to DHCP.
-11. Add the [VM to Netbox](https://netbox.hamburg.ccc.de/virtualization/virtual-machines/). Make sure to enter the VM ID.
+   4. Make sure the VM is started at boot (options).
-12. Add an Ethernet interface to the VM; we typically use `eth0` as a name.
+   5. Adjust any other VM parameters as needed.
-13. Add IP for that interface, then choose "Assign IP" and search for the IP you've created. Make it the primary IP of that interface.
+   6. Boot the VM.
+4. Add the [VM to Netbox](https://netbox.hamburg.ccc.de/virtualization/virtual-machines/).
+    - Make sure to enter the VM ID.
+    - Add an Ethernet interface to the VM; we typically use `eth0` as a name.
+    - Add IP for that interface, then choose "Assign IP" and search for the IP you've created. Make it the primary IP of that interface.
 
 ## Ansible Basics
 
 As the first step, we need to make the host known to Ansible.
 
 1. In `.sops.yaml`, add an entry for the host. Follow the other entries there.
-   1. `keys.hosts.chaosknoten.age` needs an age public key (the private key is needed in the host-specific YAML)
+   1. `keys.hosts.chaosknoten.age` needs an age public key (must be generated; the private key gets added later in the host-specific YAML)
    2. `creation_rules` needs an entry for the host, referencing the age key.
 2. In `inventories/chaosknoten/hosts.yaml`:
    1. Configure basic connection info:
-        ```
+        ```yaml
         example:
             ansible_host: example.hosts.hamburg.ccc.de
             ansible_user: chaos
             ansible_ssh_common_args: -J ssh://chaos@router.hamburg.ccc.de
         ```
         You typically will want to use router as a jump host so that you can run Ansible on an IPv4 only connection.
-    2. Add the host to the desired roles. As a minimum, you'll want `base_config_hosts` and `infrastructure_authorized_keys_hosts`. For a typical web service based on Docker Compose, you'll want `docker_compose_hosts`, `nginx_hosts`, and `certbot_hosts`.
+    2. Add the host to the desired roles.
+       1. As a minimum, you'll want the following roles:
+          - `base_config_hosts`
+          - `infrastructure_authorized_keys_hosts`
+       2. For a typical web service based on Docker Compose, you'll also want:
+          - `docker_compose_hosts`
+          - `nginx_hosts`
+          - `certbot_hosts`.
  3. In the directorry `inventories/chaosknoten/host_var/`:
     1. A file `inventories/chaosknoten/host_var/example.yaml` with the host/service specific configuration.
     2. A file `inventories/chaosknoten/host_var/example.sops.yaml` with the encrypted secrets for the host/service. Run `sops inventories/chaosknoten/host_var/example.yaml` to edit/create that file. Entries here should generally be prefixed with `secret__` to make it easier to see where that variable is coming from in templates etc.
@@ -69,12 +80,20 @@ Before you can run Ansible successfully, you will want to make sure you can conn
 * `ssh chaos@example.hosts.hamburg.ccc.de`
 * `ssh -J chaos@router.hamburg.ccc.de chaos@example.hosts.hamburg.ccc.de`
 
-Then run Ansible for `public-reverse-proxy` to add the necessary entries: `ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit public-reverse-proxy`.
+Then run Ansible for `public-reverse-proxy` to add the necessary entries:
 
-Finally run Ansible for the new host: `ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit example`
+```sh
+ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit public-reverse-proxy
+```
+
+Finally run Ansible for the new host:
+
+```sh
+ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit example
+```
 
 # Commit your changes
 
 Do not forget to commit your changes, whether it's a new host or you are making changes to an existing host.
 
-And always `git pull` before you run Ansible so avoid reverting anything!
+And always `git pull` before you run Ansible so avoid reverting anything!