Documentation: Various improvements

systemli · Feb 23, 2025 · e9c1ec5 · e9c1ec5
1 parent 248f360
commit e9c1ec5
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 15 deletions.
diff --git 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
@@ -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