# Configuration Runbook

First-run configuration steps to perform after the Ansible playbook has
provisioned the server. See `runbook-provisioning.md` for the provisioning steps.

## 1. Verify all services are reachable

Before configuring individual services, confirm every HTTPS endpoint is up and
TLS certificates are valid. Run this from your local machine:

```bash
bash scripts/check-services.sh
```

The script checks these endpoints and verifies the expected HTTP status code:

| URL | Expected | Notes |
|-----|----------|-------|
| `https://cloud.ladkau.de/dashboard/` | 401 | Basic-auth prompt — correct without credentials |
| `https://gitea.ladkau.de` | 200 | Gitea sign-in page |
| `https://nextcloud.ladkau.de` | 200 | First visit triggers setup and takes 1–2 min |
| `https://sso.ladkau.de/realms/master` | 200 | Keycloak realm JSON — first start takes ~90 s |
| `https://mail.ladkau.de` | 200 | Roundcube webmail login |
| `https://cr.ladkau.de/v2/` | 401 | Registry API — auth required, correct without credentials |
| `https://k8s.ladkau.de` | 200 | Placeholder page |

A `000` result means the connection was refused or timed out — a container that
did not start. Keycloak and Nextcloud may return `502` for up to 90 seconds on
first boot; wait and retry before investigating.

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

`gitea_disable_registration` defaults to `true`. For the first deploy, override
it to `false` so the setup wizard can create the admin account:

```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
```

After the admin account is created at `https://gitea.ladkau.de`, remove the
override and redeploy to close public registration.

## Keycloak

`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.

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)
```

Leave both empty to let users enter their own server at login.

## Container registry

```bash
# Login
docker login cr.ladkau.de

# Push
docker tag myimage:latest cr.ladkau.de/myimage:latest
docker push cr.ladkau.de/myimage:latest

# Pull
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:

```bash
docker run --entrypoint htpasswd httpd:2 -Bbn <user> <password>
# update registry_htpasswd in vault, then:
ansible-playbook -i ansible/inventory.ini ansible/site.yml --tags registry --ask-vault-pass
```