Merge branch 'exposed-background-image' into 'develop'

[akkoma] / docs / configuration / cheatsheet.md

diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md
index 1c67eca356b941b272e172ef8addd8cc82f0e747..9af8ee95ad660ceb60caf35956bfef7cfbbe925f 100644 (file)
--- a/docs/configuration/cheatsheet.md
+++ b/docs/configuration/cheatsheet.md
@@ -2,9 +2,15 @@
 
 This is a cheat sheet for Pleroma configuration file, any setting possible to configure should be listed here.
 
 
 This is a cheat sheet for Pleroma configuration file, any setting possible to configure should be listed here.
 

-Pleroma configuration works by first importing the base config (`config/config.exs` on source installs, compiled-in on OTP releases), then overriding it by the environment config (`config/$MIX_ENV.exs` on source installs, N/A to OTP releases) and then overriding it by user config (`config/$MIX_ENV.secret.exs` on source installs, typically `/etc/pleroma/config.exs` on OTP releases).
+For OTP installations the configuration is typically stored in `/etc/pleroma/config.exs`.

 
 

-You shouldn't edit the base config directly to avoid breakages and merge conflicts, but it can be used as a reference if you don't understand how an option is supposed to be formatted, the latest version of it can be viewed [here](https://git.pleroma.social/pleroma/pleroma/blob/develop/config/config.exs).
+For from source installations Pleroma configuration works by first importing the base config `config/config.exs`, then overriding it by the environment config `config/$MIX_ENV.exs` and then overriding it by user config `config/$MIX_ENV.secret.exs`. In from source installations you should always make the changes to the user config and NEVER to the base config to avoid breakages and merge conflicts. So for production you change/add configuration to `config/prod.secret.exs`.
+
+To add configuration to your config file, you can copy it from the base config. The latest version of it can be viewed [here](https://git.pleroma.social/pleroma/pleroma/blob/develop/config/config.exs). You can also use this file if you don't know how an option is supposed to be formatted.
+
+## :chat
+
+* `enabled` - Enables the backend chat. Defaults to `true`.

 
 ## :instance
 * `name`: The instance’s name.
 
 ## :instance
 * `name`: The instance’s name.


@@ -136,21 +142,19 @@ config :pleroma, :mrf_user_allowlist,
 ```
 
 #### :mrf_object_age
 ```
 
 #### :mrf_object_age

-* `threshold`: Required age (in seconds) of a post before actions are taken.
+* `threshold`: Required time offset (in seconds) compared to your server clock of an incoming post before actions are taken.
+  e.g., A value of 900 results in any post with a timestamp older than 15 minutes will be acted upon.

 * `actions`: A list of actions to apply to the post:
   * `:delist` removes the post from public timelines
   * `:strip_followers` removes followers from the ActivityPub recipient list, ensuring they won't be delivered to home timelines
   * `:reject` rejects the message entirely
 
 ### :activitypub
 * `actions`: A list of actions to apply to the post:
   * `:delist` removes the post from public timelines
   * `:strip_followers` removes followers from the ActivityPub recipient list, ensuring they won't be delivered to home timelines
   * `:reject` rejects the message entirely
 
 ### :activitypub

-* ``unfollow_blocked``: Whether blocks result in people getting unfollowed
-* ``outgoing_blocks``: Whether to federate blocks to other instances
-* ``deny_follow_blocked``: Whether to disallow following an account that has blocked the user in question
-* ``sign_object_fetches``: Sign object fetches with HTTP signatures
-
-### :fetch_initial_posts
-* `enabled`: if enabled, when a new user is federated with, fetch some of their latest posts
-* `pages`: the amount of pages to fetch
+* `unfollow_blocked`: Whether blocks result in people getting unfollowed
+* `outgoing_blocks`: Whether to federate blocks to other instances
+* `deny_follow_blocked`: Whether to disallow following an account that has blocked the user in question
+* `sign_object_fetches`: Sign object fetches with HTTP signatures
+* `authorized_fetch_mode`: Require HTTP signatures for AP fetches

 
 ## Pleroma.ScheduledActivity
 
 
 ## Pleroma.ScheduledActivity
 


@@ -245,6 +249,40 @@ This section describe PWA manifest instance-specific values. Currently this opti
 * `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host/CDN fronts.
 * `proxy_opts`: All options defined in `Pleroma.ReverseProxy` documentation, defaults to `[max_body_length: (25*1_048_576)]`.
 * `whitelist`: List of domains to bypass the mediaproxy
 * `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host/CDN fronts.
 * `proxy_opts`: All options defined in `Pleroma.ReverseProxy` documentation, defaults to `[max_body_length: (25*1_048_576)]`.
 * `whitelist`: List of domains to bypass the mediaproxy

+* `invalidation`: options for remove media from cache after delete object:
+    * `enabled`: Enables purge cache
+    * `provider`: Which one of  the [purge cache strategy](#purge-cache-strategy) to use.
+
+### Purge cache strategy
+
+#### Pleroma.Web.MediaProxy.Invalidation.Script
+
+This strategy allow perform external bash script to purge cache.
+Urls of attachments pass to script as arguments.
+
+* `script_path`: path to external script.
+
+Example:
+```elixir
+config :pleroma, Pleroma.Web.MediaProxy.Invalidation.Script,
+  script_path: "./installation/nginx-cache-purge.example"
+```
+
+#### Pleroma.Web.MediaProxy.Invalidation.Http
+
+This strategy allow perform custom http request to purge cache.
+
+* `method`: http method. default is `purge`
+* `headers`: http headers. default is empty
+* `options`: request options. default is empty
+
+Example:
+```elixir
+config :pleroma, Pleroma.Web.MediaProxy.Invalidation.Http,
+  method: :purge,
+  headers: [],
+  options: []
+```

 
 ## Link previews
 
 
 ## Link previews
 


@@ -342,6 +380,7 @@ Means that:
 Supported rate limiters:
 
 * `:search` - Account/Status search.
 Supported rate limiters:
 
 * `:search` - Account/Status search.

+* `:timeline` - Timeline requests (each timeline has it's own limiter).

 * `:app_account_creation` - Account registration from the API.
 * `:relations_actions` - Following/Unfollowing in general.
 * `:relation_id_action` - Following/Unfollowing for a specific user.
 * `:app_account_creation` - Account registration from the API.
 * `:relations_actions` - Following/Unfollowing in general.
 * `:relation_id_action` - Following/Unfollowing for a specific user.


@@ -393,10 +432,13 @@ For each pool, the options are:
 
 Advanced settings for connections pool. Pool with opened connections. These connections can be reused in worker pools.
 
 
 Advanced settings for connections pool. Pool with opened connections. These connections can be reused in worker pools.
 

-* `:receive_connection_timeout` - timeout to receive connection from pool. Default: 250ms.
+For big instances it's recommended to increase `config :pleroma, :connections_pool, max_connections: 500` up to 500-1000.
+It will increase memory usage, but federation would work faster.
+
+* `:checkin_timeout` - timeout to checkin connection from pool. Default: 250ms.

 * `:max_connections` - maximum number of connections in the pool. Default: 250 connections.
 * `:max_connections` - maximum number of connections in the pool. Default: 250 connections.

-* `:retry` - number of retries, while `gun` will try to reconnect if connections goes down. Default: 5.
-* `:retry_timeout` - timeout while `gun` will try to reconnect. Default: 100ms.
+* `:retry` - number of retries, while `gun` will try to reconnect if connection goes down. Default: 1.
+* `:retry_timeout` - time between retries when `gun` will try to reconnect in milliseconds. Default: 1000ms.

 * `:await_up_timeout` - timeout while `gun` will wait until connection is up. Default: 5000ms.
 
 ### :pools
 * `:await_up_timeout` - timeout while `gun` will wait until connection is up. Default: 5000ms.
 
 ### :pools


@@ -405,7 +447,7 @@ Advanced settings for connections pool. Pool with opened connections. These conn
 
 Advanced settings for workers pools.
 
 
 Advanced settings for workers pools.
 

-There's four pools used:
+There are four pools used:

 
 * `:federation` for the federation jobs.
   You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs.
 
 * `:federation` for the federation jobs.
   You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs.


@@ -533,6 +575,10 @@ Email notifications settings.
 - `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo.
 - `:styling` - a map with color settings for email templates.
 
 - `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo.
 - `:styling` - a map with color settings for email templates.
 

+### Pleroma.Emails.NewUsersDigestEmail
+
+- `:enabled` - a boolean, enables new users admin digest email when `true`. Defaults to `false`.
+

 ## Background jobs
 
 ### Oban
 ## Background jobs
 
 ### Oban


@@ -607,24 +653,6 @@ config :pleroma, :workers,
 * `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]`
 * deprecated options: `max_jobs`, `initial_timeout`
 
 * `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]`
 * deprecated options: `max_jobs`, `initial_timeout`
 

-### Pleroma.Scheduler
-
-Configuration for [Quantum](https://github.com/quantum-elixir/quantum-core) jobs scheduler.
-
-See [Quantum readme](https://github.com/quantum-elixir/quantum-core#usage) for the list of supported options.
-
-Example:
-
-```elixir
-config :pleroma, Pleroma.Scheduler,
-  global: true,
-  overlap: true,
-  timezone: :utc,
-  jobs: [{"0 */6 * * * *", {Pleroma.Web.Websub, :refresh_subscriptions, []}}]
-```
-
-The above example defines a single job which invokes `Pleroma.Web.Websub.refresh_subscriptions()` every 6 hours ("0 */6 * * * *", [crontab format](https://en.wikipedia.org/wiki/Cron)).
-

 ## :web_push_encryption, :vapid_details
 
 Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it.
 ## :web_push_encryption, :vapid_details
 
 Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it.


@@ -895,7 +923,51 @@ config :auto_linker,
 
 * `runtime_dir`: A path to custom Elixir modules (such as MRF policies).
 
 
 * `runtime_dir`: A path to custom Elixir modules (such as MRF policies).
 

-

 ## :configurable_from_database
 
 Boolean, enables/disables in-database configuration. Read [Transfering the config to/from the database](../administration/CLI_tasks/config.md) for more information.
 ## :configurable_from_database
 
 Boolean, enables/disables in-database configuration. Read [Transfering the config to/from the database](../administration/CLI_tasks/config.md) for more information.

+
+## :database_config_whitelist
+
+List of valid configuration sections which are allowed to be configured from the
+database. Settings stored in the database before the whitelist is configured are
+still applied, so it is suggested to only use the whitelist on instances that
+have not migrated the config to the database.
+
+Example:
+```elixir
+config :pleroma, :database_config_whitelist, [
+  {:pleroma, :instance},
+  {:pleroma, Pleroma.Web.Metadata},
+  {:auto_linker}
+]
+```
+
+### Multi-factor authentication -  :two_factor_authentication
+* `totp` - a list containing TOTP configuration
+  - `digits` - Determines the length of a one-time pass-code in characters. Defaults to 6 characters.
+  - `period` - a period for which the TOTP code will be valid in seconds. Defaults to 30 seconds.
+* `backup_codes` - a list containing backup codes configuration
+  - `number` - number of backup codes to generate.
+  - `length` - backup code length. Defaults to 16 characters.
+
+## Restrict entities access for unauthenticated users
+
+### :restrict_unauthenticated
+
+Restrict access for unauthenticated users to timelines (public and federate), user profiles and statuses.
+
+* `timelines` - public and federated timelines
+  * `local` - public timeline
+  * `federated`
+* `profiles` - user profiles
+  * `local`
+  * `remote`
+* `activities` - statuses
+  * `local`
+  * `remote`
+
+
+## Pleroma.Web.ApiSpec.CastAndValidate
+
+* `:strict` a boolean, enables strict input validation (useful in development, not recommended in production). Defaults to `false`.