X-Git-Url: https://git.squeep.com/?a=blobdiff_plain;f=docs%2Fconfiguration%2Fcheatsheet.md;h=9af8ee95ad660ceb60caf35956bfef7cfbbe925f;hb=94ba5a780212920a1d4b303c3523f66ca0147a67;hp=ac55a0b32319fae9c722a73c5bdef31ae83fa9d5;hpb=3eddd9caa61a2ac431eb57cd4c835db608702a7d;p=akkoma diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index ac55a0b32..9af8ee95a 100644 --- 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. -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. @@ -136,7 +142,8 @@ config :pleroma, :mrf_user_allowlist, ``` #### :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 @@ -149,10 +156,6 @@ config :pleroma, :mrf_user_allowlist, * `sign_object_fetches`: Sign object fetches with HTTP signatures * `authorized_fetch_mode`: Require HTTP signatures for AP fetches -### :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 - ## Pleroma.ScheduledActivity * `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`) @@ -246,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 +* `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 @@ -343,6 +380,7 @@ Means that: 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. @@ -369,8 +407,7 @@ Available caches: * `proxy_url`: an upstream proxy to fetch posts and/or media with, (default: `nil`) * `send_user_agent`: should we include a user agent with HTTP requests? (default: `true`) * `user_agent`: what user agent should we use? (default: `:default`), must be string or `:default` -* `adapter`: array of hackney options - +* `adapter`: array of adapter options ### :hackney_pools @@ -389,6 +426,42 @@ For each pool, the options are: * `timeout` - retention duration for connections +### :connections_pool + +*For `gun` adapter* + +Advanced settings for connections pool. Pool with opened connections. These connections can be reused in worker pools. + +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. +* `: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 + +*For `gun` adapter* + +Advanced settings for workers pools. + +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. +* `:media` for rich media, media proxy +* `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`) +* `:default` for other requests + +For each pool, the options are: + +* `:size` - how much workers the pool can hold +* `:timeout` - timeout while `gun` will wait for response +* `:max_overflow` - additional workers if pool is under load + + ## Captcha ### Pleroma.Captcha @@ -580,24 +653,6 @@ config :pleroma, :workers, * `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. @@ -868,7 +923,51 @@ config :auto_linker, * `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. + +## :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`.