Expose config.php settings to operators #154

New Issue

Open

opened 2026-10-22 08:51:43 +00:00 by amras · 6 comments

amras commented 2026-10-22 08:51:43 +00:00

Owner

Copy Link

Copy Source

Background

Nextcloud handles a lot of its configuration through the config/config.php file. This file is unfortunately editable both by administrators and by the application.

Normally, config files ought to be specified in the configs: and templated, so their features can be placed in the .env and exposed to the operator. However, this would make it read-only for the application, so this recipe uses the unconventional approach of placing config.php in the nextconfig volume.

When an operator wants to modify the options provided by config.php, they have to deploy the app, then modify the file in the config volume. (e.g. using abra app cmd <domain> app set_system_config <config> <value> ) This has substantial limitations, described below.

Motivation

1. I want to be able to change (imortant aspects of) the config without a running deployment. In particular, when preparing a config for a new instance or when using higher-layer tools like alakazam.
2. Config-in-volume runs counter to the conventions in most other recipes, where (nearly) all the config is stored and documented in .env. Nextcloud is already relatively complex to set up, so if we can keep the config similar to other deployments it would ease the burden on operators.
3. The principle "keep documentation close to what it documents" is difficult to keep in this case, since the operator effectively has to cross reference the readme, abra.sh's commands, their own running config.php, and nextcloud's own documentation. If we keep the variables in the .env, we can document them through names or through #comments.
4. Because the config.php is not readily visible, contains a mix of relevant and irrelevant options, and is set with a mix of runtime and config commands, it becomes harder to notice issues in the config.

Proposal

config/config.php can be extended by files named config/*.config.php, as described here.These files can (probably) be read-only, making them a good candidate for templated configs:. They also take precedence over application-generated config.php options.

I suggest we create a operator.config.php.tmpl, then move a couple of relevant options into .env.sample, like skeleton_directory and default_app.

### Background Nextcloud handles a lot of its configuration through the `config/config.php` file. This file is unfortunately editable both by administrators and by the application. Normally, config files ought to be specified in the `configs:` and templated, so their features can be placed in the `.env` and exposed to the operator. However, this would make it read-only for the application, so this recipe uses the unconventional approach of placing `config.php` in the `nextconfig` volume. When an operator wants to modify the options provided by `config.php`, they have to deploy the app, then modify the file in the config volume. (e.g. using `abra app cmd <domain> app set_system_config <config> <value>` ) This has substantial limitations, described below. ### Motivation 1. I want to be able to change (imortant aspects of) the config without a running deployment. In particular, when preparing a config for a new instance or when using higher-layer tools like alakazam. 2. Config-in-volume runs counter to the conventions in most other recipes, where (nearly) all the config is stored and documented in .env. Nextcloud is already relatively complex to set up, so if we can keep the config similar to other deployments it would ease the burden on operators. 3. The principle "keep documentation close to what it documents" is difficult to keep in this case, since the operator effectively has to cross reference the readme, abra.sh's commands, their own running config.php, and nextcloud's own documentation. If we keep the variables in the .env, we can document them through names or through #comments. 4. Because the config.php is not readily visible, contains a mix of relevant and irrelevant options, and is set with a mix of runtime and config commands, it becomes harder to notice issues in the config. ### Proposal `config/config.php` can be extended by files named `config/*.config.php`, as described [here](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#loading).These files can (probably) be read-only, making them a good candidate for templated `configs:`. They also take precedence over application-generated `config.php` options. I suggest we create a `operator.config.php.tmpl`, then move a couple of relevant options into `.env.sample`, like `skeleton_directory` and `default_app`.

amras added the enhancementquestion labels 2026-10-22 08:51:43 +00:00

ineiti commented 2026-10-22 11:39:05 +00:00

Owner

Copy Link

Copy Source

1. what are the pros/cons?
2. would you like to work on that?

1. what are the pros/cons? 2. would you like to work on that?

dannygroenewegen commented 2026-10-25 18:28:04 +00:00

Owner

Copy Link

Copy Source

Settings in config.php can be set with occ config:system:set <key> --value=<value>. And the recipe already has two wrapper functions for that in abra.sh: set_system_config and run_occ. You can set defaultapp with abra app cmd <domain> app set_system_config defaultapp "dashboard"

And for setting the skeleton_directory to an empty value, there is: abra app cmd <domain> app disable_skeletondirectory or this one for setting any value: abra app cmd <domain> app set_system_config skeletondirectory '/some/path'

Settings in `config.php` can be set with `occ config:system:set <key> --value=<value>`. And the recipe already has two wrapper functions for that in `abra.sh`: `set_system_config` and `run_occ`. You can set defaultapp with `abra app cmd <domain> app set_system_config defaultapp "dashboard"` And for setting the `skeleton_directory` to an empty value, there is: `abra app cmd <domain> app disable_skeletondirectory` or this one for setting any value: `abra app cmd <domain> app set_system_config skeletondirectory '/some/path'`

ineiti commented 2026-10-25 19:52:45 +00:00

Owner

Copy Link

Copy Source

Shall we close this then?

Shall we close this then?

dannygroenewegen added the documentation label 2026-10-26 07:51:55 +00:00

dannygroenewegen commented 2026-10-26 07:57:08 +00:00

Owner

Copy Link

Copy Source

Shall we close this then?

@amras Would abra app cmd <domain> app set_system_config <config> <value> resolve it for you?

We can keep this open to clarify this in the readme. We could link to Nextcloud Configuration Parameters for all parameters that can be configured with set_system_config

> Shall we close this then? @amras Would `abra app cmd <domain> app set_system_config <config> <value>` resolve it for you? We can keep this open to clarify this in the readme. We could link to [Nextcloud Configuration Parameters](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#default-parameters) for all parameters that can be configured with `set_system_config`

amras commented 2026-10-26 08:37:50 +00:00

Author

Owner

Copy Link

Copy Source

2. would you like to work on that?

I would like to work on this, since I believe it'll save me headaches for future clients. Unfortunately I can't promise I'll do so in a timely manner because of other priorities - and I believe others would benefit if this was changed in the meantime. So if anyone else has the motivation to poke at the problem I encourage it.

Would abra app cmd <domain> app set_system_config <config> <value> resolve it for you

I agree we should keep this option, because it gives operators flexibility to change undocumented parameters. However, I don't think this is a sufficient solution.

1. I want to be able to change (imortant aspects of) the config without a running deployment. In particular, when preparing a config for a new instance or when using higher-layer tools like alakazam.
2. Config-in-volume runs counter to the conventions in most other recipes, where (nearly) all the config is stored and documented in .env. Nextcloud is already relatively complex to set up, so if we can keep the config similar to other deployments it would ease the burden on operators.
3. The principle "keep documentation close to what it documents" is difficult to keep in this case, since the operator effectively has to cross reference the readme, abra.sh's commands, their own running config.php, and nextcloud's own documentation. If we keep the variables in the .env, we can document them through names or through #comments.
4. Because the config.php is not readily visible, contains a mix of relevant and irrelevant options, and is set with a mix of runtime and config commands, it becomes harder to notice issues in the config.

> 2. would you like to work on that? I would like to work on this, since I believe it'll save me headaches for future clients. Unfortunately I can't promise I'll do so in a timely manner because of other priorities - and I believe others would benefit if this was changed in the meantime. So if anyone else has the motivation to poke at the problem I encourage it. > Would `abra app cmd <domain> app set_system_config <config> <value>` resolve it for you I agree we should keep this option, because it gives operators flexibility to change undocumented parameters. However, I don't think this is a sufficient solution. 1. I want to be able to change (imortant aspects of) the config without a running deployment. In particular, when preparing a config for a new instance or when using higher-layer tools like alakazam. 2. Config-in-volume runs counter to the conventions in most other recipes, where (nearly) all the config is stored and documented in .env. Nextcloud is already relatively complex to set up, so if we can keep the config similar to other deployments it would ease the burden on operators. 3. The principle "keep documentation close to what it documents" is difficult to keep in this case, since the operator effectively has to cross reference the readme, abra.sh's commands, their own running config.php, and nextcloud's own documentation. If we keep the variables in the .env, we can document them through names or through #comments. 4. Because the config.php is not readily visible, contains a mix of relevant and irrelevant options, and is set with a mix of runtime and config commands, it becomes harder to notice issues in the config.

ineiti commented 2026-10-26 12:08:10 +00:00

Owner

Copy Link

Copy Source

Thanks @amras for this explanation - now I see the light :) I'm also in favour of having a config file which can be prepared beforehand, is readable, represents the current configuration, can be put in version control, ...

So let's keep the issue open then. Can I ask you to update the description of the issue with a resume of your 1. - 4.? I like having the main issue comment being the "latest state of the discussions". This makes it so that people don't need to go through all discussions to know what's the latest state of the issue.

Thanks @amras for this explanation - now I see the light :) I'm also in favour of having a config file which can be prepared beforehand, is readable, represents the current configuration, can be put in version control, ... So let's keep the issue open then. Can I ask you to update the description of the issue with a resume of your 1. - 4.? I like having the main issue comment being the "latest state of the discussions". This makes it so that people don't need to go through all discussions to know what's the latest state of the issue.

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

main

whiteboard-docs

version_35

renovate/docker.elastic.co-elasticsearch-elasticsearch-8.x

renovate/docker.elastic.co-elasticsearch-elasticsearch-9.x

kc_stable

mitigations_php

after-pr-143-cherry-pick

pr-143-review

pr-125-v2

pr-125

renovate/mariadb-13.x

trusted-domains

renovate/pgautoupgrade-pgautoupgrade-18.x

pr-15.2.0+34.0.2-fpm

pr-14.2.0+33-fpm

fix-pgautoupgrade-max-connections

upload-limit

feature/imaginary

local

authentik_sso

healthchecks

occ_cmds

15.1.1+34.0.6-fpm

15.1.0+34.0.5-fpm

15.0.1+34.0.5-fpm

15.0.0+34.0.5-fpm

14.6.0+33-fpm

14.5.1+33.0.9-fpm

14.5.0+33.0.9-fpm

14.4.0+33.0.9-fpm

14.3.0+33.0.9-fpm

14.2.0+33.0.9-fpm

14.1.2+33.0.9-fpm

14.1.1+33.0.8-fpm

14.1.0+33.0.7-fpm

14.0.1+33.0.7-fpm

14.0.0+33.0.7-fpm

13.2.0+32-fpm

13.1.5+32.0.13-fpm

13.1.4+32.0.13-fpm

13.1.3+32.0.13-fpm

13.1.2+32.0.13-fpm

13.1.1+32.0.12-fpm

13.1.0+32.0.11-fpm

13.0.1+32.0.3-fpm

13.0.0+32.0.3-fpm

12.1.0+31.0.6-fpm

12.0.1+31.0.6-fpm

12.0.0+31.0.6-fpm

11.4.0+30.0.6-fpm

11.4.0+30.0.10-fpm

11.3.0+30.0.6-fpm

11.2.0+30.0.6-fpm

11.1.0+30.0.6-fpm

11.0.1+30.0.4-fpm

11.0.0+30.0.4-fpm

10.0.0+30.0.4-fpm

9.2.0+29.0.8-fpm

6.0.11+28.0.10-fpm

6.0.10+28.0.10-fpm

6.0.9+28.0.10-fpm

9.1.2+29.0.5-fpm

6.0.8+28.0.5-fpm

6.0.7+28.0.5-fpm

9.1.0+29.0.5-fpm

9.0.0+29.0.5-fpm

6.0.6+28.0.5-fpm

8.0.1+29.0.3-fpm

8.0.0+29.0.1-fpm

7.0.3+29.0.1-fpm

6.0.5+28.0.5-fpm

7.0.2+29.0.1-fpm

7.0.1+29.0.1-fpm

7.0.0+29.0.0-fpm

6.0.4+28.0.5-fpm

6.0.3+28.0.5-fpm

6.0.2+28.0.5-fpm

5.0.3+27.0.1-fpm

6.0.1+28.0.2-fpm

6.0.0+28.0.1-fpm

5.2.0+27.1.5-fpm

5.1.1+27.1.5-fpm

5.1.0+27.1.3-fpm

5.0.2+27.0.1-fpm

5.0.1+27.0.1-fpm

5.0.0+27.0.0-fpm

4.0.7+26.0.2-fpm

4.0.6+26.0.2-fpm

4.0.5+26.0.2-fpm

4.0.4+26.0.2-fpm

4.0.3+26.0.2-fpm

4.0.2+26.0.2-fpm

4.0.1+26.0.1-fpm

4.0.0+26.0.1-fpm

3.3.2+25.0.6-fpm

3.3.1+25.0.5-fpm

3.3.0+25.0.5-fpm

3.2.0+25.0.4-fpm

3.1.2+25.0.4-fpm

3.1.1+25.0.1-fpm

3.1.0+25.0.1-fpm

3.0.1+25.0.1-fpm

3.0.0+25.0.1-fpm

2.1.4+24.0.6-fpm

2.1.3+24.0.5-fpm

2.1.2+24.0.3-fpm

2.1.1+24.0.2-fpm

2.1.0+24.0.0-fpm

2.0.0+23.0.4-fpm

1.0.0+23.0.1-fpm

Labels

Clear labels

bug

Something is not working

documentation

For issues that are calling out documentation gap

duplicate

This issue or pull request already exists

enhancement

New feature

help wanted

Need some help

invalid

Something is wrong

question

More information is needed

wontfix

This won't be fixed

No labels documentation enhancement question

Milestone

No items

No Milestone

Assignees

Clear assignees

3wordchant aadil (Aadil Ayub) abra-bot (Abra Bot) ammaratef45 amras (Sarma) BornDeleuze (Born Deleuze) Brooke carla cas (Cassowary) coopcloud dannygroenewegen (Danny Groenewegen) decentral1se (d1) devydave fauno (fauno) hex (Josh Dukes) ineiti (Linus Gasser) javielico (Javielico) jjsfunhouse kawaiipunk (KawaiiPunk) knoflook moosemower moritz notplants oxaliq (sorrel) p4u1 (p4u1) renovate-bot (Comrade Renovate Bot) simon stevensting (stevensting) trav (Trav Fryer) yksflip

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: coop-cloud/nextcloud#154