matthias/server_cloud_ladkau_de
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
ml
2026-06-28 14:13:53 +02:00
parent fdcc0079cb
commit 187c6bdea4
15 changed files with 436 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/runbook-configuration.md
+157 -34
View File
@@ -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
```
docs/runbook-provisioning.md
+29 -15
View File
@@ -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: