We currently inject auto config variable a variety of ways.

Some:

• are install time only
• can be used all the time
• only are used if other variables are specified with them
• make there way into the main config.php if they're provided at install time
• will never appear in the main config.php
• are injected in more than one way depending on other factors
• etc

These creates confusion in a variety of ways:

• "Why aren't my configuration changes taking effect?"
• "Which variables can only be specified at installation time?"
• "Why are the variables apparently taking effect, but not appearing in my config.php"?
• "Why does my long-time installed container's variable handling not match the docs?"
• "How can I see my real running configuration if it's not visible in config.php"?
• "Why doesn't this work in rootless environment?"
• "Why does this variable only work when injected as a secret?"
• "Why are my SMTP settings made via the web UI being overridden?"
• "Why do my variable values sometimes show up in the main config.php and other times they don't?"
• "Why are my Docker Compose and config.php values completely out-of-sync?"
• etc

Here I'll attempt to inventory and analyze each variable so that we can then:

• improve our documentation
• determine where there are potential opportunities to enhance things (to make things easier to understand, more useful, etc.)
• determine where there is potential technical debt (e.g. differences that inconsistent or no longer necessary)

TODO:

• Start documenting them (fix(readme): Auto configuration variable details/constraints #2228)
• Add column/note/something regarding some secrets needing different permissions (i.e. those injected via autoconfig.php will be accessed as www-data not root/root equivalent)
• Finish documenting them (fix(readme): Auto configuration variable details/constraints #2228)

Background:

• Some of the variables are handled in particular ways out of necessity, such based on how the standard Nextcloud Server installer works.
• Some of these are essentially for historical reasons, driven by a mixture of "just how it was implemented initially", backwards compatibility needs, and/or mere technical debt that hasn't been addressed.
• Then we also have the NC_* support native to Server itself (see Document how to use NC_* environment variables with Nextcloud Server via the image #2226), but not documented upstream (but something we tend to suggest when people request new variables to adjust Server parameters get added here) nor documented for the image formally either officially

We likely can't fix all of them, but we can document them clearly. And, in the process, possibly also make some implementation adjustments where it make sense.

The variations (this basically needs to be translated into a big table or something):

• Installation time only (first startup only) via image's entrypoint.sh
• Installation time only (first startup only) via Server's autoconfig.php
• Can be specified anytime and will override config.php
• Will appear within config.php
• Will appear only within occ config:list system
• Require other variables to be present in order to be used
• Requires root/can't be used in rootless environment
• Can be specified as a Docker secret / from a file
• Handled via container-specific extra config files (config/*.config.php)
  • Note: must be manually updated in older installations
  • Once Warn if config folder misses original image configs or files differ #2120 is merged, there will be a built-check for outdated installations (watch for warnings at startup)

• Injected via { PHP's, Apache's } built-in environment variable substitution

Installation time only:

• NEXTCLOUD_ADMIN_USER
  • requires NEXTCLOUD_ADMIN_PASSWORD
• NEXTCLOUD_ADMIN_PASSWORD
  • requires NEXTCLOUD_ADMIN_USER
• NEXTCLOUD_TRUSTED_DOMAINS
  • requires NEXTCLOUD_ADMIN_USER and NEXTCLOUD_ADMIN_PASSWORD
• SQLITE_*
  • Installation time only (first startup only)
  • via image's entrypoint.sh (or) via Server's autoconfig.php
    • Injected via entrypoint.sh if used with NEXTCLOUD_ADMIN_* (provided to Server's installer)
    • Injected via Server's built-in autoconfig.php support if used without NEXTCLOUD_ADMIN_* (pulled in by Server's installer)
• MYSQL_*
  • Installation time only (first startup only)
  • via image's entrypoint.sh (or) via Server's autoconfig.php
    • Injected via entrypoint.sh if used with NEXTCLOUD_ADMIN_* (provided to Server's installer)
    • Injected via Server's built-in autoconfig.php support if used without NEXTCLOUD_ADMIN_* (pulled in by Server's installer)
• POSTGRES_*
  • Installation time only (first startup only)
  • via image's entrypoint.sh (or) via Server's autoconfig.php
    • Injected via entrypoint.sh if used with NEXTCLOUD_ADMIN_* (provided to Server's installer)
    • Injected via Server's built-in autoconfig.php support if used without NEXTCLOUD_ADMIN_* (pulled in by Server's installer)
• NEXTCLOUD_DATA_DIR
  • Installation time only (first startup only)
  • via image's entrypoint.sh (or) via Server's autoconfig.php
    • Injected via entrypoint.sh if used with NEXTCLOUD_ADMIN_* (provided to Server's installer)
    • Injected via Server's built-in autoconfig.php support if used without NEXTCLOUD_ADMIN_* (pulled in by Server's installer)

Anytime

• NEXTCLOUD_UPDATE
• NEXTCLOUD_INIT_HTACCESS
• REDIS_*
  • Requires root/can't be used in rootless environment
• SMTP_* and MAIL_*
• OBJECTSTORE_*
• PHP_*
  • Injected via PHP's ini files (with built-in environment variable substitution)
• APACHE_BODY_LIMIT
  • Injected via Apache's own config files (with built-in environment variable substitution)
• APACHE_DISABLE_REWRITE_IP
  • via entrypoint.sh
• TRUSTED_PROXIES and OVERWRITE*
  • will override config/config.php
  • handled via config/reverse.proxy.php