feat(web): allow php session storage configuration via environment variables

Author: jeboehm

README.md

@@ -104,6 +104,7 @@ and the documentation [Use another MySQL instance](docs/EXTERNAL_MYSQL.md) for d
 - [TLS Configuration](docs/TLS.md)
 - [External MySQL](docs/EXTERNAL_MYSQL.md)
 - [Relayhost Configuration](docs/RELAYHOST.md)
+- [PHP Sessions](docs/PHP_SESSIONS.md)
 - Installation:
   - [Kustomize External Database and HTTPS Ingress Example](docs/example-configs/kustomize/external-db-and-https-ingress/README.md)
   - [Compose Traefik Reverse Proxy Example](docs/example-configs/compose/traefik-reverse-proxy/README.md)

docs/PHP_SESSIONS.md

@@ -0,0 +1,81 @@
+# PHP Session Configuration
+
+This document explains how to configure PHP sessions in the docker-mailserver project, including both Redis and file-based session storage options.
+
+## Overview
+
+The web service supports configurable PHP session storage through environment variables. By default, sessions are stored in Redis, but you can easily switch to file-based storage or other session handlers.
+
+## Environment Variables
+
+| Variable                   | Default                                                    | Description          |
+| -------------------------- | ---------------------------------------------------------- | -------------------- |
+| `PHP_SESSION_SAVE_HANDLER` | `redis`                                                    | Session save handler |
+| `PHP_SESSION_SAVE_PATH`    | `tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}` | Session save path    |
+
+## Session Storage Options
+
+### Redis Sessions (Default)
+
+Redis is the default session storage mechanism, providing fast, scalable session management.
+
+**Configuration:**
+
+```bash
+PHP_SESSION_SAVE_HANDLER=redis
+PHP_SESSION_SAVE_PATH=tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}
+```
+
+### File-Based Sessions
+
+Store sessions as files on the local filesystem.
+
+**Configuration:**
+
+```bash
+PHP_SESSION_SAVE_HANDLER=files
+PHP_SESSION_SAVE_PATH=/tmp/sessions
+```
+
+## Implementation Examples
+
+### Docker Compose Configuration
+
+**Redis Sessions (Default):**
+
+```yaml
+services:
+  web:
+    environment:
+      - PHP_SESSION_SAVE_HANDLER=redis
+      - PHP_SESSION_SAVE_PATH=tcp://redis:6379?auth=${REDIS_PASSWORD}
+    depends_on:
+      - redis
+```
+
+**File-Based Sessions:**
+
+```yaml
+services:
+  web:
+    environment:
+      - PHP_SESSION_SAVE_HANDLER=files
+      - PHP_SESSION_SAVE_PATH=/tmp/sessions
+    volumes:
+      - session_data:/tmp/sessions
+```
+
+## PHP Configuration
+
+The session configuration is applied through the PHP configuration file at:
+`target/web/rootfs/usr/local/etc/php/conf.d/zzz_app.ini`
+
+```ini
+session.save_handler = ${PHP_SESSION_SAVE_HANDLER}
+session.save_path = "${PHP_SESSION_SAVE_PATH:-tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}}"
+```
+
+This configuration:
+
+- Uses the `PHP_SESSION_SAVE_HANDLER` environment variable
+- Falls back to Redis configuration if `PHP_SESSION_SAVE_PATH` is not set

target/web/Dockerfile

@@ -49,7 +49,8 @@ ENV MYSQL_HOST=db \
     WAITSTART_TIMEOUT=1m \
     ADMIN_VER=${ADMIN_VER} \
     DATABASE_URL="mysql://%env(MYSQL_USER)%:%env(MYSQL_PASSWORD)%@%env(MYSQL_HOST)%:%env(MYSQL_PORT)%/%env(MYSQL_DATABASE)%?serverVersion=8.4" \
-    COMPOSER_ALLOW_SUPERUSER=1
+    COMPOSER_ALLOW_SUPERUSER=1 \
+    PHP_SESSION_SAVE_HANDLER=redis
 
 ARG RC_PLUGINS=""
 COPY --from=docker.io/roundcube/roundcubemail:1.6.11-fpm@sha256:c7ca21fc0d617e1b866f112250a2b9638a0e237d5a0b345c7b74258ef8fba704 /usr/src/roundcubemail/ /var/www/html/webmail/

target/web/rootfs/usr/local/etc/php/conf.d/zzz_app.ini

@@ -11,5 +11,5 @@ display_errors = Off
 upload_max_filesize = 50M
 post_max_size = 50M
 
-session.save_handler = redis
-session.save_path = "tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}"
+session.save_handler = ${PHP_SESSION_SAVE_HANDLER}
+session.save_path = "${PHP_SESSION_SAVE_PATH:-tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}}"