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