From 7f9d62f40966625472c83a5939bd3dc177246ead Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Fri, 1 Mar 2024 15:35:26 +0100 Subject: [PATCH] Update documentation about syncing the configuration with the database --- docs/setup/general.md | 16 ++-------------- docs/setup/sso.md | 3 ++- docs/usage/configuration.md | 5 +++-- 3 files changed, 7 insertions(+), 17 deletions(-) diff --git a/docs/setup/general.md b/docs/setup/general.md index 0c2364afc..05b9a40c9 100644 --- a/docs/setup/general.md +++ b/docs/setup/general.md @@ -62,27 +62,15 @@ Many [tools in text editors](https://json-schema.org/implementations.html#editor Some sections of the configuration file need to be synced every time the configuration file is updated. This includes the [`clients`](../usage/configuration.md#clients) and [`upstream_oauth`](../usage/configuration.md#upstream-oauth) sections. -Once the database is initialized, the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command can be used to sync the configuration file with the database: +The configuration is synced by default on startup, and can be manually synced using the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command. -```sh -mas-cli config sync -``` - -By default, this will only add new clients and upstream OAuth providers, and will not remove entries that were removed from the configuration file. +By default, this will only add new clients and upstream OAuth providers and update existing ones, but will not remove entries that were removed from the configuration file. To do so, use the `--prune` option: ```sh mas-cli config sync --prune ``` -Before synchronizing the configuration file, it is *recommended* to do it in with the `--dry-run` option to see what will be changed, without committing the changes to the database: - -```sh -mas-cli config sync --dry-run -# with the --prune option -mas-cli config sync --dry-run --prune -``` - ## Next step After generating the configuration file, the next step is to [set up a database](./database.md). diff --git a/docs/setup/sso.md b/docs/setup/sso.md index 5cfa8844a..56346ff6a 100644 --- a/docs/setup/sso.md +++ b/docs/setup/sso.md @@ -11,7 +11,8 @@ A deployment which requires SAML or LDAP-based authentication should use a servi ## General configuration Configuration of upstream providers is done in the `upstream_oauth2` section of the configuration file, which has a `providers` list. -This section needs to be synced with the database every time it changes, using the [`mas-cli config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command. +Additions and changes to this sections are synced with the database on startup. +Removals need to be applied using the [`mas-cli config sync --prune`](../usage/cli/config.md#config-sync---prune---dry-run) command. **An exhaustive list of all the parameters is available in the [configuration file reference](../usage/configuration.md#upstream_oauth2).** diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index a02193782..7d1694d75 100644 --- a/docs/usage/configuration.md +++ b/docs/usage/configuration.md @@ -157,7 +157,7 @@ clients: client_auth_method: none ``` -**Note:** this list is not used at runtime, and any modification of this list must be synced to the database using the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command. +**Note:** any additions or modification in this list are synced with the database on server startup. Removed entries are only removed with the [`config sync --prune`](../usage/cli/config.md#config-sync---prune---dry-run) command. ## `secrets` @@ -367,7 +367,8 @@ email: ### `upstream_oauth2` Settings related to upstream OAuth 2.0/OIDC providers. -This section must be synced to the database using the [`config sync`](../usage/cli/config.md#config-sync---prune---dry-run) command. +Additions and modifications within this section are synced with the database on server startup. +Removed entries are only removed with the [`config sync --prune`](../usage/cli/config.md#config-sync---prune---dry-run) command. #### `upstream_oauth2.providers`