persist config directories

README.md

@@ -41,6 +41,7 @@ ___
   * [Previews generator sidecar](#previews-generator-sidecar)
   * [Nextcloud News Updater](#nextcloud-news-updater)
   * [Email server](#email-server)
+  * [Custom configuration](#custom-configuration)
   * [Redis cache](#redis-cache)
   * [Running in a subdir](#running-in-a-subdir)
 * [Contributing](#contributing)
@@ -167,6 +168,7 @@ linux/s390x
 ## Volumes
 
 * `/data`: Contains config, data folders, installed user apps (not core ones), session, themes, tmp folders
+* `/data/config/*.config.php`: Additional Nextcloud configuration files loaded from the persistent config directory
 
 > [!WARNING]
 > Note that the volume should be owned by the user/group with the specified
@@ -293,20 +295,42 @@ declared in our [`compose.yml`](examples/compose/compose.yml):
 
 ![Email server config](.github/email-server-config.png)
 
+### Custom configuration
+
+Nextcloud can load additional
+[`*.config.php` files](https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files)
+from its config directory.
+Use `/data/config/<name>.config.php` for custom settings instead of editing
+`/data/config/config.php`, which is managed by Nextcloud and this image.
+
+These files are merged with `config.php` and take precedence over values defined
+there. You can inspect the merged configuration with:
+
+```bash
+docker compose exec nextcloud occ config:list system --private
+```
+
+Do not store backup files ending with `.config.php` in `/data/config`, because
+Nextcloud will load them as active configuration.
+
 ### Redis cache
 
 Redis is recommended, alongside APCu to make Nextcloud faster. If you want to
 enable Redis, deploy a redis container (see [compose file](examples/compose/compose.yml))
-and add this to your `config.php`:
+and create `/data/config/redis.config.php`:
 
-```
+```php
+<?php
+
+$CONFIG = [
     'memcache.local' => '\OC\Memcache\APCu',
     'memcache.distributed' => '\OC\Memcache\Redis',
     'memcache.locking' => '\OC\Memcache\Redis',
-    'redis' => array(
+    'redis' => [
         'host' => 'redis',
         'port' => 6379,
-    ),
+    ],
+];
 ```
 
 ### Running in a subdir

rootfs/etc/cont-init.d/03-config.sh

@@ -28,6 +28,26 @@ file_env() {
   unset "$fileVar"
 }
 
+persist_web_dir() {
+  local web_path="$1"
+  local data_path="$2"
+  local entry_name
+  local web_entry
+
+  if [ -d "$web_path" ] && [ ! -L "$web_path" ]; then
+    for web_entry in "$web_path"/* "$web_path"/.[!.]*; do
+      [ -e "$web_entry" ] || continue
+      entry_name="$(basename "$web_entry")"
+      [ -e "${data_path}/${entry_name}" ] || cp -a "$web_entry" "$data_path/"
+    done
+    mv "$web_path" "${web_path}.dist"
+  fi
+  if [ -e "$web_path" ] && [ ! -L "$web_path" ]; then
+    echo >&2 "ERROR: Failed to replace ${web_path} with ${data_path} symlink"
+    exit 1
+  fi
+}
+
 TZ=${TZ:-UTC}
 MEMORY_LIMIT=${MEMORY_LIMIT:-512M}
 UPLOAD_MAX_SIZE=${UPLOAD_MAX_SIZE:-512M}
@@ -102,21 +122,24 @@ fi
 
 # Init Nextcloud
 echo "Initializing Nextcloud files/folders..."
-mkdir -p /data/config /data/data /data/session /data/tmp /data/userapps
-if [ ! -d /data/themes ]; then
-  if [ -d /var/www/themes ]; then
-    mv -f /var/www/themes /data/
-    chown -R nextcloud:nextcloud /data/themes
-  fi
-  mkdir -p /data/themes
-elif [ -d /var/www/themes ]; then
-  rm -rf /var/www/themes
-fi
+mkdir -p /data/config /data/data /data/session /data/themes /data/tmp /data/userapps
+
+persist_web_dir /var/www/config /data/config
+persist_web_dir /var/www/themes /data/themes
+persist_web_dir /var/www/userapps /data/userapps
+
+# FIXME: Drop this migration cleanup after existing volumes have been recreated
+# with ln -sfn and no longer contain legacy nested self-links.
+[ "$(readlink /data/config/config 2>/dev/null)" = "/data/config" ] && rm -f /data/config/config
+[ "$(readlink /data/themes/themes 2>/dev/null)" = "/data/themes" ] && rm -f /data/themes/themes
+[ "$(readlink /data/userapps/userapps 2>/dev/null)" = "/data/userapps" ] && rm -f /data/userapps/userapps
+
+ln -sfn /data/config /var/www/config
+ln -sfn /data/themes /var/www/themes
+ln -sfn /data/userapps /var/www/userapps
 chown nextcloud:nextcloud /data/config /data/data /data/session /data/tmp /data/userapps /data/themes
-ln -sf /data/config/config.php /var/www/config/config.php &>/dev/null
-ln -sf /data/themes /var/www/themes &>/dev/null
-ln -sf /data/userapps /var/www/userapps &>/dev/null
 
+# Check DB
 file_env 'DB_USER'
 file_env 'DB_PASSWORD'
 
@@ -224,15 +247,19 @@ fi
 unset DB_USER
 unset DB_PASSWORD
 
+subdir_config="/var/www/config/docker-subdir.config.php"
 # https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/config_sample_php_parameters.html#proxy-configurations
 if [ -n "$SUBDIR" ]; then
-  cat >/var/www/config/subdir.config.php <<EOL
+  cat >"${subdir_config}" <<EOL
 <?php
+// Generated by docker-nextcloud from the SUBDIR environment variable.
 \$CONFIG = array(
     'overwritewebroot' => '${SUBDIR}',
 );
 EOL
+else
+  rm -f "${subdir_config}"
 fi
 
-# config directory must be writable
-chown -R nextcloud:nextcloud /var/www/config
+# config, themes and user apps directories must be writable
+chown -R nextcloud:nextcloud /data/config /data/themes /data/userapps