Add Dovecot IMAP + Fetchmail, fix Gitea SSO, simplify credential management

- Add local Dovecot IMAP server exposed via Traefik IMAPS on port 993; Roundcube now connects to it internally instead of requiring manual server entry - Add Fetchmail integration for pulling from external POP3 accounts with configurable per-account poll interval - Fix Gitea SSO registration: DISABLE_REGISTRATION=false + ALLOW_ONLY_EXTERNAL_REGISTRATION allows Keycloak-authenticated users to get accounts while blocking public sign-up; disable legacy OpenID 2.0 sign-in - Fix Keycloak post-logout redirect for Nextcloud (valid post logout redirect URI) - Replace all pre-hashed credentials (Traefik dashboard, registry, Dovecot) with plaintext passwords in vault; Ansible generates deterministic bcrypt/SHA-512 hashes at deploy time — no more manual htpasswd commands - Rewrite check-vault.sh with Python/PyYAML to properly validate both scalar and list-type secrets - Update provisioning and configuration runbooks throughout
2026-06-28 14:13:53 +02:00
parent fdcc0079cb
commit 187c6bdea4
15 changed files with 436 additions and 116 deletions
@@ -24,18 +24,16 @@ traefik_network: traefik_public
 # Traefik
 traefik_version: v3.6
 traefik_data_dir: /opt/traefik
-# htpasswd-formatted user list for the dashboard.
-# Generate with: echo $(htpasswd -nB admin) | sed -e 's/\$/\$\$/g'
-# Store the actual value in ansible/group_vars/all/vault.yml (Ansible Vault).
-traefik_dashboard_users: ""
+# Dashboard basic-auth users — plaintext passwords, Ansible generates bcrypt hashes at deploy time
+# traefik_dashboard_users:
+#   - username: admin
+#     password: "your-password"
+traefik_dashboard_users: []

 # Gitea
 gitea_version: "1"          # major-only tag — always pulls latest 1.x patch
 gitea_db_version: "16"      # PostgreSQL major version
 gitea_data_dir: /opt/gitea
-# Set to false for the very first deploy so the admin account can be created,
-# then flip to true and redeploy to close public registration.
-gitea_disable_registration: true
 # Secrets — store values in ansible/group_vars/all/vault.yml (Ansible Vault)
 # gitea_db_password: ""
 # gitea_secret_key: ""      # generate: openssl rand -hex 32
@@ -59,28 +57,42 @@ nextcloud_admin_user: admin
 # nextcloud_db_password: ""
 # nextcloud_admin_password: ""

-# Mail (Roundcube webmail client)
+# Mail (Roundcube + Dovecot IMAP + Fetchmail)
 roundcube_version: "1.6.x-apache"
 roundcube_db_version: "16"
 mail_data_dir: /opt/mail
-# IMAP/SMTP — set to the mail server Roundcube should connect to.
-# Leave imap_host empty to let users enter their own server at login.
-# Use "ssl://hostname" for implicit TLS (port 993), or plain hostname for STARTTLS (port 143).
-roundcube_imap_host: ""
-roundcube_imap_port: "993"
+# Dovecot IMAP server — Roundcube always connects to the local Dovecot container
+dovecot_version: "2.3"
+# SMTP — outgoing mail server for Roundcube (leave empty if not configured)
 roundcube_smtp_host: ""
 roundcube_smtp_port: "587"
+# Fetchmail — polls external POP3 accounts and delivers to local Dovecot via LMTP
+# poll_minutes is per-account (default: 10 minutes)
 # Secrets — store values in ansible/group_vars/all/vault.yml (Ansible Vault)
 # roundcube_db_password: ""
 # roundcube_des_key: ""   # generate: openssl rand -hex 12  (must be exactly 24 chars)
+#
+# Dovecot users — list of {username, password} pairs (plaintext, vault is encrypted)
+# dovecot_users:
+#   - username: alice
+#     password: "plaintext-password"
+#
+# Fetchmail accounts — list of external POP3 sources to poll
+# fetchmail_accounts:
+#   - server: pop.gmail.com
+#     username: user@gmail.com
+#     password: app-password
+#     local_user: alice
+#     protocol: pop3      # default: pop3
+#     ssl: true           # default: true
+#     keep: true          # default: true — set false to delete from source after fetch

 # Container registry (Docker Registry v2)
 registry_data_dir: /opt/registry
-# registry_htpasswd — full htpasswd file content, store in vault.yml
-# Generate with: docker run --entrypoint htpasswd httpd:2 -Bbn <user> <password>
-# Multiple users: run the command once per user and concatenate the lines.
-# Secrets — store values in ansible/group_vars/all/vault.yml (Ansible Vault)
-# registry_htpasswd: ""
+# Registry users — plaintext passwords, Ansible generates bcrypt hashes at deploy time
+# registry_users:
+#   - username: alice
+#     password: "your-password"

 # k8s (placeholder)
 k8s_data_dir: /opt/k8s
@@ -20,8 +20,14 @@ services:
      # Security
      - GITEA__security__SECRET_KEY={{ gitea_secret_key }}
      - GITEA__security__INTERNAL_TOKEN={{ gitea_internal_token }}
-      # Disable public registration — set to false only for initial admin setup
-      - GITEA__service__DISABLE_REGISTRATION={{ gitea_disable_registration | lower }}
+      # Allow account creation only via external auth (OAuth2/SSO).
+      # DISABLE_REGISTRATION=false is explicit because the setup wizard writes true to app.ini;
+      # ALLOW_ONLY_EXTERNAL_REGISTRATION then hides the sign-up form so only SSO accounts work.
+      - GITEA__service__DISABLE_REGISTRATION=false
+      - GITEA__service__ALLOW_ONLY_EXTERNAL_REGISTRATION=true
+      # Disable legacy OpenID 2.0 sign-in (distinct from the Keycloak OAuth2 integration)
+      - GITEA__openid__ENABLE_OPENID_SIGNIN=false
+      - GITEA__openid__ENABLE_OPENID_SIGNUP=false
    volumes:
      - {{ gitea_data_dir }}/data:/data
    ports:
@@ -1,6 +1,5 @@
 ---
-# Roundcube webmail client — connects to any external IMAP/SMTP server
- name: Create Roundcube data directories
+- name: Create mail data directories
  ansible.builtin.file:
    path: "{{ item }}"
    state: directory
@@ -20,6 +19,45 @@
    mode: "0700"
  tags: mail

+- name: Create Dovecot maildir (vmail UID 5000)
+  ansible.builtin.file:
+    path: "{{ mail_data_dir }}/maildir"
+    state: directory
+    owner: "5000"
+    group: "5000"
+    mode: "0755"
+  tags: mail
+
+- name: Deploy Dovecot config
+  ansible.builtin.template:
+    src: dovecot.conf.j2
+    dest: "{{ mail_data_dir }}/dovecot.conf"
+    owner: root
+    group: root
+    mode: "0644"
+  notify: Restart mail
+  tags: mail
+
+- name: Deploy Dovecot passwd file
+  ansible.builtin.template:
+    src: passwd.j2
+    dest: "{{ mail_data_dir }}/passwd"
+    owner: root
+    group: root
+    mode: "0640"
+  notify: Restart mail
+  tags: mail
+
+- name: Deploy fetchmail config
+  ansible.builtin.template:
+    src: fetchmailrc.j2
+    dest: "{{ mail_data_dir }}/fetchmailrc"
+    owner: root
+    group: root
+    mode: "0600"
+  notify: Restart mail
+  tags: mail
+
 - name: Deploy Docker Compose file
  ansible.builtin.template:
    src: docker-compose.yml.j2
@@ -30,7 +68,7 @@
  notify: Restart mail
  tags: mail

- name: Start Roundcube
+- name: Start mail stack
  community.docker.docker_compose_v2:
    project_src: "{{ mail_data_dir }}"
    state: present
@@ -18,6 +18,41 @@ services:
      timeout: 5s
      retries: 5

+  dovecot:
+    image: dovecot/dovecot:{{ dovecot_version }}
+    container_name: dovecot
+    restart: unless-stopped
+    volumes:
+      - {{ mail_data_dir }}/dovecot.conf:/etc/dovecot/dovecot.conf:ro
+      - {{ mail_data_dir }}/passwd:/etc/dovecot/passwd:ro
+      - {{ mail_data_dir }}/maildir:/var/mail
+    networks:
+      - traefik_public
+      - mail_internal
+    labels:
+      - "traefik.enable=true"
+      # TCP router — Traefik terminates TLS on port 993 and forwards plain IMAP to port 143
+      - "traefik.tcp.routers.imaps.rule=HostSNI(`{{ domain_mail }}`)"
+      - "traefik.tcp.routers.imaps.entrypoints=imaps"
+      - "traefik.tcp.routers.imaps.tls.certresolver=letsencrypt"
+      - "traefik.tcp.services.imaps.loadbalancer.server.port=143"
+
+{% if fetchmail_accounts | default([]) | length > 0 %}
+  fetchmail:
+    image: alpine:3
+    container_name: fetchmail
+    restart: unless-stopped
+    # apk add runs on each start — acceptable for a home server
+    command: ["sh", "-c", "apk add --no-cache fetchmail && exec fetchmail --nodetach -f /etc/fetchmail/fetchmailrc"]
+    volumes:
+      - {{ mail_data_dir }}/fetchmailrc:/etc/fetchmail/fetchmailrc:ro
+    networks:
+      - traefik_public
+      - mail_internal
+    depends_on:
+      - dovecot
+
+{% endif %}
  roundcube:
    image: roundcube/roundcubemail:{{ roundcube_version }}
    container_name: roundcube
@@ -30,14 +65,13 @@ services:
      ROUNDCUBEMAIL_DB_USER: roundcube
      ROUNDCUBEMAIL_DB_PASSWORD: "{{ roundcube_db_password }}"
      ROUNDCUBEMAIL_DB_NAME: roundcube
-      # IMAP — leave empty to let users enter their own server at login,
-      # or set to a specific host to lock it down (e.g. ssl://imap.example.com)
-      ROUNDCUBEMAIL_DEFAULT_HOST: "{{ roundcube_imap_host }}"
-      ROUNDCUBEMAIL_DEFAULT_PORT: "{{ roundcube_imap_port }}"
-      # SMTP
+      # IMAP — local Dovecot container
+      ROUNDCUBEMAIL_DEFAULT_HOST: "dovecot"
+      ROUNDCUBEMAIL_DEFAULT_PORT: "143"
+      # SMTP — outgoing mail server (leave empty if not configured)
      ROUNDCUBEMAIL_SMTP_SERVER: "{{ roundcube_smtp_host }}"
      ROUNDCUBEMAIL_SMTP_PORT: "{{ roundcube_smtp_port }}"
-      # Security — 24-character random string used to encrypt session data
+      # Security
      ROUNDCUBEMAIL_DES_KEY: "{{ roundcube_des_key }}"
      ROUNDCUBEMAIL_UPLOAD_MAX_FILESIZE: 25M
    networks:
@@ -53,6 +87,8 @@ services:
    depends_on:
      mail-db:
        condition: service_healthy
+      dovecot:
+        condition: service_started

 networks:
  traefik_public:
@@ -0,0 +1,43 @@
+# Managed by Ansible — do not edit manually
+protocols = imap lmtp
+
+# Plaintext auth is fine — connections come from within Docker or via
+# Traefik TLS termination, never plain from the internet
+disable_plaintext_auth = no
+auth_mechanisms = plain login
+
+passdb {
+  driver = passwd-file
+  args = /etc/dovecot/passwd
+}
+
+userdb {
+  driver = passwd-file
+  args = /etc/dovecot/passwd
+  default_fields = uid=5000 gid=5000 home=/var/mail/%u
+}
+
+mail_location = maildir:/var/mail/%u/Maildir
+mail_uid = 5000
+mail_gid = 5000
+
+service imap-login {
+  inet_listener imap {
+    port = 143
+  }
+  # IMAPS disabled — Traefik terminates TLS on port 993 and forwards plain IMAP
+  inet_listener imaps {
+    port = 0
+  }
+}
+
+# LMTP listener for fetchmail delivery — reachable on mail_internal network only
+service lmtp {
+  inet_listener lmtp {
+    address = *
+    port = 24
+  }
+}
+
+# SSL disabled — Traefik handles TLS
+ssl = no
@@ -0,0 +1,20 @@
+# Managed by Ansible — do not edit manually
+set postmaster "postmaster"
+set bouncemail
+set logfile /dev/stdout
+# Wake up every 60 seconds; each server's 'interval' is a multiplier of this
+set daemon 60
+
+{% for account in fetchmail_accounts | default([]) %}
+poll {{ account.server }} proto {{ account.protocol | default('pop3') }}{% if account.ssl | default(true) %} ssl{% endif %}
+
+  user "{{ account.username }}" password "{{ account.password }}"
+  is {{ account.local_user }} here
+  smtphost dovecot
+  smtpport 24
+  lmtp
+  fetchall
+  {{ 'keep' if account.keep | default(true) else 'no keep' }}
+  interval {{ account.poll_minutes | default(10) }}
+
+{% endfor %}
@@ -0,0 +1,4 @@
+# Managed by Ansible — do not edit manually
+{% for user in dovecot_users | default([]) %}
+{{ user.username }}:{SHA512-CRYPT}{{ user.password | password_hash('sha512', (user.username | hash('md5'))[:16]) }}
+{% endfor %}
@@ -12,10 +12,9 @@
    - "{{ registry_data_dir }}/auth"
  tags: registry

-# htpasswd content is stored in vault and deployed as a file
 - name: Deploy htpasswd file
-  ansible.builtin.copy:
-    content: "{{ registry_htpasswd }}\n"
+  ansible.builtin.template:
+    src: htpasswd.j2
    dest: "{{ registry_data_dir }}/auth/htpasswd"
    owner: root
    group: root
@@ -0,0 +1,4 @@
+# Managed by Ansible — do not edit manually
+{% for user in registry_users | default([]) %}
+{{ user.username }}:{{ user.password | password_hash('bcrypt', (user.username | hash('md5'))[:22]) }}
+{% endfor %}
@@ -47,7 +47,7 @@ services:
      - "traefik.http.routers.sso.entrypoints=websecure"
      - "traefik.http.routers.sso.tls.certresolver=letsencrypt"
      - "traefik.http.services.sso.loadbalancer.server.port=8080"
-      - "traefik.http.routers.sso.middlewares=rate-limit@docker"
+      - "traefik.http.routers.sso.middlewares=rate-limit-lax@docker"
    healthcheck:
      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/localhost/9000"]
      interval: 30s
@@ -7,6 +7,7 @@ services:
    ports:
      - "80:80"
      - "443:443"
+      - "993:993"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - {{ traefik_data_dir }}/traefik.yml:/traefik.yml:ro
@@ -22,7 +23,11 @@ services:
      - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
-      - "traefik.http.middlewares.dashboard-auth.basicauth.users={{ traefik_dashboard_users }}"
+{% set ns = namespace(entries=[]) %}
+{% for user in traefik_dashboard_users | default([]) %}
+{% set ns.entries = ns.entries + [user.username + ':' + (user.password | password_hash('bcrypt', (user.username | hash('md5'))[:22]) | replace('$', '$$'))] %}
+{% endfor %}
+      - "traefik.http.middlewares.dashboard-auth.basicauth.users={{ ns.entries | join(',') }}"
      # Rate-limit middlewares — referenced by services as rate-limit@docker / rate-limit-lax@docker
      # Standard: 60 req/min per IP, burst 20 — protects all services from bot floods
      - "traefik.http.middlewares.rate-limit.rateLimit.average=60"
@@ -24,6 +24,8 @@ entryPoints:
          permanent: true
  websecure:
    address: ":443"
+  imaps:
+    address: ":993"

 providers:
  docker:
@@ -32,48 +32,171 @@ Once the script passes, open `https://cloud.ladkau.de/dashboard/` in a browser
 and authenticate with the `traefik_dashboard_users` credentials to verify the
 dashboard loads correctly.

-## Gitea
+## 2. Keycloak

-`gitea_disable_registration` defaults to `true`. For the first deploy, override
-it to `false` so the setup wizard can create the admin account:
+Keycloak is the identity provider for all services. Configure it first so that
+Gitea and Nextcloud can be wired up to SSO in the steps that follow.
+
+Keycloak takes ~90 seconds to start on first boot. If the login page at
+`https://sso.ladkau.de` is not immediately available, wait and retry.
+
+### 2.1 Log in and change the admin password
+
+1. Go to `https://sso.ladkau.de` and sign in with username `admin` and the
+   value of `keycloak_admin_password` from the vault.
+2. Click the **admin** dropdown (top right) → **Manage account** →
+   **Password** → set a new password.
+
+The bootstrap credentials are only used on first start. After changing the
+password, the vault value is no longer authoritative — store the new password
+in your password manager.
+
+### 2.2 Create an application realm
+
+1. In the left sidebar, click the realm dropdown (shows **master**) →
+   **Create realm**.
+2. Set **Realm name** to `ladkau` and click **Create**.
+3. Make sure the `ladkau` realm is selected in the sidebar for all steps below.
+
+The `master` realm is for Keycloak administration only. All application users
+and clients live in `ladkau`.
+
+### 2.3 Create users
+
+For each user you want to be able to log in to Gitea and Nextcloud:
+
+1. **Users** → **Add user**.
+2. Fill in **Username**, **Email**, **First name**, **Last name** → **Create**.
+3. Go to the **Credentials** tab → **Set password**.
+4. Enter a password, turn off **Temporary**, and click **Save**.
+
+### 2.4 Create the Gitea OIDC client
+
+1. **Clients** → **Create client**.
+2. **Client type**: OpenID Connect — **Client ID**: `gitea` → **Next**.
+3. Turn **Client authentication** on (confidential client) → **Next**.
+4. **Valid redirect URIs**: `https://gitea.ladkau.de/user/oauth2/keycloak/callback`
+5. **Web origins**: `https://gitea.ladkau.de` → **Save**.
+6. Go to the **Credentials** tab and copy the **Client secret** — you will
+   need it in step 3.
+
+### 2.5 Create the Nextcloud OIDC client
+
+1. **Clients** → **Create client**.
+2. **Client type**: OpenID Connect — **Client ID**: `nextcloud` → **Next**.
+3. Turn **Client authentication** on → **Next**.
+4. **Valid redirect URIs**: `https://nextcloud.ladkau.de/apps/user_oidc/code`
+5. **Valid post logout redirect URIs**: `https://nextcloud.ladkau.de/*`
+6. **Web origins**: `https://nextcloud.ladkau.de` → **Save**.
+7. Go to the **Credentials** tab and copy the **Client secret** — you will
+   need it in step 4.
+
+## 3. Gitea
+
+### 3.1 Create the admin account
+
+1. Go to `https://gitea.ladkau.de` — Gitea shows an initial configuration
+   dialog on the first visit.
+2. Scroll to the bottom of the form to the **Administrator Account Settings**
+   section and fill in the admin username, email, and password.
+3. Click **Install Gitea**.
+
+Gitea initialises the database and creates the admin account in one step.
+Public registration is closed — only users authenticating via Keycloak can
+get an account (controlled by `ALLOW_ONLY_EXTERNAL_REGISTRATION`).
+
+### 3.2 Connect Gitea to Keycloak
+
+1. In Gitea, go to **Site Administration** → **Identity & Access** →
+   **Authentication Sources** → **Add Authentication Source**.
+2. Set **Authentication type** to **OAuth2**.
+3. Set **OAuth2 provider** to **OpenID Connect**.
+4. Fill in:
+   - **Name**: `keycloak`
+   - **Client ID**: `gitea`
+   - **Client secret**: the secret copied in step 2.4
+   - **OpenID Connect Auto Discovery URL**:
+     `https://sso.ladkau.de/realms/ladkau/.well-known/openid-configuration`
+5. Click **Add Authentication Source**.
+
+Users can now sign in via **Sign in with keycloak** on the Gitea login page.
+
+## 4. Nextcloud
+
+The admin credentials are set via `nextcloud_admin_user` and
+`nextcloud_admin_password` in the vault. The first HTTP request triggers
+installation, which takes a minute or two.
+
+### 4.1 Log in
+
+1. Go to `https://nextcloud.ladkau.de` and sign in with the admin credentials
+   from the vault.
+
+### 4.2 Connect Nextcloud to Keycloak
+
+1. Go to **Apps** → search for **OpenID Connect user backend** → **Download
+   and enable**.
+2. Go to **Administration settings** → **OpenID Connect** → **Add provider**.
+3. Fill in:
+   - **Identifier**: `keycloak`
+   - **Client ID**: `nextcloud`
+   - **Client secret**: the secret copied in step 2.5
+   - **Discovery endpoint**:
+     `https://sso.ladkau.de/realms/ladkau/.well-known/openid-configuration`
+4. Click **Save**.
+
+Users can now sign in to Nextcloud with their Keycloak credentials via the
+**Log in with keycloak** button.
+
+## 5. Mail (Dovecot + Roundcube + Fetchmail)
+
+The mail stack runs a local Dovecot IMAP server. Roundcube connects to it
+internally. External IMAP clients connect to `mail.ladkau.de:993` (IMAPS —
+TLS terminated by Traefik). Fetchmail polls external POP3 accounts and
+delivers to Dovecot.
+
+Dovecot users and fetchmail accounts are configured in the vault before
+provisioning — see step 4 of `runbook-provisioning.md`. To add users or
+accounts after initial deployment, edit the vault and redeploy:

 ```bash
 ansible-vault edit ansible/group_vars/all/vault.yml
-# add: gitea_disable_registration: false
-ansible-playbook -i ansible/inventory.ini ansible/site.yml --tags gitea --ask-vault-pass
+ansible-playbook -i ansible/inventory.ini ansible/site.yml --tags mail --ask-vault-pass
 ```

-After the admin account is created at `https://gitea.ladkau.de`, remove the
-override and redeploy to close public registration.
+### 5.1 Import mail from an old Dovecot server

-## Keycloak
+If migrating from an existing Dovecot server, sync the Maildir directly:

-`KEYCLOAK_ADMIN` / `KEYCLOAK_ADMIN_PASSWORD` bootstrap the initial admin account
-on first start only — Keycloak ignores them once the account exists. After
-logging in at `https://sso.ladkau.de`, change the admin password via the UI.
+```bash
+# Run on the old server — syncs to the new server's maildir volume
+rsync -av --progress /var/mail/alice/Maildir/ \
+  root@217.154.207.148:/opt/mail/maildir/alice/Maildir/

-Keycloak takes ~90 seconds to start. If the login page is not immediately
-available, wait and retry.
-
-## Nextcloud
-
-Nextcloud runs its first-time installation on the initial HTTP request, which
-takes a minute or two. The admin credentials are set via `nextcloud_admin_user`
-and `nextcloud_admin_password` in the vault.
-
-## Roundcube
-
-Roundcube is a webmail client — it does not host mail itself. Configure the IMAP
-and SMTP servers it connects to via `ansible/group_vars/all/vars.yml`:
-
-```yaml
-roundcube_imap_host: "ssl://mail.example.com"  # implicit TLS (port 993)
-roundcube_smtp_host: "mail.example.com"         # STARTTLS (port 587)
+# Fix ownership for Dovecot's vmail user (UID 5000)
+ssh root@217.154.207.148 "chown -R 5000:5000 /opt/mail/maildir/alice"
 ```

-Leave both empty to let users enter their own server at login.
+Alternatively, use `imapsync` to copy via IMAP from the old server to the
+new one (works without direct server access):

-## Container registry
+```bash
+imapsync \
+  --host1 old.server.com --user1 alice --password1 oldpass \
+  --host2 mail.ladkau.de  --user2 alice --password2 newpass \
+  --port2 993 --ssl2
+```
+
+### 5.2 Connect an IMAP client
+
+| Setting   | Value                |
+|-----------|----------------------|
+| Server    | `mail.ladkau.de`     |
+| Port      | `993`                |
+| Security  | SSL/TLS              |
+| Username  | as set in vault      |
+
+## 6. Container registry

 ```bash
 # Login
@@ -87,11 +210,11 @@ docker push cr.ladkau.de/myimage:latest
 docker pull cr.ladkau.de/myimage:latest
 ```

-Registry credentials are managed via `registry_htpasswd` in the vault. To add
-or rotate a user, regenerate the htpasswd entry and redeploy:
+Registry users are managed via `registry_users` in the vault — store plaintext
+passwords, Ansible generates bcrypt hashes at deploy time. To add or rotate a
+user, edit the vault and redeploy:

 ```bash
-docker run --entrypoint htpasswd httpd:2 -Bbn <user> <password>
-# update registry_htpasswd in vault, then:
+ansible-vault edit ansible/group_vars/all/vault.yml
 ansible-playbook -i ansible/inventory.ini ansible/site.yml --tags registry --ask-vault-pass
 ```
@@ -11,8 +11,6 @@ setup of individual services.
 ### Local tools

 - Ansible installed (`pip install ansible`)
- `htpasswd` available (`apt install apache2-utils` or `brew install httpd`)
- `docker` available (for generating the registry htpasswd entry)
 - `openssl` available (for generating secrets)

 ### SSH keys
@@ -89,35 +87,51 @@ Create `ansible/group_vars/all/vault.yml` (gitignored) and encrypt it with Ansib
 ansible-vault create ansible/group_vars/all/vault.yml
 ```

-Populate all required secrets:
+Populate all required secrets. Ansible generates all password hashes at
+deploy time — store plaintext values here (the vault is encrypted).

 ```yaml
-# Traefik dashboard basic auth
-# Generate: echo $(htpasswd -nB admin) | sed -e 's/\$/\$\$/g'
-traefik_dashboard_users: "admin:$$2y$$05$$..."
+# Traefik dashboard basic auth — generate with: openssl rand -hex 32
+traefik_dashboard_users:
+  - username: admin
+    password: "your-password"

-# Gitea
-# Generate secrets: openssl rand -hex 32
+# Gitea — generate with: openssl rand -hex 32
 gitea_db_password: ""
 gitea_secret_key: ""
 gitea_internal_token: ""

-# Keycloak
+# Keycloak — generate with: openssl rand -hex 32
 keycloak_db_password: ""
 keycloak_admin_password: ""

-# Nextcloud
+# Nextcloud — generate with: openssl rand -hex 32
 nextcloud_db_password: ""
 nextcloud_admin_password: ""

-# Roundcube
-# des_key must be exactly 24 characters: openssl rand -hex 12
+# Roundcube — des_key must be exactly 24 characters: openssl rand -hex 12
 roundcube_db_password: ""
 roundcube_des_key: ""

-# Container registry
-# Generate: docker run --entrypoint htpasswd httpd:2 -Bbn <user> <password>
-registry_htpasswd: "user:$2y$05$..."
+# Container registry — generate with: openssl rand -hex 32
+registry_users:
+  - username: alice
+    password: "your-password"
+
+# Dovecot IMAP users — generate with: openssl rand -hex 32
+dovecot_users:
+  - username: alice
+    password: "your-password"
+
+# Fetchmail — external POP3 accounts to pull from (omit section if not needed)
+# fetchmail_accounts:
+#   - server: pop.gmail.com
+#     username: user@gmail.com
+#     password: app-password    # use a Gmail App Password, not your main password
+#     local_user: alice
+#     ssl: true
+#     keep: true                # set false to delete from source after fetching
+#     poll_minutes: 10          # how often to poll this account (default: 10)
 ```

 Verify all secrets are present and non-empty:
@@ -9,23 +9,9 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 VAULT_FILE="${REPO_ROOT}/ansible/group_vars/all/vault.yml"

-REQUIRED_KEYS=(
-  traefik_dashboard_users
-  gitea_db_password
-  gitea_secret_key
-  gitea_internal_token
-  keycloak_db_password
-  keycloak_admin_password
-  nextcloud_db_password
-  nextcloud_admin_password
-  roundcube_db_password
-  roundcube_des_key
-  registry_htpasswd
-)
-
 if [ ! -f "${VAULT_FILE}" ]; then
  echo "ERROR: vault file not found at ${VAULT_FILE}" >&2
-  echo "       Create it with: ansible-vault create ansible/group_vars/vault.yml" >&2
+  echo "       Create it with: ansible-vault create ansible/group_vars/all/vault.yml" >&2
  exit 1
 fi

@@ -37,23 +23,51 @@ fi
 echo "==> Decrypting vault (you will be prompted for the vault password)"
 VAULT_CONTENT=$(ansible-vault view "${VAULT_FILE}")

-MISSING=()
-for key in "${REQUIRED_KEYS[@]}"; do
-  # Match lines like:   key: "value"  or  key: value  — but not  key: ""  or  key: ''  or missing
-  if ! echo "${VAULT_CONTENT}" | grep -qE "^${key}:[[:space:]]+[^'\"[:space:]]|^${key}:[[:space:]]+['\"].+['\"]"; then
-    MISSING+=("${key}")
-  fi
-done
+echo "${VAULT_CONTENT}" | python3 - <<'PYEOF'
+import sys, yaml

-if [ ${#MISSING[@]} -gt 0 ]; then
-  echo "" >&2
-  echo "ERROR: the following secrets are missing or empty in vault.yml:" >&2
-  for key in "${MISSING[@]}"; do
-    echo "       - ${key}" >&2
-  done
-  echo "" >&2
-  echo "Edit the vault with: ansible-vault edit ansible/group_vars/vault.yml" >&2
-  exit 1
-fi
+data = yaml.safe_load(sys.stdin.read())

-echo "    OK — all required secrets are present"
+# Required non-empty scalar strings
+required_scalars = [
+    "gitea_db_password",
+    "gitea_secret_key",
+    "gitea_internal_token",
+    "keycloak_db_password",
+    "keycloak_admin_password",
+    "nextcloud_db_password",
+    "nextcloud_admin_password",
+    "roundcube_db_password",
+    "roundcube_des_key",
+]
+
+# Required non-empty lists (must contain at least one entry)
+required_lists = [
+    "traefik_dashboard_users",
+    "registry_users",
+    "dovecot_users",
+]
+
+missing = []
+
+for key in required_scalars:
+    val = data.get(key, "")
+    if not val or str(val).strip() in ("", '""', "''"):
+        missing.append(key)
+
+for key in required_lists:
+    val = data.get(key)
+    if not isinstance(val, list) or len(val) == 0:
+        missing.append(key)
+
+if missing:
+    print("", file=sys.stderr)
+    print("ERROR: the following secrets are missing or empty in vault.yml:", file=sys.stderr)
+    for key in missing:
+        print(f"       - {key}", file=sys.stderr)
+    print("", file=sys.stderr)
+    print("Edit the vault with: ansible-vault edit ansible/group_vars/all/vault.yml", file=sys.stderr)
+    sys.exit(1)
+
+print("    OK — all required secrets are present")
+PYEOF