Update docs

docs/development/index.md

@@ -1,13 +1,19 @@
 # Getting started
 
-The easiest way to get started with Userli is to use podman or docker.
-We provide a `docker-compose.yml` file that starts Userli, Dovecot and MariaDB.
+We provide a `docker-compose.yml` file that starts Userli, Dovecot and MariaDB to set up a development environment.
+
+## Requirements
+
+- `docker-compose` or `podman-compose`
+- `yarn` (or `yarn-pkg` on Ubuntu or Debian based systems)
+- `composer`
 
 !!! info
     If you don't have podman or docker installed, you can find the installation instructions on the [podman website](https://podman.io/getting-started/installation) or the [docker website](https://docs.docker.com/get-docker/).
 
+## Set up
 
-Start Userli, Dovecot and MariaDB with podman or docker:
+Start the containers:
 
 === "podman"
 
@@ -21,34 +27,31 @@ Start Userli, Dovecot and MariaDB with podman or docker:
     docker compose up -d
     ```
 
-Install dependencies and run composer scripts:
+!!! info
+    This command will initiate building the containers on first run. Append `--build` to always force a full rebuild
+
+
+Install PHP dependencies, run composer scripts and update assets:
+
 
 ```shell
 composer install --ignore-platform-reqs
+yarn
+yarn encore dev
 ```
 
-Initialize the database:
+Initialize the database and install sample data:
 
 === "podman"
 
     ```shell
     podman compose exec userli bin/console doctrine:schema:create
-    ```
-
-=== "docker"
-    ```shell
-    docker compose exec userli bin/console doctrine:schema:create
-    ```
-
-Install sample data:
-
-=== "podman"
-    ```shell
     podman compose exec userli bin/console doctrine:fixtures:load
     ```
 
 === "docker"
     ```shell
+    docker compose exec userli bin/console doctrine:schema:create
     docker compose exec userli bin/console doctrine:fixtures:load
     ```
 

docs/installation/dovecot.md

@@ -0,0 +1,74 @@
+# Dovecot Authentication 
+
+Userli provides an API for `userdb` and `passdb` lookups.
+This can be used to authenticate users with Dovecot by using [Lua based authentication](https://doc.dovecot.org/2.3/configuration_manual/authentication/lua_based_authentication/).
+An adapter script is provided in the source code in `contrib/dovecot/userli.lua`.
+
+If the mailcrypt is enabled in Userli, the Lua adapter will also forward the required key material with each lookup.
+
+## On the Userli Host
+
+Following environment variables needs to be configured, for example via `.env.local`:
+
+```shell
+DOVECOT_API_ENABLED=true
+DOVECOT_API_IP_ALLOWLIST="127.0.0.1, ::1"
+DOVECOT_API_ACCESS_TOKEN="replace-me-with-a-secure-token"
+```
+
+## On the Dovecot host
+
+### Prerequisites
+
+On Debian based systems, following packages are required:
+
+* `lua`
+* `json-lua`
+* `dovecot-auth-lua`
+
+!!! warning
+   Debian 12 ships version 1.3.4-2 of `json-lua`, which does not include the library for the lua5.4 runtime.
+   This can be solved with symlinks:
+   ```shell
+   sudo ln -s  /usr/share/lua/5.3/json.lua  /usr/share/lua/5.4/
+   sudo ln -s  /usr/share/lua/5.3/json  /usr/share/lua/5.4/
+   ```
+
+## Export environment variables
+
+- `USERLI_API_ACCESS_TOKEN` (mandatory)
+- `USERLI_HOST` (mandatory)
+- `DOVECOT_LUA_AGENT`, defaults "Dovecot-Lua-Auth"
+- `DOVECOT_LUA_INSECURE`, to connect to the Userli host via unencrypted HTTP, defaults to `false`
+- `DOVECOT_LUA_DEBUG`, defaults to `false`
+- `DOVECOT_LUA_MAX_ATTEMPTS`, defaults to `3`
+- `DOVECOT_LUA_TIMEOUT`, defaults to `10000`
+
+### Example configuration
+
+`/etc/dovecot/conf.d/auth-lua.conf.ext`:
+
+```text
+# Any of the above env vars needs to be explicitly imported here in order to be available to the Lua adapter:
+import_environment=USERLI_API_ACCESS_TOKEN USERLI_HOST
+
+passdb {
+  driver = lua
+  args = file=/path/to/userli-adapter.lua blocking=yes
+}
+
+userdb {
+  driver = lua
+  args = file=/path/to/userli-adapter.lua blocking=yes
+}
+```
+
+## MailCrypt
+
+In order to enable MailCrypt in Dovecot, the following is required:
+
+* Add `mail_crypt` to the `mail_plugins` list in `/etc/dovecot/conf.d/10-mail.conf`
+* Set `mail_crypt_save_version = 0` in `/etc/dovecot/conf.d/90-mail-crypt.conf`
+
+The latter disables MailCrypt per default and is necessary to not break incoming mail for legacy users without MailCrypt keys.
+The Lua adapter automatically sets `mail_crypt_save_version = 2` for all users with MailCrypt keys.

docs/mail_crypt/index.md

@@ -3,8 +3,9 @@
 The software has builtin support for
 [Dovecot's mailbox encryption](https://wiki.dovecot.org/Plugins/MailCrypt), using the
 [global keys mode](https://wiki.dovecot.org/Plugins/MailCrypt#Global_keys).
-Keys are created and maintained by userli and handed over to Dovecot via
-`checkpassword` script.
+Keys are created and maintained by userli and handed over via an API and can
+be consumed by Dovecot by a Lua script. See [here](/installation/dovecot)
+for how to configure authentication and mailcrypt in Dovecot.
 
 The MailCrypt feature is enabled per default and can optionally be switched
 off globally by setting `MAIL_CRYPT=0` in the dotenv (`.env`) file.
@@ -20,16 +21,6 @@ have MailCrypt enabled per default, you can set `MAIL_CRYPT=1` in the dotenv
 * `MAIL_CRYPT=3` - Enforce MailCrypt key generation for all users, see the
                    documentation about migrating legacy users for more info
 
-In order to enable MailCrypt in Dovecot, the following is required:
-
-* Add `mail_crypt` to the `mail_plugins` list in `/etc/dovecot/conf.d/10-mail.conf`
-* Set `mail_crypt_save_version = 0` in `/etc/dovecot/conf.d/90-mail-crypt.conf`
-
-The latter disables MailCrypt per default and is necessary to not break
-incoming mail for legacy users without MailCrypt keys. The checkpassword script
-automatically sets `mail_crypt_save_version = 2` for all users with MailCrypt
-keys.
-
 MailCrypt can be turned on/off for individual users by setting the `mail_crypt`
 switch in the `virtual_users` database table. This switch is mainly meant to
 provide a migration path from legacy users without MailCrypt keys. On new

mkdocs.yml

@@ -13,11 +13,11 @@ nav:
       - Tests: development/tests.md
   - Installation:
       - Installation: installation/index.md
-      - Checkpassword: installation/checkpassword.md
       - Commands: installation/commands.md
       - Configuration: installation/configuration.md
       - Customize: installation/customize.md
       - Database: installation/database.md
+      - Dovecot: installation/dovecot.md
       - Finalize: installation/finalize.md
       - Webserver: installation/webserver.md
   - MailCrypt: