docs: fix code blocks overflowing and add syntax highlighting

Without these options code blocks would overflow. See:
https://github.com/asiffer/mkdocs-shadcn/issues/57
And it also provides nice syntax highlighting.

.forgejo/workflows/cleanup-docs.yaml

@@ -0,0 +1,24 @@
+on:
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  cleanup-staging:
+    runs-on: docker
+    container:
+      image: code.forgejo.org/oci/node:22-bookworm
+    steps:
+      - name: Pipeline info PR
+        run: |
+          echo "Run triggered by ${{ github.event_name }} (${{ github.event.action }}) on ref ${{ github.ref_name }}"
+
+      - name: Staging Deployment - Prepare keys
+        run: |
+          echo "${{ secrets.SSH_DEPLOY_KEY }}" > deploykey.priv
+          chmod 400 deploykey.priv
+          echo "${{ vars.SSH_KNOWN_HOSTS }}" > ./known_hosts
+
+      - name: Staging Deployment - Remove PR from staging
+        run: |
+          ssh -i deploykey.priv -o 'UserKnownHostsFile ./known_hosts' infra-docs-deploy@public-web-static.hosts.hamburg.ccc.de -t "rm -r /var/www/staging.infra-docs.hamburg.ccc.de/pr${{ github.event.pull_request.number }}/"

.forgejo/workflows/deploy-docs.yaml

@@ -0,0 +1,75 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  TZ: Europe/Berlin
+
+jobs:
+  build:
+    runs-on: docker
+    container:
+      image: docker.io/library/python:3.14-trixie
+    steps:
+      - name: Pipeline info
+        run: |
+          echo "Run triggered by ${{ github.event_name }} (${{ github.event.action }}) on ref ${{ github.ref_name }}"
+
+      - name: Install packages
+        run: |
+          apt update
+          apt -y install nodejs git rsync openssh-client
+          pip install --upgrade pip
+
+      - uses: actions/checkout@v6
+
+      - name: Install Python packages
+        run: |
+          pip install -r docs_requirements.txt
+
+      - name: Build website - prod
+        if: github.event_name != 'pull_request'
+        run: |
+          mkdocs build
+
+      - name: Build website - staging
+        if: github.event_name == 'pull_request'
+        run: |
+          sed -i "s#site_url: https://infra-docs.hamburg.ccc.de#site_url: https://staging.infra-docs.hamburg.ccc.de/pr${{ github.event.pull_request.number }}/#" mkdocs.yml
+          mkdocs build
+
+      - name: Deploy - Prepare keys
+        run: |
+          echo "${{ secrets.SSH_DEPLOY_KEY }}" > deploykey.priv
+          chmod 400 deploykey.priv
+          echo "${{ vars.SSH_KNOWN_HOSTS }}" > ./known_hosts
+
+      - name: Deploy - Upload PR to staging
+        if: github.event_name == 'pull_request'
+        run: |
+          echo "Deploying to staging.infra-docs.hamburg.ccc.de/pr${{ github.event.pull_request.number }}"
+          rsync -v -r --delete -e "ssh -i deploykey.priv -o 'UserKnownHostsFile ./known_hosts'" site/ infra-docs-deploy@public-web-static.hosts.hamburg.ccc.de:/var/www/staging.infra-docs.hamburg.ccc.de/pr${{ github.event.pull_request.number }}/
+
+      - name: Deploy - Add comment to PR with staging URL
+        if: github.event_name == 'pull_request' && github.event.action == 'opened'
+        run: |
+          curl \
+            -X POST \
+            ${{ github.event.pull_request.base.repo.url }}/issues/${{ github.event.pull_request.number }}/comments \
+            -H "Content-Type: application/json" \
+            -H "Authorization: token $FORGEJO_TOKEN" \
+            --data '{ "body": "You can view your changes at https://staging.infra-docs.hamburg.ccc.de/pr${{ github.event.pull_request.number }}/" }'
+
+      - name: Deploy - Upload to prod
+        if: github.event_name != 'pull_request'
+        run: |
+          rsync -v -r --delete -e "ssh -i deploykey.priv -o 'UserKnownHostsFile ./known_hosts'" site/ infra-docs-deploy@public-web-static.hosts.hamburg.ccc.de:/var/www/infra-docs.hamburg.ccc.de/
+
+      - uses: actions/upload-artifact@v3
+        if: github.event_name == 'pull_request'
+        with:
+          name: docs-build
+          path: site/
+          retention-days: 3

docs/index.md

@@ -0,0 +1,3 @@
+# CCCHH Infrastructure Documentation
+
+Home for CCCHH infrastructure documentation.

docs_requirements.txt

@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-shadcn
+pygments

inventories/chaosknoten/host_vars/auth-dns.yaml

@@ -7,36 +7,39 @@ knot__dnssec_key_id: "auth-dns.hamburg.ccc.de-1"
 knot__remotes:
   - id: ns-intern.hamburg.ccc.de
     address: [ "2a00:14b0:f000:23::53", "172.31.17.53" ]
+  - id: ns.vie.ccc.de
+    address: [ "2a02:1b8:10:31::228", "146.255.57.228" ]
 
 knot__catalog_zones:
   - domain: "hamburg.ccc.de.catalog."
+    notify_targets: [ "ns.vie.ccc.de" ]
 
 knot__zones:
   - domain: "hh.ccc.de."
     catalog_member: "hamburg.ccc.de.catalog."
-    notify_targets: [ "ns-intern.hamburg.ccc.de" ]
+    notify_targets: [ "ns-intern.hamburg.ccc.de", "ns.vie.ccc.de" ]
     content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/auth-dns/zones/hh.ccc.de.zone') }}"
 
   - domain: "ccchh.net."
     catalog_member: "hamburg.ccc.de.catalog."
-    notify_targets: [ "ns-intern.hamburg.ccc.de" ]
+    notify_targets: [ "ns-intern.hamburg.ccc.de", "ns.vie.ccc.de" ]
     content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/auth-dns/zones/ccchh.net.zone') }}"
 
   - domain: "hamburg.ccc.de."
     catalog_member: "hamburg.ccc.de.catalog."
-    notify_targets: [ "ns-intern.hamburg.ccc.de" ]
+    notify_targets: [ "ns-intern.hamburg.ccc.de", "ns.vie.ccc.de" ]
     content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/auth-dns/zones/hamburg.ccc.de.zone') }}"
 
   - domain: "eh20.easterhegg.eu."
     catalog_member: "hamburg.ccc.de.catalog."
-    notify_targets: [ "ns-intern.hamburg.ccc.de" ]
+    notify_targets: [ "ns-intern.hamburg.ccc.de", "ns.vie.ccc.de" ]
     content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/auth-dns/zones/eh20.easterhegg.eu.zone') }}"
 
   - domain: "eh22.easterhegg.eu."
     catalog_member: "hamburg.ccc.de.catalog."
-    notify_targets: [ "ns-intern.hamburg.ccc.de" ]
+    notify_targets: [ "ns-intern.hamburg.ccc.de", "ns.vie.ccc.de" ]
     content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/auth-dns/zones/eh22.easterhegg.eu.zone') }}"
 
   - domain: "3.2.0.0.0.0.0.f.0.b.4.1.0.0.a.2.ip6.arpa."
-    notify_targets: [ "ns-intern.hamburg.ccc.de" ]
+    notify_targets: [ "ns-intern.hamburg.ccc.de", "ns.vie.ccc.de" ]
     content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/auth-dns/zones/3.2.0.0.0.0.0.f.0.b.4.1.0.0.a.2.ip6.arpa.zone') }}"

mkdocs.yml

@@ -0,0 +1,20 @@
+site_name: CCCHH Infrastructure Documentation
+site_url: https://infra-docs.hamburg.ccc.de
+repo_url: https://git.hamburg.ccc.de/CCCHH/ansible-infra
+copyright: MIT
+markdown_extensions:
+  - smarty
+  - admonition
+  - attr_list
+  - codehilite
+
+theme:
+  name: shadcn
+  show_title: true
+  show_stargazers: false
+  pygments_style:
+    light: shadcn-light
+    dark: github-dark
+  icon: oui:documentation
+  topbar_sections: false
+  show_datetime: false

playbooks/deploy.yaml

@@ -3,69 +3,98 @@
   hosts: base_config_hosts
   roles:
     - base_config
+  tags:
+    - base_config
 
 - name: Ensure systemd-networkd config deployment on systemd_networkd_hosts
   hosts: systemd_networkd_hosts
   roles:
     - systemd_networkd
+  tags:
+    - systemd_networkd
 
 - name: Ensure nftables deployment on nftables_hosts
   hosts: nftables_hosts
   roles:
     - nftables
+  tags:
+    - nftables
 
 - name: Ensure deployment of infrastructure authorized keys
   hosts: infrastructure_authorized_keys_hosts
   roles:
     - infrastructure_authorized_keys
+  tags:
+    - infrastructure_authorized_keys
 
 - name: Ensure Nextcloud config
   hosts: nextcloud_hosts
   roles:
     - nextcloud
+  tags:
+    - nextcloud
 
 - name: Ensure ola deployment on ola_hosts
   hosts: ola_hosts
   roles:
     - ola
+  tags:
+    - ola
 
 - name: Ensure foobazdmx deployment on foobazdmx_hosts
   hosts: foobazdmx_hosts
   roles:
     - foobazdmx
+  tags:
+    - foobazdmx
 
 - name: Ensure Dokuwiki config
   hosts: wiki_hosts
   roles:
     - dokuwiki
+  tags:
+    - dokuwiki
 
 - name: Ensure NetBox deployment on netbox_hosts
   hosts: netbox_hosts
   roles:
     - netbox
+  tags:
+    - netbox
 
 - name: Ensure NGINX deployment on nginx_hosts, which are also public_reverse_proxy_hosts, before certbot role runs
   hosts: nginx_hosts:&public_reverse_proxy_hosts
   roles:
     - nginx
+  tags:
+    - nginx
+    - public_reverse_proxy
 
 - name: Ensure certbot and certificate deployment on certbot_hosts
   hosts: certbot_hosts
   roles:
     - certbot
+  tags:
+    - certbot
 
 - name: Ensure OnlyOffice custom fonts
   ansible.builtin.import_playbook: onlyoffice_fonts.yaml
+  tags:
+    - onlyoffice_fonts
 
 - name: Ensure Docker Compose deployment on docker_compose_hosts
   hosts: docker_compose_hosts
   roles:
     - docker_compose
+  tags:
+    - docker_compose
 
 - name: Ensure NGINX deployment on nginx_hosts
   hosts: nginx_hosts:!public_reverse_proxy_hosts
   roles:
     - nginx
+  tags:
+    - nginx
 
 - name: Configure unattended upgrades for all non-hypervisors
   hosts: all:!hypervisors
@@ -77,32 +106,46 @@
           - "o=${distro_id},n=${distro_codename}"
           - "o=Docker,n=${distro_codename}"
           - "o=nginx,n=${distro_codename}"
+  tags:
+    - unattended_upgrades
 
 - name: Ensure Alloy is installed and Setup on alloy_hosts
   hosts: alloy_hosts
   become: true
   roles:
     - alloy
+  tags:
+    - alloy
 
 - name: Ensure ansible_pull deployment on ansible_pull_hosts
   hosts: ansible_pull_hosts
   roles:
     - ansible_pull
+  tags:
+    - ansible_pull
 
 - name: Ensure msmtp is setup on msmtp_hosts
   hosts: msmtp_hosts
   roles:
     - msmtp
+  tags:
+    - msmtp
 
 - name: Ensure Renovate is setup on renovate_hosts
   hosts: renovate_hosts
   roles:
     - renovate
+  tags:
+    - renovate
 
 - name: Run ensure_eh22_styleguide_dir Playbook
   ansible.builtin.import_playbook: ensure_eh22_styleguide_dir.yaml
+  tags:
+    - eh22_styleguide_dir
 
 - name: Setup authoritative dns servers
   hosts: auth-dns
   roles:
     - knot
+  tags:
+    - knot

playbooks/maintenance.yaml

@@ -1,5 +1,7 @@
 - name: Ensure NGINX repo setup and nginx install on relevant hosts
   hosts: nginx_hosts:nextcloud_hosts
+  tags:
+    - nextcloud_nginx
   tasks:
     - name: Ensure NGINX repo is setup
       ansible.builtin.include_role:
@@ -13,6 +15,8 @@
 
 - name: Ensure Docker repo setup and package install on relevant hosts
   hosts: docker_compose_hosts:nextcloud_hosts
+  tags:
+    - nextcloud_docker
   tasks:
     - name: Ensure Docker repo is setup
       ansible.builtin.include_role:
@@ -28,6 +32,8 @@
   hosts: all:!hypervisors
   roles:
     - apt_update_and_upgrade
+  tags:
+    - apt_update_and_upgrade
 
 - name: Run deploy Playbook
   ansible.builtin.import_playbook: deploy.yaml

resources/chaosknoten/auth-dns/zones/hamburg.ccc.de.zone

@@ -287,6 +287,8 @@ spaceapiccc                         IN  CNAME           public-reverse-proxy
 acmedns                             IN  CNAME           public-reverse-proxy
 cpuccc                              IN  CNAME           public-reverse-proxy
 did                                 IN  CNAME           public-reverse-proxy
+infra-docs                          IN  CNAME           public-reverse-proxy
+staging.infra-docs                  IN  CNAME           public-reverse-proxy
 
 
 auth.acmedns                        IN  NS              acmedns.hosts.hamburg.ccc.de.

resources/chaosknoten/public-reverse-proxy/nginx/acme_challenge.conf

@@ -85,6 +85,8 @@ map $host $upstream_acme_challenge_host {
     diday.org public-web-static.hosts.hamburg.ccc.de:31820;
     docs.c3voc.de public-web-static.hosts.hamburg.ccc.de:31820;
     staging.docs.c3voc.de public-web-static.hosts.hamburg.ccc.de:31820;
+    infra-docs.hamburg.ccc.de public-web-static.hosts.hamburg.ccc.de:31820;
+    staging.infra-docs.hamburg.ccc.de public-web-static.hosts.hamburg.ccc.de:31820;
     default "";
 }
 

resources/chaosknoten/public-reverse-proxy/nginx/nginx.conf

@@ -108,6 +108,8 @@ stream {
         *.staging.diday.org public-web-static.hosts.hamburg.ccc.de:8443;
         docs.c3voc.de public-web-static.hosts.hamburg.ccc.de:8443;
         staging.docs.c3voc.de public-web-static.hosts.hamburg.ccc.de:8443;
+        infra-docs.hamburg.ccc.de public-web-static.hosts.hamburg.ccc.de:8443;
+        staging.infra-docs.hamburg.ccc.de public-web-static.hosts.hamburg.ccc.de:8443;
     }
 
     server {

resources/external/status/docker_compose/config/services-chaosknoten.yaml

@@ -57,6 +57,33 @@ endpoints:
       # apparently TXT records aren't supported yet.
       # - "[BODY] == ________________gatus_test_________________"
 
+  - name: auth-dns (hamburg.ccc.de)
+    url: "auth-dns.hamburg.ccc.de"
+    <<: *services_chaosknoten_defaults
+    dns:
+      query-name: "hamburg.ccc.de"
+      query-type: "A"
+    conditions:
+      - "[DNS_RCODE] == NOERROR"
+
+  - name: auth-dns (eh22.easterhegg.eu)
+    url: "auth-dns.hamburg.ccc.de"
+    <<: *services_chaosknoten_defaults
+    dns:
+      query-name: "eh22.easterhegg.eu"
+      query-type: "A"
+    conditions:
+      - "[DNS_RCODE] == NOERROR"
+
+  - name: auth-dns (club-assistant.ccchh.net)
+    url: "auth-dns.hamburg.ccc.de"
+    <<: *services_chaosknoten_defaults
+    dns:
+      query-name: "club-assistant.ccchh.net"
+      query-type: "AAAA"
+    conditions:
+      - "[DNS_RCODE] == NOERROR"
+
   - name: CCCHH ID/Keycloak (main page/account console)
     url: "https://id.hamburg.ccc.de/"
     <<: *services_chaosknoten_defaults

resources/external/status/docker_compose/config/websites.yaml

@@ -76,6 +76,14 @@ endpoints:
       - "[CERTIFICATE_EXPIRATION] > 48h"
       - "[BODY] == pat(*Digitale Selbstverteidigung in Hamburg*)"
 
+  - name: diday.org
+    url: "https://diday.org"
+    <<: *websites_defaults
+    conditions:
+      - "[STATUS] == 200"
+      - "[CERTIFICATE_EXPIRATION] > 48h"
+      - "[BODY] == pat(*DIDay*)"
+
   - name: element-admin.hamburg.ccc.de
     url: "https://element-admin.hamburg.ccc.de"
     <<: *websites_defaults

roles/deploy_systemd_resolved_config/handlers/main.yaml

@@ -1,6 +1,5 @@
 ---
 - name: "reload systemd-resolved"
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   ansible.builtin.systemd:
     name: "systemd-resolved.service"

roles/deploy_systemd_resolved_config/tasks/disable.yaml

@@ -1,13 +1,11 @@
 ---
 - name: Ensure /etc/resolv.conf is a plain file
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   ansible.builtin.file:
     path: "/etc/resolv.conf"
     state: file
 
 - name: Write nameserver config directly into /etc/resolv.conf
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   ansible.builtin.template:
     src: "resolv.conf.j2"
@@ -17,7 +15,6 @@
     mode: u=rw,g=r,o=r
 
 - name: Disable systemd-resolved
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   ansible.builtin.systemd:
     name: "systemd-resolved.service"

roles/deploy_systemd_resolved_config/tasks/enable.yaml

@@ -1,13 +1,11 @@
 ---
 - name: Ensure systemd-resolved is installed
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   when: ansible_facts["distribution"] == "Debian"
   ansible.builtin.package:
     name: [ "systemd-resolved" ]
 
 - name: Deploy systemd-resolved config
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   notify: "reload systemd-resolved"
   ansible.builtin.template:
@@ -18,7 +16,6 @@
     mode: u=rw,g=r,o=r
 
 - name: Make /etc/resolv.conf points to systemd-resolved
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   when: deploy_systemd_resolved_config__mode != "extern"
   ansible.builtin.file: # noqa: jinja
@@ -35,7 +32,6 @@
       {%- endif -%}
 
 - name: Ensure systemd-resolved is running and enabled
-  tags: [ "deploy_systemd_resolved_config" ]
   become: true
   ansible.builtin.systemd:
     name: systemd-resolved.service

roles/deploy_systemd_resolved_config/tasks/main.yaml

@@ -1,10 +1,8 @@
 ---
 - name: Include enable.yaml
-  tags: [ "deploy_systemd_resolved_config" ]
   ansible.builtin.include_tasks: enable.yaml
   when: deploy_systemd_resolved_config__enable
 
 - name: Include disable.yaml
-  tags: [ "deploy_systemd_resolved_config" ]
   ansible.builtin.include_tasks: disable.yaml
   when: not deploy_systemd_resolved_config__enable

roles/knot/handlers/main.yaml

@@ -1,19 +1,16 @@
 ---
 - name: reload knot
-  tags: [ auth-dns ]
   become: true
   ansible.builtin.systemd:
     name: knot.service
     state: reloaded
 
 - name: netplan apply
-  tags: [ auth-dns ]
   become: true
   changed_when: true
   ansible.builtin.command: "netplan apply"
 
 - name: restart knot-exporter
-  tags: [ auth-dns ]
   become: true
   ansible.builtin.systemd:
     name: knot-exporter.service

roles/knot/tasks/01-install.yaml

@@ -1,6 +1,5 @@
 ---
 - name: Install knot
-  tags: [ auth-dns ]
   become: true
   ansible.builtin.package:
     name:

roles/knot/tasks/02-configure.yaml

@@ -1,6 +1,5 @@
 ---
 - name: Ensure required directories exist
-  tags: [ auth-dns ]
   become: true
   loop: [ "/etc/knot", "/etc/knot/zones" ]
   ansible.builtin.file:
@@ -11,7 +10,6 @@
     mode: u=rwx,g=rx,o=
 
 - name: Deploy knot configuration file
-  tags: [ auth-dns ]
   become: true
   notify: reload knot
   ansible.builtin.template:
@@ -22,7 +20,6 @@
     mode: u=rw,g=r,o=
 
 - name: Deploy configured zones
-  tags: [ auth-dns ]
   become: true
   notify: reload knot
   loop: "{{ knot__zones }}"
@@ -42,7 +39,6 @@
 # this results in outgoing zone transfers failing because knot will prefer to use the dynamic address over the statically configured one.
 # so because we are configuring a DNS Nameserver where known IP-Addresses are actually important for ACL reasons, SLAAC is disabled
 - name: Disable IPv6 SLAAC
-  tags: [ auth-dns ]
   become: true
   notify: netplan apply
   ansible.builtin.template:

roles/knot/tasks/03-configure-exporter.yaml

@@ -1,5 +1,4 @@
 - name: Deploy knot-exporter systemd unit
-  tags: [ auth-dns ]
   become: true
   register: knot_deploy_service_file
   notify: restart knot-exporter
@@ -11,7 +10,6 @@
     mode: u=rw,g=r,o=r
 
 - name: Ensure knot-exporter is running and enabled
-  tags: [ auth-dns ]
   become: true
   ansible.builtin.systemd:
     name: knot-exporter.service

roles/knot/templates/knot.conf.j2

@@ -67,8 +67,7 @@ template:
   # template for automatically created special zones
   - id: catalog
     catalog-role: generate
-    dnssec-signing: on
+    dnssec-signing: off
-    dnssec-policy: default
 
 
 # define zones on this server