From 187c6bdea424bfdf74bbdbe1e52a69bf850e84be Mon Sep 17 00:00:00 2001 From: ml Date: Sun, 28 Jun 2026 14:13:53 +0200 Subject: [PATCH] Add Dovecot IMAP + Fetchmail, fix Gitea SSO, simplify credential management MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- ansible/group_vars/all/vars.yml | 48 +++-- .../gitea/templates/docker-compose.yml.j2 | 10 +- ansible/roles/mail/tasks/main.yml | 44 +++- .../mail/templates/docker-compose.yml.j2 | 48 ++++- ansible/roles/mail/templates/dovecot.conf.j2 | 43 ++++ ansible/roles/mail/templates/fetchmailrc.j2 | 20 ++ ansible/roles/mail/templates/passwd.j2 | 4 + ansible/roles/registry/tasks/main.yml | 5 +- ansible/roles/registry/templates/htpasswd.j2 | 4 + .../roles/sso/templates/docker-compose.yml.j2 | 2 +- .../traefik/templates/docker-compose.yml.j2 | 7 +- .../roles/traefik/templates/traefik.yml.j2 | 2 + docs/runbook-configuration.md | 191 ++++++++++++++---- docs/runbook-provisioning.md | 44 ++-- scripts/check-vault.sh | 80 +++++--- 15 files changed, 436 insertions(+), 116 deletions(-) create mode 100644 ansible/roles/mail/templates/dovecot.conf.j2 create mode 100644 ansible/roles/mail/templates/fetchmailrc.j2 create mode 100644 ansible/roles/mail/templates/passwd.j2 create mode 100644 ansible/roles/registry/templates/htpasswd.j2 diff --git a/ansible/group_vars/all/vars.yml b/ansible/group_vars/all/vars.yml index 1671b54..583557d 100644 --- a/ansible/group_vars/all/vars.yml +++ b/ansible/group_vars/all/vars.yml @@ -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 -# 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 diff --git a/ansible/roles/gitea/templates/docker-compose.yml.j2 b/ansible/roles/gitea/templates/docker-compose.yml.j2 index 6ad5a94..ad609c8 100644 --- a/ansible/roles/gitea/templates/docker-compose.yml.j2 +++ b/ansible/roles/gitea/templates/docker-compose.yml.j2 @@ -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: diff --git a/ansible/roles/mail/tasks/main.yml b/ansible/roles/mail/tasks/main.yml index 6afae12..ad8d751 100644 --- a/ansible/roles/mail/tasks/main.yml +++ b/ansible/roles/mail/tasks/main.yml @@ -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 diff --git a/ansible/roles/mail/templates/docker-compose.yml.j2 b/ansible/roles/mail/templates/docker-compose.yml.j2 index 78b3299..9814382 100644 --- a/ansible/roles/mail/templates/docker-compose.yml.j2 +++ b/ansible/roles/mail/templates/docker-compose.yml.j2 @@ -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: diff --git a/ansible/roles/mail/templates/dovecot.conf.j2 b/ansible/roles/mail/templates/dovecot.conf.j2 new file mode 100644 index 0000000..64f12f3 --- /dev/null +++ b/ansible/roles/mail/templates/dovecot.conf.j2 @@ -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 diff --git a/ansible/roles/mail/templates/fetchmailrc.j2 b/ansible/roles/mail/templates/fetchmailrc.j2 new file mode 100644 index 0000000..b88c326 --- /dev/null +++ b/ansible/roles/mail/templates/fetchmailrc.j2 @@ -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 %} diff --git a/ansible/roles/mail/templates/passwd.j2 b/ansible/roles/mail/templates/passwd.j2 new file mode 100644 index 0000000..f36d438 --- /dev/null +++ b/ansible/roles/mail/templates/passwd.j2 @@ -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 %} diff --git a/ansible/roles/registry/tasks/main.yml b/ansible/roles/registry/tasks/main.yml index b2dfbde..3862b29 100644 --- a/ansible/roles/registry/tasks/main.yml +++ b/ansible/roles/registry/tasks/main.yml @@ -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 diff --git a/ansible/roles/registry/templates/htpasswd.j2 b/ansible/roles/registry/templates/htpasswd.j2 new file mode 100644 index 0000000..0d34b28 --- /dev/null +++ b/ansible/roles/registry/templates/htpasswd.j2 @@ -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 %} diff --git a/ansible/roles/sso/templates/docker-compose.yml.j2 b/ansible/roles/sso/templates/docker-compose.yml.j2 index dcebe50..bc594a9 100644 --- a/ansible/roles/sso/templates/docker-compose.yml.j2 +++ b/ansible/roles/sso/templates/docker-compose.yml.j2 @@ -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 diff --git a/ansible/roles/traefik/templates/docker-compose.yml.j2 b/ansible/roles/traefik/templates/docker-compose.yml.j2 index c5a659b..2044726 100644 --- a/ansible/roles/traefik/templates/docker-compose.yml.j2 +++ b/ansible/roles/traefik/templates/docker-compose.yml.j2 @@ -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" diff --git a/ansible/roles/traefik/templates/traefik.yml.j2 b/ansible/roles/traefik/templates/traefik.yml.j2 index 708fffe..2dc1aa9 100644 --- a/ansible/roles/traefik/templates/traefik.yml.j2 +++ b/ansible/roles/traefik/templates/traefik.yml.j2 @@ -24,6 +24,8 @@ entryPoints: permanent: true websecure: address: ":443" + imaps: + address: ":993" providers: docker: diff --git a/docs/runbook-configuration.md b/docs/runbook-configuration.md index 311e0a3..9d49e16 100644 --- a/docs/runbook-configuration.md +++ b/docs/runbook-configuration.md @@ -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 -# 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 ``` diff --git a/docs/runbook-provisioning.md b/docs/runbook-provisioning.md index eaf9826..295b0c4 100644 --- a/docs/runbook-provisioning.md +++ b/docs/runbook-provisioning.md @@ -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 -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: diff --git a/scripts/check-vault.sh b/scripts/check-vault.sh index e8b24d6..7c858b1 100755 --- a/scripts/check-vault.sh +++ b/scripts/check-vault.sh @@ -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