From e9c1ec58851d5ca790a294414f44c67fdb89ad38 Mon Sep 17 00:00:00 2001
From: yena <yena@systemli.org>
Date: Sun, 23 Feb 2025 21:14:22 +0100
Subject: [PATCH] Documentation: Various improvements

---
 docs/development/index.md    |  4 +---
 docs/installation/dovecot.md | 36 ++++++++++++++++++++++++------------
 2 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/docs/development/index.md b/docs/development/index.md
index fa22bb41..245ee188 100644
--- a/docs/development/index.md
+++ b/docs/development/index.md
@@ -28,8 +28,7 @@ Start the containers:
     ```
 
 !!! info
-    `$command compose up -d` will initiate building the containers on first run. Append `--build` to force a full rebuild
-
+    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:
@@ -56,7 +55,6 @@ Initialize the database and install sample data:
     docker compose exec userli bin/console doctrine:fixtures:load
     ```
 
-
 Open your browser and go to [http://localhost:8000](http://localhost:8000)
 
 
diff --git a/docs/installation/dovecot.md b/docs/installation/dovecot.md
index b08816f7..66c8ca71 100644
--- a/docs/installation/dovecot.md
+++ b/docs/installation/dovecot.md
@@ -8,7 +8,7 @@ If the mailcrypt is enabled in Userli, the Lua adapter will also forward the req
 
 ## On the Userli Host
 
-In `.env.local`, following environment variables needs to be configured:
+Following environment variables needs to be configured, for example via `.env.local`:
 
 ```shell
 DOVECOT_API_ENABLED=true
@@ -20,16 +20,37 @@ DOVECOT_API_ACCESS_TOKEN="replace-me-with-a-secure-token"
 
 ### 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
-import_environment=USERLI_API_ACCESS_TOKEN USERLI_HOST DOVECOT_LUA_DEBUG DOVECOT_LUA_INSECURE
+# 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
@@ -42,16 +63,6 @@ userdb {
 }
 ```
 
-Export the env vars to be picked up by Dovecots `import_environment` config:
-
-- `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`
-
 ## MailCrypt
 
 In order to enable MailCrypt in Dovecot, the following is required:
@@ -61,3 +72,4 @@ In order to enable MailCrypt in Dovecot, the following is required:
 
 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.
+c
\ No newline at end of file