Merge branch 'develop' of https://git.pleroma.social/pleroma/pleroma into develop
[akkoma] / docs / configuration / cheatsheet.md
1 # Configuration Cheat Sheet
2
3 This is a cheat sheet for Pleroma configuration file, any setting possible to configure should be listed here.
4
5 For OTP installations the configuration is typically stored in `/etc/pleroma/config.exs`.
6
7 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`.
8
9 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.
10
11 ## :chat
12
13 * `enabled` - Enables the backend chat. Defaults to `true`.
14
15 ## :instance
16 * `name`: The instance’s name.
17 * `email`: Email used to reach an Administrator/Moderator of the instance.
18 * `notify_email`: Email used for notifications.
19 * `description`: The instance’s description, can be seen in nodeinfo and ``/api/v1/instance``.
20 * `limit`: Posts character limit (CW/Subject included in the counter).
21 * `chat_limit`: Character limit of the instance chat messages.
22 * `remote_limit`: Hard character limit beyond which remote posts will be dropped.
23 * `upload_limit`: File size limit of uploads (except for avatar, background, banner).
24 * `avatar_upload_limit`: File size limit of user’s profile avatars.
25 * `background_upload_limit`: File size limit of user’s profile backgrounds.
26 * `banner_upload_limit`: File size limit of user’s profile banners.
27 * `poll_limits`: A map with poll limits for **local** polls.
28 * `max_options`: Maximum number of options.
29 * `max_option_chars`: Maximum number of characters per option.
30 * `min_expiration`: Minimum expiration time (in seconds).
31 * `max_expiration`: Maximum expiration time (in seconds).
32 * `registrations_open`: Enable registrations for anyone, invitations can be enabled when false.
33 * `invites_enabled`: Enable user invitations for admins (depends on `registrations_open: false`).
34 * `account_activation_required`: Require users to confirm their emails before signing in.
35 * `federating`: Enable federation with other instances.
36 * `federation_incoming_replies_max_depth`: Max. depth of reply-to activities fetching on incoming federation, to prevent out-of-memory situations while fetching very long threads. If set to `nil`, threads of any depth will be fetched. Lower this value if you experience out-of-memory crashes.
37 * `federation_reachability_timeout_days`: Timeout (in days) of each external federation target being unreachable prior to pausing federating to it.
38 * `allow_relay`: Enable Pleroma’s Relay, which makes it possible to follow a whole instance.
39 * `rewrite_policy`: Message Rewrite Policy, either one or a list. Here are the ones available by default:
40 * `Pleroma.Web.ActivityPub.MRF.NoOpPolicy`: Doesn’t modify activities (default).
41 * `Pleroma.Web.ActivityPub.MRF.DropPolicy`: Drops all activities. It generally doesn’t makes sense to use in production.
42 * `Pleroma.Web.ActivityPub.MRF.SimplePolicy`: Restrict the visibility of activities from certain instances (See [`:mrf_simple`](#mrf_simple)).
43 * `Pleroma.Web.ActivityPub.MRF.TagPolicy`: Applies policies to individual users based on tags, which can be set using pleroma-fe/admin-fe/any other app that supports Pleroma Admin API. For example it allows marking posts from individual users nsfw (sensitive).
44 * `Pleroma.Web.ActivityPub.MRF.SubchainPolicy`: Selectively runs other MRF policies when messages match (See [`:mrf_subchain`](#mrf_subchain)).
45 * `Pleroma.Web.ActivityPub.MRF.RejectNonPublic`: Drops posts with non-public visibility settings (See [`:mrf_rejectnonpublic`](#mrf_rejectnonpublic)).
46 * `Pleroma.Web.ActivityPub.MRF.EnsureRePrepended`: Rewrites posts to ensure that replies to posts with subjects do not have an identical subject and instead begin with re:.
47 * `Pleroma.Web.ActivityPub.MRF.AntiLinkSpamPolicy`: Rejects posts from likely spambots by rejecting posts from new users that contain links.
48 * `Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy`: Crawls attachments using their MediaProxy URLs so that the MediaProxy cache is primed.
49 * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (See [`:mrf_mention`](#mrf_mention)).
50 * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (See [`:mrf_vocabulary`](#mrf_vocabulary)).
51 * `Pleroma.Web.ActivityPub.MRF.ObjectAgePolicy`: Rejects or delists posts based on their age when received. (See [`:mrf_object_age`](#mrf_object_age)).
52 * `Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy`: Adds expiration to all local Create activities (see [`:mrf_activity_expiration`](#mrf_activity_expiration)).
53 * `public`: Makes the client API in authenticated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network.
54 * `quarantined_instances`: List of ActivityPub instances where private(DMs, followers-only) activities will not be send.
55 * `managed_config`: Whenether the config for pleroma-fe is configured in [:frontend_configurations](#frontend_configurations) or in ``static/config.json``.
56 * `allowed_post_formats`: MIME-type list of formats allowed to be posted (transformed into HTML).
57 * `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo).
58 * `mrf_transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value.
59 * `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with
60 older software for theses nicknames.
61 * `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature.
62 * `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow.
63 * `no_attachment_links`: Set to true to disable automatically adding attachment link text to statuses.
64 * `welcome_message`: A message that will be send to a newly registered users as a direct message.
65 * `welcome_user_nickname`: The nickname of the local user that sends the welcome message.
66 * `max_report_comment_size`: The maximum size of the report comment (Default: `1000`).
67 * `safe_dm_mentions`: If set to true, only mentions at the beginning of a post will be used to address people in direct messages. This is to prevent accidental mentioning of people when talking about them (e.g. "@friend hey i really don't like @enemy"). Default: `false`.
68 * `healthcheck`: If set to true, system data will be shown on ``/api/pleroma/healthcheck``.
69 * `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database.
70 * `user_bio_length`: A user bio maximum length (default: `5000`).
71 * `user_name_length`: A user name maximum length (default: `100`).
72 * `skip_thread_containment`: Skip filter out broken threads. The default is `false`.
73 * `limit_to_local_content`: Limit unauthenticated users to search for local statutes and users only. Possible values: `:unauthenticated`, `:all` and `false`. The default is `:unauthenticated`.
74 * `max_account_fields`: The maximum number of custom fields in the user profile (default: `10`).
75 * `max_remote_account_fields`: The maximum number of custom fields in the remote user profile (default: `20`).
76 * `account_field_name_length`: An account field name maximum length (default: `512`).
77 * `account_field_value_length`: An account field value maximum length (default: `2048`).
78 * `external_user_synchronization`: Enabling following/followers counters synchronization for external users.
79 * `cleanup_attachments`: Remove attachments along with statuses. Does not affect duplicate files and attachments without status. Enabling this will increase load to database when deleting statuses on larger instances.
80
81 ## Federation
82 ### MRF policies
83
84 !!! note
85 Configuring MRF policies is not enough for them to take effect. You have to enable them by specifying their module in `rewrite_policy` under [:instance](#instance) section.
86
87 #### :mrf_simple
88 * `media_removal`: List of instances to remove media from.
89 * `media_nsfw`: List of instances to put media as NSFW(sensitive) from.
90 * `federated_timeline_removal`: List of instances to remove from Federated (aka The Whole Known Network) Timeline.
91 * `reject`: List of instances to reject any activities from.
92 * `accept`: List of instances to accept any activities from.
93 * `report_removal`: List of instances to reject reports from.
94 * `avatar_removal`: List of instances to strip avatars from.
95 * `banner_removal`: List of instances to strip banners from.
96
97 #### :mrf_subchain
98 This policy processes messages through an alternate pipeline when a given message matches certain criteria.
99 All criteria are configured as a map of regular expressions to lists of policy modules.
100
101 * `match_actor`: Matches a series of regular expressions against the actor field.
102
103 Example:
104
105 ```elixir
106 config :pleroma, :mrf_subchain,
107 match_actor: %{
108 ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy]
109 }
110 ```
111
112 #### :mrf_rejectnonpublic
113 * `allow_followersonly`: whether to allow followers-only posts.
114 * `allow_direct`: whether to allow direct messages.
115
116 #### :mrf_hellthread
117 * `delist_threshold`: Number of mentioned users after which the message gets delisted (the message can still be seen, but it will not show up in public timelines and mentioned users won't get notifications about it). Set to 0 to disable.
118 * `reject_threshold`: Number of mentioned users after which the messaged gets rejected. Set to 0 to disable.
119
120 #### :mrf_keyword
121 * `reject`: A list of patterns which result in message being rejected, each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html).
122 * `federated_timeline_removal`: A list of patterns which result in message being removed from federated timelines (a.k.a unlisted), each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html).
123 * `replace`: A list of tuples containing `{pattern, replacement}`, `pattern` can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html).
124
125 #### :mrf_mention
126 * `actors`: A list of actors, for which to drop any posts mentioning.
127
128 #### :mrf_vocabulary
129 * `accept`: A list of ActivityStreams terms to accept. If empty, all supported messages are accepted.
130 * `reject`: A list of ActivityStreams terms to reject. If empty, no messages are rejected.
131
132 #### :mrf_user_allowlist
133
134 The keys in this section are the domain names that the policy should apply to.
135 Each key should be assigned a list of users that should be allowed through by
136 their ActivityPub ID.
137
138 An example:
139
140 ```elixir
141 config :pleroma, :mrf_user_allowlist, %{
142 "example.org" => ["https://example.org/users/admin"]
143 }
144 ```
145
146 #### :mrf_object_age
147 * `threshold`: Required time offset (in seconds) compared to your server clock of an incoming post before actions are taken.
148 e.g., A value of 900 results in any post with a timestamp older than 15 minutes will be acted upon.
149 * `actions`: A list of actions to apply to the post:
150 * `:delist` removes the post from public timelines
151 * `:strip_followers` removes followers from the ActivityPub recipient list, ensuring they won't be delivered to home timelines
152 * `:reject` rejects the message entirely
153
154 #### mrf_steal_emoji
155 * `hosts`: List of hosts to steal emojis from
156 * `rejected_shortcodes`: Regex-list of shortcodes to reject
157 * `size_limit`: File size limit (in bytes), checked before an emoji is saved to the disk
158
159 #### :mrf_activity_expiration
160
161 * `days`: Default global expiration time for all local Create activities (in days)
162
163 ### :activitypub
164 * `unfollow_blocked`: Whether blocks result in people getting unfollowed
165 * `outgoing_blocks`: Whether to federate blocks to other instances
166 * `deny_follow_blocked`: Whether to disallow following an account that has blocked the user in question
167 * `sign_object_fetches`: Sign object fetches with HTTP signatures
168 * `authorized_fetch_mode`: Require HTTP signatures for AP fetches
169
170 ## Pleroma.ScheduledActivity
171
172 * `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`)
173 * `total_user_limit`: the number of scheduled activities a user is allowed to create in total (Default: `300`)
174 * `enabled`: whether scheduled activities are sent to the job queue to be executed
175
176 ## Pleroma.ActivityExpiration
177
178 * `enabled`: whether expired activities will be sent to the job queue to be deleted
179
180 ## Frontends
181
182 ### :frontend_configurations
183
184 This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. You can find the documentation for `pleroma_fe` configuration into [Pleroma-FE configuration and customization for instance administrators](/frontend/CONFIGURATION/#options).
185
186 Frontends can access these settings at `/api/pleroma/frontend_configurations`
187
188 To add your own configuration for PleromaFE, use it like this:
189
190 ```elixir
191 config :pleroma, :frontend_configurations,
192 pleroma_fe: %{
193 theme: "pleroma-dark",
194 # ... see /priv/static/static/config.json for the available keys.
195 },
196 masto_fe: %{
197 showInstanceSpecificPanel: true
198 }
199 ```
200
201 These settings **need to be complete**, they will override the defaults.
202
203 ### :static_fe
204
205 Render profiles and posts using server-generated HTML that is viewable without using JavaScript.
206
207 Available options:
208
209 * `enabled` - Enables the rendering of static HTML. Defaults to `false`.
210
211 ### :assets
212
213 This section configures assets to be used with various frontends. Currently the only option
214 relates to mascots on the mastodon frontend
215
216 * `mascots`: KeywordList of mascots, each element __MUST__ contain both a `url` and a
217 `mime_type` key.
218 * `default_mascot`: An element from `mascots` - This will be used as the default mascot
219 on MastoFE (default: `:pleroma_fox_tan`).
220
221 ### :manifest
222
223 This section describe PWA manifest instance-specific values. Currently this option relate only for MastoFE.
224
225 * `icons`: Describe the icons of the app, this a list of maps describing icons in the same way as the
226 [spec](https://www.w3.org/TR/appmanifest/#imageresource-and-its-members) describes it.
227
228 Example:
229
230 ```elixir
231 config :pleroma, :manifest,
232 icons: [
233 %{
234 src: "/static/logo.png"
235 },
236 %{
237 src: "/static/icon.png",
238 type: "image/png"
239 },
240 %{
241 src: "/static/icon.ico",
242 sizes: "72x72 96x96 128x128 256x256"
243 }
244 ]
245 ```
246
247 * `theme_color`: Describe the theme color of the app. (Example: `"#282c37"`, `"rebeccapurple"`).
248 * `background_color`: Describe the background color of the app. (Example: `"#191b22"`, `"aliceblue"`).
249
250 ## :emoji
251 * `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]`
252 * `pack_extensions`: A list of file extensions for emojis, when no emoji.txt for a pack is present. Example `[".png", ".gif"]`
253 * `groups`: Emojis are ordered in groups (tags). This is an array of key-value pairs where the key is the groupname and the value the location or array of locations. `*` can be used as a wildcard. Example `[Custom: ["/emoji/*.png", "/emoji/custom/*.png"]]`
254 * `default_manifest`: Location of the JSON-manifest. This manifest contains information about the emoji-packs you can download. Currently only one manifest can be added (no arrays).
255 * `shared_pack_cache_seconds_per_file`: When an emoji pack is shared, the archive is created and cached in
256 memory for this amount of seconds multiplied by the number of files.
257
258 ## :media_proxy
259 * `enabled`: Enables proxying of remote media to the instance’s proxy
260 * `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.
261 * `proxy_opts`: All options defined in `Pleroma.ReverseProxy` documentation, defaults to `[max_body_length: (25*1_048_576)]`.
262 * `whitelist`: List of domains to bypass the mediaproxy
263 * `invalidation`: options for remove media from cache after delete object:
264 * `enabled`: Enables purge cache
265 * `provider`: Which one of the [purge cache strategy](#purge-cache-strategy) to use.
266
267 ### Purge cache strategy
268
269 #### Pleroma.Web.MediaProxy.Invalidation.Script
270
271 This strategy allow perform external bash script to purge cache.
272 Urls of attachments pass to script as arguments.
273
274 * `script_path`: path to external script.
275
276 Example:
277 ```elixir
278 config :pleroma, Pleroma.Web.MediaProxy.Invalidation.Script,
279 script_path: "./installation/nginx-cache-purge.example"
280 ```
281
282 #### Pleroma.Web.MediaProxy.Invalidation.Http
283
284 This strategy allow perform custom http request to purge cache.
285
286 * `method`: http method. default is `purge`
287 * `headers`: http headers. default is empty
288 * `options`: request options. default is empty
289
290 Example:
291 ```elixir
292 config :pleroma, Pleroma.Web.MediaProxy.Invalidation.Http,
293 method: :purge,
294 headers: [],
295 options: []
296 ```
297
298 ## Link previews
299
300 ### Pleroma.Web.Metadata (provider)
301 * `providers`: a list of metadata providers to enable. Providers available:
302 * `Pleroma.Web.Metadata.Providers.OpenGraph`
303 * `Pleroma.Web.Metadata.Providers.TwitterCard`
304 * `Pleroma.Web.Metadata.Providers.RelMe` - add links from user bio with rel=me into the `<header>` as `<link rel=me>`.
305 * `Pleroma.Web.Metadata.Providers.Feed` - add a link to a user's Atom feed into the `<header>` as `<link rel=alternate>`.
306 * `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews.
307
308 ### :rich_media (consumer)
309 * `enabled`: if enabled the instance will parse metadata from attached links to generate link previews.
310 * `ignore_hosts`: list of hosts which will be ignored by the metadata parser. For example `["accounts.google.com", "xss.website"]`, defaults to `[]`.
311 * `ignore_tld`: list TLDs (top-level domains) which will ignore for parse metadata. default is ["local", "localdomain", "lan"].
312 * `parsers`: list of Rich Media parsers.
313
314 ## HTTP server
315
316 ### Pleroma.Web.Endpoint
317
318 !!! note
319 `Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here.
320
321 * `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here. For deployment using docker, you need to set this to `[ip: {0,0,0,0}, port: 4000]` to make pleroma accessible from other containers (such as your nginx server).
322 - `ip` - a tuple consisting of 4 integers
323 - `port`
324 * `url` - a list containing the configuration for generating urls, accepts
325 - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`)
326 - `scheme` - e.g `http`, `https`
327 - `port`
328 - `path`
329 * `extra_cookie_attrs` - a list of `Key=Value` strings to be added as non-standard cookie attributes. Defaults to `["SameSite=Lax"]`. See the [SameSite article](https://www.owasp.org/index.php/SameSite) on OWASP for more info.
330
331 Example:
332 ```elixir
333 config :pleroma, Pleroma.Web.Endpoint,
334 url: [host: "example.com", port: 2020, scheme: "https"],
335 http: [
336 port: 8080,
337 ip: {127, 0, 0, 1}
338 ]
339 ```
340
341 This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020`
342
343 ### :http_security
344 * ``enabled``: Whether the managed content security policy is enabled.
345 * ``sts``: Whether to additionally send a `Strict-Transport-Security` header.
346 * ``sts_max_age``: The maximum age for the `Strict-Transport-Security` header if sent.
347 * ``ct_max_age``: The maximum age for the `Expect-CT` header if sent.
348 * ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"`.
349 * ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header.
350
351 ### Pleroma.Plugs.RemoteIp
352
353 !!! warning
354 If your instance is not behind at least one reverse proxy, you should not enable this plug.
355
356 `Pleroma.Plugs.RemoteIp` is a shim to call [`RemoteIp`](https://git.pleroma.social/pleroma/remote_ip) but with runtime configuration.
357
358 Available options:
359
360 * `enabled` - Enable/disable the plug. Defaults to `false`.
361 * `headers` - A list of strings naming the `req_headers` to use when deriving the `remote_ip`. Order does not matter. Defaults to `["x-forwarded-for"]`.
362 * `proxies` - A list of strings in [CIDR](https://en.wikipedia.org/wiki/CIDR) notation specifying the IPs of known proxies. Defaults to `[]`.
363 * `reserved` - Defaults to [localhost](https://en.wikipedia.org/wiki/Localhost) and [private network](https://en.wikipedia.org/wiki/Private_network).
364
365
366 ### :rate_limit
367
368 !!! note
369 If your instance is behind a reverse proxy ensure [`Pleroma.Plugs.RemoteIp`](#pleroma-plugs-remoteip) is enabled (it is enabled by default).
370
371 A keyword list of rate limiters where a key is a limiter name and value is the limiter configuration. The basic configuration is a tuple where:
372
373 * The first element: `scale` (Integer). The time scale in milliseconds.
374 * The second element: `limit` (Integer). How many requests to limit in the time scale provided.
375
376 It is also possible to have different limits for unauthenticated and authenticated users: the keyword value must be a list of two tuples where the first one is a config for unauthenticated users and the second one is for authenticated.
377
378 For example:
379
380 ```elixir
381 config :pleroma, :rate_limit,
382 authentication: {60_000, 15},
383 search: [{1000, 10}, {1000, 30}]
384 ```
385
386 Means that:
387
388 1. In 60 seconds, 15 authentication attempts can be performed from the same IP address.
389 2. In 1 second, 10 search requests can be performed from the same IP adress by unauthenticated users, while authenticated users can perform 30 search requests per second.
390
391 Supported rate limiters:
392
393 * `:search` - Account/Status search.
394 * `:timeline` - Timeline requests (each timeline has it's own limiter).
395 * `:app_account_creation` - Account registration from the API.
396 * `:relations_actions` - Following/Unfollowing in general.
397 * `:relation_id_action` - Following/Unfollowing for a specific user.
398 * `:statuses_actions` - Status actions such as: (un)repeating, (un)favouriting, creating, deleting.
399 * `:status_id_action` - (un)Repeating/(un)Favouriting a particular status.
400 * `:authentication` - Authentication actions, i.e getting an OAuth token.
401 * `:password_reset` - Requesting password reset emails.
402 * `:account_confirmation_resend` - Requesting resending account confirmation emails.
403 * `:ap_routes` - Requesting statuses via ActivityPub.
404
405 ### :web_cache_ttl
406
407 The expiration time for the web responses cache. Values should be in milliseconds or `nil` to disable expiration.
408
409 Available caches:
410
411 * `:activity_pub` - activity pub routes (except question activities). Defaults to `nil` (no expiration).
412 * `:activity_pub_question` - activity pub routes (question activities). Defaults to `30_000` (30 seconds).
413
414 ## HTTP client
415
416 ### :http
417
418 * `proxy_url`: an upstream proxy to fetch posts and/or media with, (default: `nil`)
419 * `send_user_agent`: should we include a user agent with HTTP requests? (default: `true`)
420 * `user_agent`: what user agent should we use? (default: `:default`), must be string or `:default`
421 * `adapter`: array of adapter options
422
423 ### :hackney_pools
424
425 Advanced. Tweaks Hackney (http client) connections pools.
426
427 There's three pools used:
428
429 * `:federation` for the federation jobs.
430 You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs.
431 * `:media` for rich media, media proxy
432 * `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`)
433
434 For each pool, the options are:
435
436 * `max_connections` - how much connections a pool can hold
437 * `timeout` - retention duration for connections
438
439
440 ### :connections_pool
441
442 *For `gun` adapter*
443
444 Advanced settings for connections pool. Pool with opened connections. These connections can be reused in worker pools.
445
446 For big instances it's recommended to increase `config :pleroma, :connections_pool, max_connections: 500` up to 500-1000.
447 It will increase memory usage, but federation would work faster.
448
449 * `:checkin_timeout` - timeout to checkin connection from pool. Default: 250ms.
450 * `:max_connections` - maximum number of connections in the pool. Default: 250 connections.
451 * `:retry` - number of retries, while `gun` will try to reconnect if connection goes down. Default: 1.
452 * `:retry_timeout` - time between retries when `gun` will try to reconnect in milliseconds. Default: 1000ms.
453 * `:await_up_timeout` - timeout while `gun` will wait until connection is up. Default: 5000ms.
454
455 ### :pools
456
457 *For `gun` adapter*
458
459 Advanced settings for workers pools.
460
461 There are four pools used:
462
463 * `:federation` for the federation jobs.
464 You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs.
465 * `:media` for rich media, media proxy
466 * `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`)
467 * `:default` for other requests
468
469 For each pool, the options are:
470
471 * `:size` - how much workers the pool can hold
472 * `:timeout` - timeout while `gun` will wait for response
473 * `:max_overflow` - additional workers if pool is under load
474
475
476 ## Captcha
477
478 ### Pleroma.Captcha
479
480 * `enabled`: Whether the captcha should be shown on registration.
481 * `method`: The method/service to use for captcha.
482 * `seconds_valid`: The time in seconds for which the captcha is valid.
483
484 ### Captcha providers
485
486 #### Pleroma.Captcha.Native
487
488 A built-in captcha provider. Enabled by default.
489
490 #### Pleroma.Captcha.Kocaptcha
491
492 Kocaptcha is a very simple captcha service with a single API endpoint,
493 the source code is here: https://github.com/koto-bank/kocaptcha. The default endpoint
494 `https://captcha.kotobank.ch` is hosted by the developer.
495
496 * `endpoint`: the Kocaptcha endpoint to use.
497
498 ## Uploads
499
500 ### Pleroma.Upload
501 * `uploader`: Which one of the [uploaders](#uploaders) to use.
502 * `filters`: List of [upload filters](#upload-filters) to use.
503 * `link_name`: When enabled Pleroma will add a `name` parameter to the url of the upload, for example `https://instance.tld/media/corndog.png?name=corndog.png`. This is needed to provide the correct filename in Content-Disposition headers when using filters like `Pleroma.Upload.Filter.Dedupe`
504 * `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host.
505 * `proxy_remote`: If you're using a remote uploader, Pleroma will proxy media requests instead of redirecting to it.
506 * `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation.
507 * `filename_display_max_length`: Set max length of a filename to display. 0 = no limit. Default: 30.
508
509 !!! warning
510 `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`.
511
512 ### Uploaders
513 #### Pleroma.Uploaders.Local
514 * `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory.
515
516 #### Pleroma.Uploaders.S3
517 * `bucket`: S3 bucket name.
518 * `bucket_namespace`: S3 bucket namespace.
519 * `public_endpoint`: S3 endpoint that the user finally accesses(ex. "https://s3.dualstack.ap-northeast-1.amazonaws.com")
520 * `truncated_namespace`: If you use S3 compatible service such as Digital Ocean Spaces or CDN, set folder name or "" etc.
521 For example, when using CDN to S3 virtual host format, set "".
522 At this time, write CNAME to CDN in public_endpoint.
523 * `streaming_enabled`: Enable streaming uploads, when enabled the file will be sent to the server in chunks as it's being read. This may be unsupported by some providers, try disabling this if you have upload problems.
524
525
526 ### Upload filters
527
528 #### Pleroma.Upload.Filter.Mogrify
529
530 * `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`.
531
532 #### Pleroma.Upload.Filter.Dedupe
533
534 No specific configuration.
535
536 #### Pleroma.Upload.Filter.AnonymizeFilename
537
538 This filter replaces the filename (not the path) of an upload. For complete obfuscation, add
539 `Pleroma.Upload.Filter.Dedupe` before AnonymizeFilename.
540
541 * `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used. You can get the original filename extension by using `{extension}`, for example `custom-file-name.{extension}`.
542
543 ## Email
544
545 ### Pleroma.Emails.Mailer
546 * `adapter`: one of the mail adapters listed in [Swoosh readme](https://github.com/swoosh/swoosh#adapters), or `Swoosh.Adapters.Local` for in-memory mailbox.
547 * `api_key` / `password` and / or other adapter-specific settings, per the above documentation.
548 * `enabled`: Allows enable/disable send emails. Default: `false`.
549
550 An example for Sendgrid adapter:
551
552 ```elixir
553 config :pleroma, Pleroma.Emails.Mailer,
554 enabled: true,
555 adapter: Swoosh.Adapters.Sendgrid,
556 api_key: "YOUR_API_KEY"
557 ```
558
559 An example for SMTP adapter:
560
561 ```elixir
562 config :pleroma, Pleroma.Emails.Mailer,
563 enabled: true,
564 adapter: Swoosh.Adapters.SMTP,
565 relay: "smtp.gmail.com",
566 username: "YOUR_USERNAME@gmail.com",
567 password: "YOUR_SMTP_PASSWORD",
568 port: 465,
569 ssl: true,
570 auth: :always
571 ```
572
573 ### :email_notifications
574
575 Email notifications settings.
576
577 - digest - emails of "what you've missed" for users who have been
578 inactive for a while.
579 - active: globally enable or disable digest emails
580 - schedule: When to send digest email, in [crontab format](https://en.wikipedia.org/wiki/Cron).
581 "0 0 * * 0" is the default, meaning "once a week at midnight on Sunday morning"
582 - interval: Minimum interval between digest emails to one user
583 - inactivity_threshold: Minimum user inactivity threshold
584
585 ### Pleroma.Emails.UserEmail
586
587 - `:logo` - a path to a custom logo. Set it to `nil` to use the default Pleroma logo.
588 - `:styling` - a map with color settings for email templates.
589
590 ### Pleroma.Emails.NewUsersDigestEmail
591
592 - `:enabled` - a boolean, enables new users admin digest email when `true`. Defaults to `false`.
593
594 ## Background jobs
595
596 ### Oban
597
598 [Oban](https://github.com/sorentwo/oban) asynchronous job processor configuration.
599
600 Configuration options described in [Oban readme](https://github.com/sorentwo/oban#usage):
601
602 * `repo` - app's Ecto repo (`Pleroma.Repo`)
603 * `verbose` - logs verbosity
604 * `prune` - non-retryable jobs [pruning settings](https://github.com/sorentwo/oban#pruning) (`:disabled` / `{:maxlen, value}` / `{:maxage, value}`)
605 * `queues` - job queues (see below)
606 * `crontab` - periodic jobs, see [`Oban.Cron`](#obancron)
607
608 Pleroma has the following queues:
609
610 * `activity_expiration` - Activity expiration
611 * `federator_outgoing` - Outgoing federation
612 * `federator_incoming` - Incoming federation
613 * `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleromaemailsmailer)
614 * `transmogrifier` - Transmogrifier
615 * `web_push` - Web push notifications
616 * `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivity`](#pleromascheduledactivity)
617
618 #### Oban.Cron
619
620 Pleroma has these periodic job workers:
621
622 `Pleroma.Workers.Cron.ClearOauthTokenWorker` - a job worker to cleanup expired oauth tokens.
623
624 Example:
625
626 ```elixir
627 config :pleroma, Oban,
628 repo: Pleroma.Repo,
629 verbose: false,
630 prune: {:maxlen, 1500},
631 queues: [
632 federator_incoming: 50,
633 federator_outgoing: 50
634 ],
635 crontab: [
636 {"0 0 * * *", Pleroma.Workers.Cron.ClearOauthTokenWorker}
637 ]
638 ```
639
640 This config contains two queues: `federator_incoming` and `federator_outgoing`. Both have the number of max concurrent jobs set to `50`.
641
642 #### Migrating `pleroma_job_queue` settings
643
644 `config :pleroma_job_queue, :queues` is replaced by `config :pleroma, Oban, :queues` and uses the same format (keys are queues' names, values are max concurrent jobs numbers).
645
646 ### :workers
647
648 Includes custom worker options not interpretable directly by `Oban`.
649
650 * `retries` — keyword lists where keys are `Oban` queues (see above) and values are numbers of max attempts for failed jobs.
651
652 Example:
653
654 ```elixir
655 config :pleroma, :workers,
656 retries: [
657 federator_incoming: 5,
658 federator_outgoing: 5
659 ]
660 ```
661
662 #### Migrating `Pleroma.Web.Federator.RetryQueue` settings
663
664 * `max_retries` is replaced with `config :pleroma, :workers, retries: [federator_outgoing: 5]`
665 * `enabled: false` corresponds to `config :pleroma, :workers, retries: [federator_outgoing: 1]`
666 * deprecated options: `max_jobs`, `initial_timeout`
667
668 ## :web_push_encryption, :vapid_details
669
670 Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it.
671
672 * ``subject``: a mailto link for the administrative contact. It’s best if this email is not a personal email address, but rather a group email so that if a person leaves an organization, is unavailable for an extended period, or otherwise can’t respond, someone else on the list can.
673 * ``public_key``: VAPID public key
674 * ``private_key``: VAPID private key
675
676 ## :logger
677 * `backends`: `:console` is used to send logs to stdout, `{ExSyslogger, :ex_syslogger}` to log to syslog, and `Quack.Logger` to log to Slack
678
679 An example to enable ONLY ExSyslogger (f/ex in ``prod.secret.exs``) with info and debug suppressed:
680 ```elixir
681 config :logger,
682 backends: [{ExSyslogger, :ex_syslogger}]
683
684 config :logger, :ex_syslogger,
685 level: :warn
686 ```
687
688 Another example, keeping console output and adding the pid to syslog output:
689 ```elixir
690 config :logger,
691 backends: [:console, {ExSyslogger, :ex_syslogger}]
692
693 config :logger, :ex_syslogger,
694 level: :warn,
695 option: [:pid, :ndelay]
696 ```
697
698 See: [logger’s documentation](https://hexdocs.pm/logger/Logger.html) and [ex_syslogger’s documentation](https://hexdocs.pm/ex_syslogger/)
699
700 An example of logging info to local syslog, but warn to a Slack channel:
701 ```elixir
702 config :logger,
703 backends: [ {ExSyslogger, :ex_syslogger}, Quack.Logger ],
704 level: :info
705
706 config :logger, :ex_syslogger,
707 level: :info,
708 ident: "pleroma",
709 format: "$metadata[$level] $message"
710
711 config :quack,
712 level: :warn,
713 meta: [:all],
714 webhook_url: "https://hooks.slack.com/services/YOUR-API-KEY-HERE"
715 ```
716
717 See the [Quack Github](https://github.com/azohra/quack) for more details
718
719
720
721 ## Database options
722
723 ### RUM indexing for full text search
724
725 !!! warning
726 It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.
727
728 * `rum_enabled`: If RUM indexes should be used. Defaults to `false`.
729
730 RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. While they may eventually be mainlined, for now they have to be installed as a PostgreSQL extension from https://github.com/postgrespro/rum.
731
732 Their advantage over the standard GIN indexes is that they allow efficient ordering of search results by timestamp, which makes search queries a lot faster on larger servers, by one or two orders of magnitude. They take up around 3 times as much space as GIN indexes.
733
734 To enable them, both the `rum_enabled` flag has to be set and the following special migration has to be run:
735
736 `mix ecto.migrate --migrations-path priv/repo/optional_migrations/rum_indexing/`
737
738 This will probably take a long time.
739
740 ## Alternative client protocols
741
742 ### BBS / SSH access
743
744 To enable simple command line interface accessible over ssh, add a setting like this to your configuration file:
745
746 ```exs
747 app_dir = File.cwd!
748 priv_dir = Path.join([app_dir, "priv/ssh_keys"])
749
750 config :esshd,
751 enabled: true,
752 priv_dir: priv_dir,
753 handler: "Pleroma.BBS.Handler",
754 port: 10_022,
755 password_authenticator: "Pleroma.BBS.Authenticator"
756 ```
757
758 Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -m PEM -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT`
759
760 ### :gopher
761 * `enabled`: Enables the gopher interface
762 * `ip`: IP address to bind to
763 * `port`: Port to bind to
764 * `dstport`: Port advertised in urls (optional, defaults to `port`)
765
766
767 ## Authentication
768
769 ### :admin_token
770
771 Allows to set a token that can be used to authenticate with the admin api without using an actual user by giving it as the `admin_token` parameter or `x-admin-token` HTTP header. Example:
772
773 ```elixir
774 config :pleroma, :admin_token, "somerandomtoken"
775 ```
776
777 You can then do
778
779 ```shell
780 curl "http://localhost:4000/api/pleroma/admin/users/invites?admin_token=somerandomtoken"
781 ```
782
783 or
784
785 ```shell
786 curl -H "X-Admin-Token: somerandomtoken" "http://localhost:4000/api/pleroma/admin/users/invites"
787 ```
788
789 ### :auth
790
791 * `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator.
792 * `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication.
793
794 Authentication / authorization settings.
795
796 * `auth_template`: authentication form template. By default it's `show.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/show.html.eex`.
797 * `oauth_consumer_template`: OAuth consumer mode authentication form template. By default it's `consumer.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/consumer.html.eex`.
798 * `oauth_consumer_strategies`: the list of enabled OAuth consumer strategies; by default it's set by `OAUTH_CONSUMER_STRATEGIES` environment variable. Each entry in this space-delimited string should be of format `<strategy>` or `<strategy>:<dependency>` (e.g. `twitter` or `keycloak:ueberauth_keycloak_strategy` in case dependency is named differently than `ueberauth_<strategy>`).
799
800 ### Pleroma.Web.Auth.Authenticator
801
802 * `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator.
803 * `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication.
804
805 ### :ldap
806
807 Use LDAP for user authentication. When a user logs in to the Pleroma
808 instance, the name and password will be verified by trying to authenticate
809 (bind) to an LDAP server. If a user exists in the LDAP directory but there
810 is no account with the same name yet on the Pleroma instance then a new
811 Pleroma account will be created with the same name as the LDAP user name.
812
813 * `enabled`: enables LDAP authentication
814 * `host`: LDAP server hostname
815 * `port`: LDAP port, e.g. 389 or 636
816 * `ssl`: true to use SSL, usually implies the port 636
817 * `sslopts`: additional SSL options
818 * `tls`: true to start TLS, usually implies the port 389
819 * `tlsopts`: additional TLS options
820 * `base`: LDAP base, e.g. "dc=example,dc=com"
821 * `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base"
822
823 ### OAuth consumer mode
824
825 OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.).
826 Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies).
827
828 !!! note
829 Each strategy is shipped as a separate dependency; in order to get the strategies, run `OAUTH_CONSUMER_STRATEGIES="..." mix deps.get`, e.g. `OAUTH_CONSUMER_STRATEGIES="twitter facebook google microsoft" mix deps.get`. The server should also be started with `OAUTH_CONSUMER_STRATEGIES="..." mix phx.server` in case you enable any strategies.
830
831 !!! note
832 Each strategy requires separate setup (on external provider side and Pleroma side). Below are the guidelines on setting up most popular strategies.
833
834 !!! note
835 Make sure that `"SameSite=Lax"` is set in `extra_cookie_attrs` when you have this feature enabled. OAuth consumer mode will not work with `"SameSite=Strict"`
836
837 * For Twitter, [register an app](https://developer.twitter.com/en/apps), configure callback URL to https://<your_host>/oauth/twitter/callback
838
839 * For Facebook, [register an app](https://developers.facebook.com/apps), configure callback URL to https://<your_host>/oauth/facebook/callback, enable Facebook Login service at https://developers.facebook.com/apps/<app_id>/fb-login/settings/
840
841 * For Google, [register an app](https://console.developers.google.com), configure callback URL to https://<your_host>/oauth/google/callback
842
843 * For Microsoft, [register an app](https://portal.azure.com), configure callback URL to https://<your_host>/oauth/microsoft/callback
844
845 Once the app is configured on external OAuth provider side, add app's credentials and strategy-specific settings (if any — e.g. see Microsoft below) to `config/prod.secret.exs`,
846 per strategy's documentation (e.g. [ueberauth_twitter](https://github.com/ueberauth/ueberauth_twitter)). Example config basing on environment variables:
847
848 ```elixir
849 # Twitter
850 config :ueberauth, Ueberauth.Strategy.Twitter.OAuth,
851 consumer_key: System.get_env("TWITTER_CONSUMER_KEY"),
852 consumer_secret: System.get_env("TWITTER_CONSUMER_SECRET")
853
854 # Facebook
855 config :ueberauth, Ueberauth.Strategy.Facebook.OAuth,
856 client_id: System.get_env("FACEBOOK_APP_ID"),
857 client_secret: System.get_env("FACEBOOK_APP_SECRET"),
858 redirect_uri: System.get_env("FACEBOOK_REDIRECT_URI")
859
860 # Google
861 config :ueberauth, Ueberauth.Strategy.Google.OAuth,
862 client_id: System.get_env("GOOGLE_CLIENT_ID"),
863 client_secret: System.get_env("GOOGLE_CLIENT_SECRET"),
864 redirect_uri: System.get_env("GOOGLE_REDIRECT_URI")
865
866 # Microsoft
867 config :ueberauth, Ueberauth.Strategy.Microsoft.OAuth,
868 client_id: System.get_env("MICROSOFT_CLIENT_ID"),
869 client_secret: System.get_env("MICROSOFT_CLIENT_SECRET")
870
871 config :ueberauth, Ueberauth,
872 providers: [
873 microsoft: {Ueberauth.Strategy.Microsoft, [callback_params: []]}
874 ]
875
876 # Keycloak
877 # Note: make sure to add `keycloak:ueberauth_keycloak_strategy` entry to `OAUTH_CONSUMER_STRATEGIES` environment variable
878 keycloak_url = "https://publicly-reachable-keycloak-instance.org:8080"
879
880 config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth,
881 client_id: System.get_env("KEYCLOAK_CLIENT_ID"),
882 client_secret: System.get_env("KEYCLOAK_CLIENT_SECRET"),
883 site: keycloak_url,
884 authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth",
885 token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token",
886 userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo",
887 token_method: :post
888
889 config :ueberauth, Ueberauth,
890 providers: [
891 keycloak: {Ueberauth.Strategy.Keycloak, [uid_field: :email]}
892 ]
893 ```
894
895 ### OAuth 2.0 provider - :oauth2
896
897 Configure OAuth 2 provider capabilities:
898
899 * `token_expires_in` - The lifetime in seconds of the access token.
900 * `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token.
901 * `clean_expired_tokens` - Enable a background job to clean expired oauth tokens. Defaults to `false`. Interval settings sets in configuration periodic jobs [`Oban.Cron`](#obancron)
902
903 ## Link parsing
904
905 ### :uri_schemes
906 * `valid_schemes`: List of the scheme part that is considered valid to be an URL.
907
908 ### :auto_linker
909
910 Configuration for the `auto_linker` library:
911
912 * `class: "auto-linker"` - specify the class to be added to the generated link. false to clear.
913 * `rel: "noopener noreferrer"` - override the rel attribute. false to clear.
914 * `new_window: true` - set to false to remove `target='_blank'` attribute.
915 * `scheme: false` - Set to true to link urls with schema `http://google.com`.
916 * `truncate: false` - Set to a number to truncate urls longer then the number. Truncated urls will end in `..`.
917 * `strip_prefix: true` - Strip the scheme prefix.
918 * `extra: false` - link urls with rarely used schemes (magnet, ipfs, irc, etc.).
919
920 Example:
921
922 ```elixir
923 config :auto_linker,
924 opts: [
925 scheme: true,
926 extra: true,
927 class: false,
928 strip_prefix: false,
929 new_window: false,
930 rel: "ugc"
931 ]
932 ```
933
934 ## Custom Runtime Modules (`:modules`)
935
936 * `runtime_dir`: A path to custom Elixir modules (such as MRF policies).
937
938 ## :configurable_from_database
939
940 Boolean, enables/disables in-database configuration. Read [Transfering the config to/from the database](../administration/CLI_tasks/config.md) for more information.
941
942 ## :database_config_whitelist
943
944 List of valid configuration sections which are allowed to be configured from the
945 database. Settings stored in the database before the whitelist is configured are
946 still applied, so it is suggested to only use the whitelist on instances that
947 have not migrated the config to the database.
948
949 Example:
950 ```elixir
951 config :pleroma, :database_config_whitelist, [
952 {:pleroma, :instance},
953 {:pleroma, Pleroma.Web.Metadata},
954 {:auto_linker}
955 ]
956 ```
957
958 ### Multi-factor authentication - :two_factor_authentication
959 * `totp` - a list containing TOTP configuration
960 - `digits` - Determines the length of a one-time pass-code in characters. Defaults to 6 characters.
961 - `period` - a period for which the TOTP code will be valid in seconds. Defaults to 30 seconds.
962 * `backup_codes` - a list containing backup codes configuration
963 - `number` - number of backup codes to generate.
964 - `length` - backup code length. Defaults to 16 characters.
965
966 ## Restrict entities access for unauthenticated users
967
968 ### :restrict_unauthenticated
969
970 Restrict access for unauthenticated users to timelines (public and federate), user profiles and statuses.
971
972 * `timelines` - public and federated timelines
973 * `local` - public timeline
974 * `federated`
975 * `profiles` - user profiles
976 * `local`
977 * `remote`
978 * `activities` - statuses
979 * `local`
980 * `remote`
981
982
983 ## Pleroma.Web.ApiSpec.CastAndValidate
984
985 * `:strict` a boolean, enables strict input validation (useful in development, not recommended in production). Defaults to `false`.