diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/administration/CLI_tasks/config.md | 22 | ||||
| -rw-r--r-- | docs/development/API/admin_api.md | 217 | ||||
| -rw-r--r-- | docs/development/config_versioning.md | 40 |
3 files changed, 187 insertions, 92 deletions
diff --git a/docs/administration/CLI_tasks/config.md b/docs/administration/CLI_tasks/config.md index fc9f3cbd5..4657f2111 100644 --- a/docs/administration/CLI_tasks/config.md +++ b/docs/administration/CLI_tasks/config.md @@ -2,7 +2,7 @@ {! backend/administration/CLI_tasks/general_cli_task_info.include !} -## Transfer config from file to DB. +## Transfer config from file to DB !!! note You need to add the following to your config before executing this command: @@ -154,4 +154,24 @@ This forcibly removes all saved values in the database. ```sh mix pleroma.config [--force] reset + +## Rollback config version + +!!! note + You need to add the following to your config before executing this command: + + ```elixir + config :pleroma, configurable_from_database: true + ``` + +Rollback will restore last backup by default. If you want to restore older version use `-s` parameter. + +=== "OTP" + ```sh + ./bin/pleroma_ctl config rollback [-s 2] + ``` + +=== "From Source" + ```sh + mix pleroma.config rollback [-s 2] ``` diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index 8f855d251..05c07571d 100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -282,7 +282,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false) - Response: - On failure: `Not found` - - On success: JSON, where: + - On success: JSON, where: - `total`: total count of the statuses for the user - `activities`: list of the statuses for the user @@ -339,7 +339,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret Params: none Response: -* On success: JSON array of relays +- On success: JSON array of relays ```json [ @@ -354,11 +354,11 @@ Response: Params: -* `relay_url` +- `relay_url` Response: -* On success: relay json object +- On success: relay json object ```json {"actor": "https://example.com/relay", "followed_back": true} @@ -374,7 +374,7 @@ Response: Response: -* On success: URL of the unfollowed relay +- On success: URL of the unfollowed relay ```json {"https://example.com/relay"} @@ -472,7 +472,6 @@ Response: ### Get a password reset token for a given nickname - - Params: none - Response: @@ -493,7 +492,7 @@ Response: ## PUT `/api/v1/pleroma/admin/users/disable_mfa` -### Disable mfa for user's account. +### Disable MFA for user's account - Params: - `nickname` @@ -551,30 +550,30 @@ Response: ### Change the user's email, password, display and settings-related fields -* Params: - * `email` - * `password` - * `name` - * `bio` - * `avatar` - * `locked` - * `no_rich_text` - * `default_scope` - * `banner` - * `hide_follows` - * `hide_followers` - * `hide_followers_count` - * `hide_follows_count` - * `hide_favorites` - * `allow_following_move` - * `background` - * `show_role` - * `skip_thread_containment` - * `fields` - * `is_discoverable` - * `actor_type` - -* Responses: +- Params: + - `email` + - `password` + - `name` + - `bio` + - `avatar` + - `locked` + - `no_rich_text` + - `default_scope` + - `banner` + - `hide_follows` + - `hide_followers` + - `hide_followers_count` + - `hide_follows_count` + - `hide_favorites` + - `allow_following_move` + - `background` + - `show_role` + - `skip_thread_containment` + - `fields` + - `is_discoverable` + - `actor_type` + +- Responses: Status: 200 @@ -896,7 +895,7 @@ Status: 404 - Params: none - Response: - On failure: - - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` + - 400 Bad Request `"You must enable configurable_from_database in your config file."` ```json {} @@ -909,6 +908,7 @@ Status: 404 - Params: none - Response: - `need_reboot` - boolean + ```json { "need_reboot": false @@ -917,7 +917,7 @@ Status: 404 ## `GET /api/v1/pleroma/admin/config` -### Get list of merged default settings with saved in database. +### Get list of merged default settings with saved in database *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.* @@ -927,7 +927,7 @@ Status: 404 - `only_db`: true (*optional*, get only saved in database settings) - Response: - On failure: - - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` + - 400 Bad Request `"You must enable configurable_from_database in your config file."` ```json { @@ -952,34 +952,34 @@ Status: 404 Some modifications are necessary to save the config settings correctly: -- strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules; -``` -"Pleroma.Upload" -> Pleroma.Upload -"Oban" -> Oban -``` -- strings starting with `:` will be converted to atoms; -``` -":pleroma" -> :pleroma -``` -- objects with `tuple` key and array value will be converted to tuples; -``` -{"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []} -``` -- arrays with *tuple objects* will be converted to keywords; -``` -[{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"] -``` +- strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules + - `"Pleroma.Upload"` -> `Pleroma.Upload` + - `"Oban"` -> `Oban` +- strings starting with `:` will be converted to atoms + - `":pleroma"` -> `:pleroma` +- objects with `tuple` key and array value will be converted to tuples + - `{"tuple": ["string", "Pleroma.Upload", []]}` -> `{"string", Pleroma.Upload, []}` +- arrays with *tuple objects* will be converted to keywords + - `[{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}]` -> `[key1: "value", key2: "value"]` -Most of the settings will be applied in `runtime`, this means that you don't need to restart the instance. But some settings are applied in `compile time` and require a reboot of the instance, such as: -- all settings inside these keys: - - `:hackney_pools` - - `:connections_pool` - - `:pools` +Most of the settings will be applied in `runtime`, this means that changes will be applied immediately. But some settings are applied on `startup time` and will take effect after restart of the pleroma parts, such as: + +- all settings inside these keys - `:chat` + - `Oban` + - `:rate_limit` + - `:streamer` + - `:pools` + - `:connections_pool` + - `:hackney_pools` + - `:gopher` + - `:eshhd` + - `:ex_aws` - partially settings inside these keys: - `:seconds_valid` in `Pleroma.Captcha` - `:proxy_remote` in `Pleroma.Upload` - `:upload_limit` in `:instance` + - `:enabled` in `:fed_sockets` - Params: - `configs` - array of config objects @@ -990,34 +990,33 @@ Most of the settings will be applied in `runtime`, this means that you don't nee - `delete` - true (*optional*, if setting must be deleted) - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored) -*When a value have several nested settings, you can delete only some nested settings by passing a parameter `subkeys`, without deleting all settings by key.* -``` -[subkey: val1, subkey2: val2, subkey3: val3] \\ initial value -{"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion -[subkey2: val2] \\ value after deletion -``` +#### Partial deletion -*Most of the settings can be partially updated through merge old values with new values, except settings value of which is list or is not keyword.* +Keys inside value can be partially deleted by passing `subkeys` parameter. If after partial deleting an empty list remains, then the entire setting will be deleted. + +Example: -Example of setting without keyword in value: ```elixir -config :tesla, :adapter, Tesla.Adapter.Hackney +# initial value +[subkey: :val1, subkey2: :val2, subkey3: :val3] +``` + +```json +// config object for deletion +{"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} ``` -List of settings which support only full update by key: ```elixir -@full_key_update [ - {:pleroma, :ecto_repos}, - {:quack, :meta}, - {:mime, :types}, - {:cors_plug, [:max_age, :methods, :expose, :headers]}, - {:auto_linker, :opts}, - {:swarm, :node_blacklist}, - {:logger, :backends} - ] +# value after deletion +[subkey2: :val2] ``` -List of settings which support only full update by subkey: +#### Partial update + +Most settings can be partially updated: new values will be merged with existing ones. + +The following settings are exceptions and should be fully updated: + ```elixir @full_subkey_update [ {:pleroma, :assets, :mascots}, @@ -1028,22 +1027,24 @@ List of settings which support only full update by subkey: ] ``` -*Settings without explicit key must be sended in separate config object params.* +#### Settings without explicit keys + +Settings without explicit key must be sended in one config object with null value as key. + ```elixir config :quack, level: :debug, - meta: [:all], - ... + meta: [:all] ``` + ```json { "configs": [ - {"group": ":quack", "key": ":level", "value": ":debug"}, - {"group": ":quack", "key": ":meta", "value": [":all"]}, - ... + {"group": ":quack", "key": null, "value": [{"tuple": [":level", ":debug"]}, {"tuple": [":meta", ":all"]}]} ] } ``` + - Request: ```json @@ -1077,7 +1078,8 @@ config :quack, - Response: - On failure: - - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` + - 400 Bad Request `"You must enable configurable_from_database in your config file."` + ```json { "configs": [ @@ -1091,9 +1093,10 @@ config :quack, } ``` -## ` GET /api/v1/pleroma/admin/config/descriptions` +## `GET /api/v1/pleroma/admin/config/descriptions` + +### Get JSON with config descriptions -### Get JSON with config descriptions. Loads json generated from `config/descriptions.exs`. - Params: none @@ -1124,6 +1127,37 @@ Loads json generated from `config/descriptions.exs`. }] ``` +## `GET /api/v1/pleroma/admin/config/versions/rollback/:id` + +### Rollback config changes for a given version + +- Params: + - `id` - version id for rollback +- Response: + - On success: `204`, empty response + - On failure: + - 400 Bad Request `"You must enable configurable_from_database in your config file."` or endpoint error + - 404 Not found + +## `GET /api/v1/pleroma/admin/config/versions` + +### Get list of config versions + +- Params: none +- Response: + +```json +{ + "versions": [ + { + "id": 1, + "current": true, + "inserted_at": "2020-04-21T15:11:46.000Z" + } + ] +} +``` + ## `GET /api/v1/pleroma/admin/moderation_log` ### Get moderation log @@ -1230,7 +1264,6 @@ Loads json generated from `config/descriptions.exs`. } ``` - ## `POST /api/v1/pleroma/admin/oauth_app` ### Create OAuth App @@ -1257,6 +1290,7 @@ Loads json generated from `config/descriptions.exs`. ``` - On failure: + ```json { "redirect_uris": "can't be blank", @@ -1269,11 +1303,11 @@ Loads json generated from `config/descriptions.exs`. ### Update OAuth App - Params: - - *optional* `name` - - *optional* `redirect_uris` - - *optional* `scopes` - - *optional* `website` - - *optional* `trusted` + - *optional* `name` + - *optional* `redirect_uris` + - *optional* `scopes` + - *optional* `website` + - *optional* `trusted` - Response: @@ -1491,6 +1525,7 @@ Returns the content of the document ``` ## `PATCH /api/v1/pleroma/admin/instance_document/:document_name` + - Params: - `file` (the file to be uploaded, using multipart form data.) diff --git a/docs/development/config_versioning.md b/docs/development/config_versioning.md new file mode 100644 index 000000000..fd5a44910 --- /dev/null +++ b/docs/development/config_versioning.md @@ -0,0 +1,40 @@ +# Config versioning + +Database configuration supports simple versioning. Every change (list of changes or only one change) through adminFE creates new version with backup from config table. It is possible to do rollback on N steps (1 by default). Rollback will recreate `config` table from backup. + +**IMPORTANT** Destructive operations with `Pleroma.ConfigDB` and `Pleroma.Config.Version` must be processed through `Pleroma.Config.Versioning` module for correct versioning work, especially migration changes. + +Example: + +* new config setting is added directly using `Pleroma.ConfigDB` module +* user is doing rollback and setting is lost + +## Creating new version + +Creating new version is done with `Pleroma.Config.Versioning.new_version/1`, which accepts list of changes. Changes can include adding/updating/deleting operations in `config` table at the same time. + +Process of creating new version: + +* saving config changes in `config` table +* saving new version with current configs + * `backup` - keyword with all configs from `config` table (binary) + * `current` - flag, which marks current version (boolean) + +## Version rollback + +Version control also supports a simple N steps back mechanism. + +Rollback process: + +* cleaning `config` table +* splitting `backup` field into separate settings and inserting them into `config` table +* removing subsequent versions + +## Config migrations + +Sometimes it becomes necessary to make changes to the configuration, which can be stored in the user's database. Config versioning makes this process more complicated, as we also must update this setting in versions backups. + +Versioning module contains two functions for migrations: + +* `Pleroma.Config.Versioning.migrate_namespace/2` - for simple renaming, e.g. group or key of the setting must be renamed. +* `Pleroma.Config.Versioning.migrate_configs_and_versions/2` - abstract function for more complex migrations. Accepts two functions, the first one to make changes with configs, another to make changes with version backups. |