config.md 31.1 KB
Newer Older
Haelwenn's avatar
Haelwenn committed
1 2
# Configuration

3 4 5
This file describe the configuration, it is recommended to edit the relevant *.secret.exs file instead of the others founds in the ``config`` directory.
If you run Pleroma with ``MIX_ENV=prod`` the file is ``prod.secret.exs``, otherwise it is ``dev.secret.exs``.

Haelwenn's avatar
Haelwenn committed
6 7
## Pleroma.Upload
* `uploader`: Select which `Pleroma.Uploaders` to use
href's avatar
href committed
8
* `filters`: List of `Pleroma.Upload.Filter` to use.
rinpatch's avatar
rinpatch committed
9
* `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`
href's avatar
href committed
10
* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host.
11
* `proxy_remote`: If you\'re using a remote uploader, Pleroma will proxy media requests instead of redirecting to it.
href's avatar
href committed
12 13 14
* `proxy_opts`: Proxy options, see `Pleroma.ReverseProxy` documentation.

Note: `strip_exif` has been replaced by `Pleroma.Upload.Filter.Mogrify`.
Haelwenn's avatar
Haelwenn committed
15 16

## Pleroma.Uploaders.Local
Haelwenn's avatar
Haelwenn committed
17
* `uploads`: Which directory to store the user-uploads in, relative to pleroma’s working directory
href's avatar
href committed
18

aries's avatar
aries committed
19 20
## Pleroma.Uploaders.S3
* `bucket`: S3 bucket name
aries's avatar
aries committed
21
* `public_endpoint`: S3 endpoint that the user finally accesses(ex. "https://s3.dualstack.ap-northeast-1.amazonaws.com")
aries's avatar
aries committed
22 23 24 25
* `truncated_namespace`: If you use S3 compatible service such as Digital Ocean Spaces or CDN, set folder name or "" etc.
For example, when using CDN to S3 virtual host format, set "".
At this time, write CNAME to CDN in public_endpoint.

href's avatar
href committed
26 27
## Pleroma.Upload.Filter.Mogrify

28
* `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"impode", "1"}]`.
Haelwenn's avatar
Haelwenn committed
29

30 31 32 33 34 35
## Pleroma.Upload.Filter.Dedupe

No specific configuration.

## Pleroma.Upload.Filter.AnonymizeFilename

href's avatar
href committed
36
This filter replaces the filename (not the path) of an upload. For complete obfuscation, add
37 38
`Pleroma.Upload.Filter.Dedupe` before AnonymizeFilename.

href's avatar
href committed
39
* `text`: Text to replace filenames in links. If empty, `{random}.extension` will be used.
40

41
## Pleroma.Emails.Mailer
42
* `adapter`: one of the mail adapters listed in [Swoosh readme](https://github.com/swoosh/swoosh#adapters), or `Swoosh.Adapters.Local` for in-memory mailbox.
43
* `api_key` / `password` and / or other adapter-specific settings, per the above documentation.
44 45 46

An example for Sendgrid adapter:

47
```elixir
48
config :pleroma, Pleroma.Emails.Mailer,
49 50 51 52 53
  adapter: Swoosh.Adapters.Sendgrid,
  api_key: "YOUR_API_KEY"
```

An example for SMTP adapter:
minibikini's avatar
minibikini committed
54

55
```elixir
56
config :pleroma, Pleroma.Emails.Mailer,
57 58 59 60 61 62 63 64 65 66
  adapter: Swoosh.Adapters.SMTP,
  relay: "smtp.gmail.com",
  username: "YOUR_USERNAME@gmail.com",
  password: "YOUR_SMTP_PASSWORD",
  port: 465,
  ssl: true,
  tls: :always,
  auth: :always
```

Haelwenn's avatar
Haelwenn committed
67
## :uri_schemes
Haelwenn's avatar
Haelwenn committed
68 69
* `valid_schemes`: List of the scheme part that is considered valid to be an URL

Haelwenn's avatar
Haelwenn committed
70
## :instance
71
* `name`: The instance’s name
Haelwenn's avatar
Haelwenn committed
72
* `email`: Email used to reach an Administrator/Moderator of the instance
73
* `notify_email`: Email used for notifications.
74 75
* `description`: The instance’s description, can be seen in nodeinfo and ``/api/v1/instance``
* `limit`: Posts character limit (CW/Subject included in the counter)
76
* `remote_limit`: Hard character limit beyond which remote posts will be dropped.
Haelwenn's avatar
Haelwenn committed
77 78 79
* `upload_limit`: File size limit of uploads (except for avatar, background, banner)
* `avatar_upload_limit`: File size limit of user’s profile avatars
* `background_upload_limit`: File size limit of user’s profile backgrounds
80
* `banner_upload_limit`: File size limit of user’s profile banners
81 82 83 84 85
* `poll_limits`: A map with poll limits for **local** polls
  * `max_options`: Maximum number of options
  * `max_option_chars`: Maximum number of characters per option
  * `min_expiration`: Minimum expiration time (in seconds)
  * `max_expiration`: Maximum expiration time (in seconds)
86 87
* `registrations_open`: Enable registrations for anyone, invitations can be enabled when false.
* `invites_enabled`: Enable user invitations for admins (depends on `registrations_open: false`).
88
* `account_activation_required`: Require users to confirm their emails before signing in.
89
* `federating`: Enable federation with other instances
90
* `federation_reachability_timeout_days`: Timeout (in days) of each external federation target being unreachable prior to pausing federating to it.
91
* `allow_relay`: Enable Pleroma’s Relay, which makes it possible to follow a whole instance
92 93 94 95
* `rewrite_policy`: Message Rewrite Policy, either one or a list. Here are the ones available by default:
  * `Pleroma.Web.ActivityPub.MRF.NoOpPolicy`: Doesn’t modify activities (default)
  * `Pleroma.Web.ActivityPub.MRF.DropPolicy`: Drops all activities. It generally doesn’t makes sense to use in production
  * `Pleroma.Web.ActivityPub.MRF.SimplePolicy`: Restrict the visibility of activities from certains instances (See ``:mrf_simple`` section)
96
  * `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)
kaniini's avatar
kaniini committed
97
  * `Pleroma.Web.ActivityPub.MRF.SubchainPolicy`: Selectively runs other MRF policies when messages match (see ``:mrf_subchain`` section)
98
  * `Pleroma.Web.ActivityPub.MRF.RejectNonPublic`: Drops posts with non-public visibility settings (See ``:mrf_rejectnonpublic`` section)
99
  * `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:.
100
  * `Pleroma.Web.ActivityPub.MRF.AntiLinkSpamPolicy`: Rejects posts from likely spambots by rejecting posts from new users that contain links.
101
* `public`: Makes the client API in authentificated mode-only except for user-profiles. Useful for disabling the Local Timeline and The Whole Known Network.
Haelwenn's avatar
Haelwenn committed
102 103 104 105
* `quarantined_instances`: List of ActivityPub instances where private(DMs, followers-only) activities will not be send.
* `managed_config`: Whenether the config for pleroma-fe is configured in this config or in ``static/config.json``
* `allowed_post_formats`: MIME-type list of formats allowed to be posted (transformed into HTML)
* `mrf_transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo).
scarlett's avatar
scarlett committed
106 107 108 109 110 111
* `scope_copy`: Copy the scope (private/unlisted/public) in replies to posts by default.
* `subject_line_behavior`: Allows changing the default behaviour of subject lines in replies. Valid values:
  * "email": Copy and preprend re:, as in email.
  * "masto": Copy verbatim, as in Mastodon.
  * "noop": Don't copy the subject.
* `always_show_subject_input`: When set to false, auto-hide the subject field when it's empty.
href's avatar
href committed
112
* `extended_nickname_format`: Set to `true` to use extended local nicknames format (allows underscores/dashes). This will break federation with
href's avatar
href committed
113
    older software for theses nicknames.
114
* `max_pinned_statuses`: The maximum number of pinned statuses. `0` will disable the feature.
115
* `autofollowed_nicknames`: Set to nicknames of (local) users that every new user should automatically follow.
feld's avatar
feld committed
116
* `no_attachment_links`: Set to true to disable automatically adding attachment link text to statuses
lain's avatar
lain committed
117
* `welcome_message`: A message that will be send to a newly registered users as a direct message.
118
* `welcome_user_nickname`: The nickname of the local user that sends the welcome message.
lain's avatar
lain committed
119
* `max_report_comment_size`: The maximum size of the report comment (Default: `1000`)
120 121 122 123
* `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`.
* `healthcheck`: If set to true, system data will be shown on ``/api/pleroma/healthcheck``.
* `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database.
* `skip_thread_containment`: Skip filter out broken threads. The default is `false`.
124
* `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`.
125
* `dynamic_configuration`: Allow transferring configuration to DB with the subsequent customization from Admin api.
126

Haelwenn's avatar
Haelwenn committed
127

128
## :logger
129
* `backends`: `:console` is used to send logs to stdout, `{ExSyslogger, :ex_syslogger}` to log to syslog, and `Quack.Logger` to log to Slack
130 131

An example to enable ONLY ExSyslogger (f/ex in ``prod.secret.exs``) with info and debug suppressed:
132
```elixir
minibikini's avatar
minibikini committed
133
config :logger,
134 135 136 137 138 139 140
  backends: [{ExSyslogger, :ex_syslogger}]

config :logger, :ex_syslogger,
  level: :warn
```

Another example, keeping console output and adding the pid to syslog output:
141
```elixir
142 143 144 145 146 147 148 149
config :logger,
  backends: [:console, {ExSyslogger, :ex_syslogger}]

config :logger, :ex_syslogger,
  level: :warn,
  option: [:pid, :ndelay]
```

150 151
See: [logger’s documentation](https://hexdocs.pm/logger/Logger.html) and [ex_syslogger’s documentation](https://hexdocs.pm/ex_syslogger/)

152
An example of logging info to local syslog, but warn to a Slack channel:
153
```elixir
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169
config :logger,
  backends: [ {ExSyslogger, :ex_syslogger}, Quack.Logger ],
  level: :info

config :logger, :ex_syslogger,
  level: :info,
  ident: "pleroma",
  format: "$metadata[$level] $message"

config :quack,
  level: :warn,
  meta: [:all],
  webhook_url: "https://hooks.slack.com/services/YOUR-API-KEY-HERE"
```

See the [Quack Github](https://github.com/azohra/quack) for more details
lain's avatar
lain committed
170 171 172

## :frontend_configurations

Haelwenn's avatar
Haelwenn committed
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.
lain's avatar
lain committed
174 175 176 177 178

Frontends can access these settings at `/api/pleroma/frontend_configurations`

To add your own configuration for PleromaFE, use it like this:

179 180 181 182 183 184 185 186 187 188
```elixir
config :pleroma, :frontend_configurations,
  pleroma_fe: %{
    theme: "pleroma-dark",
    # ... see /priv/static/static/config.json for the available keys.
},
  masto_fe: %{
    showInstanceSpecificPanel: true
  }
```
lain's avatar
lain committed
189

190 191
These settings **need to be complete**, they will override the defaults.

Alexander Strizhakov's avatar
Alexander Strizhakov committed
192
NOTE: for versions < 1.0, you need to set [`:fe`](#fe) to false, as shown a few lines below.
lain's avatar
lain committed
193

Haelwenn's avatar
Haelwenn committed
194
## :fe
lain's avatar
lain committed
195
__THIS IS DEPRECATED__
lain's avatar
lain committed
196

197
If you are using this method, please change it to the [`frontend_configurations`](#frontend_configurations) method.
Alexander Strizhakov's avatar
Alexander Strizhakov committed
198
Please **set this option to false** in your config like this:
199 200 201 202

```elixir
config :pleroma, :fe, false
```
lain's avatar
lain committed
203

204 205 206 207
This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:instance`` is set to false.

* `theme`: Which theme to use, they are defined in ``styles.json``
* `logo`: URL of the logo, defaults to Pleroma’s logo
208
* `logo_mask`: Whether to use only the logo's shape as a mask (true) or as a regular image (false)
209 210 211 212 213
* `logo_margin`: What margin to use around the logo
* `background`: URL of the background, unless viewing a user profile with a background that is set
* `redirect_root_no_login`: relative URL which indicates where to redirect when a user isn’t logged in.
* `redirect_root_login`: relative URL which indicates where to redirect when a user is logged in.
* `show_instance_panel`: Whenether to show the instance’s specific panel.
214
* `scope_options_enabled`: Enable setting an notice visibility and subject/CW when posting
Haelwenn's avatar
Haelwenn committed
215 216 217 218 219
* `formatting_options_enabled`: Enable setting a formatting different than plain-text (ie. HTML, Markdown) when posting, relates to ``:instance, allowed_post_formats``
* `collapse_message_with_subjects`: When a message has a subject(aka Content Warning), collapse it by default
* `hide_post_stats`: Hide notices statistics(repeats, favorites, …)
* `hide_user_stats`: Hide profile statistics(posts, posts per day, followers, followings, …)

220 221 222 223 224 225 226 227 228 229
## :assets

This section configures assets to be used with various frontends. Currently the only option
relates to mascots on the mastodon frontend

* `mascots`: KeywordList of mascots, each element __MUST__ contain both a `url` and a
  `mime_type` key.
* `default_mascot`: An element from `mascots` - This will be used as the default mascot
  on MastoFE (default: `:pleroma_fox_tan`)

Haelwenn's avatar
Haelwenn committed
230 231 232 233 234 235
## :mrf_simple
* `media_removal`: List of instances to remove medias from
* `media_nsfw`: List of instances to put medias as NSFW(sensitive) from
* `federated_timeline_removal`: List of instances to remove from Federated (aka The Whole Known Network) Timeline
* `reject`: List of instances to reject any activities from
* `accept`: List of instances to accept any activities from
236 237 238
* `report_removal`: List of instances to reject reports from
* `avatar_removal`: List of instances to strip avatars from
* `banner_removal`: List of instances to strip banners from
Haelwenn's avatar
Haelwenn committed
239

kaniini's avatar
kaniini committed
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254
## :mrf_subchain
This policy processes messages through an alternate pipeline when a given message matches certain criteria.
All criteria are configured as a map of regular expressions to lists of policy modules.

* `match_actor`: Matches a series of regular expressions against the actor field.

Example:

```
config :pleroma, :mrf_subchain,
  match_actor: %{
    ~r/https:\/\/example.com/s => [Pleroma.Web.ActivityPub.MRF.DropPolicy]
  }
```

255 256 257 258
## :mrf_rejectnonpublic
* `allow_followersonly`: whether to allow followers-only posts
* `allow_direct`: whether to allow direct messages

Karen Konou's avatar
Karen Konou committed
259
## :mrf_hellthread
Karen Konou's avatar
Karen Konou committed
260
* `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.
Karen Konou's avatar
Karen Konou committed
261
* `reject_threshold`: Number of mentioned users after which the messaged gets rejected. Set to 0 to disable.
Karen Konou's avatar
Karen Konou committed
262

rinpatch's avatar
rinpatch committed
263 264
## :mrf_keyword
* `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)
rinpatch's avatar
rinpatch committed
265
* `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)
rinpatch's avatar
rinpatch committed
266
* `replace`: A list of tuples containing `{pattern, replacement}`, `pattern` can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html)
rinpatch's avatar
rinpatch committed
267

Haelwenn's avatar
Haelwenn committed
268 269
## :media_proxy
* `enabled`: Enables proxying of remote media to the instance’s proxy
href's avatar
href committed
270 271
* `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host/CDN fronts.
* `proxy_opts`: All options defined in `Pleroma.ReverseProxy` documentation, defaults to `[max_body_length: (25*1_048_576)]`.
feld's avatar
feld committed
272
* `whitelist`: List of domains to bypass the mediaproxy
Haelwenn's avatar
Haelwenn committed
273 274 275 276 277

## :gopher
* `enabled`: Enables the gopher interface
* `ip`: IP address to bind to
* `port`: Port to bind to
278
* `dstport`: Port advertised in urls (optional, defaults to `port`)
279

280 281 282 283 284 285 286
## Pleroma.Web.Endpoint
`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
* `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
  - `ip` - a tuple consisting of 4 integers
  - `port`
* `url` - a list containing the configuration for generating urls, accepts
  - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`)
287
  - `scheme` - e.g `http`, `https`
288 289
  - `port`
  - `path`
290 291
* `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.

292 293


294
**Important note**: if you modify anything inside these lists, default `config.exs` values will be overwritten, which may result in breakage, to make sure this does not happen please copy the default value for the list from `config.exs` and modify/add only what you need
295

296
Example:
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
```elixir
config :pleroma, Pleroma.Web.Endpoint,
  url: [host: "example.com", port: 2020, scheme: "https"],
  http: [
    # start copied from config.exs
    dispatch: [
      {:_,
       [
         {"/api/v1/streaming", Pleroma.Web.MastodonAPI.WebsocketHandler, []},
         {"/websocket", Phoenix.Endpoint.CowboyWebSocket,
          {Phoenix.Transports.WebSocket,
           {Pleroma.Web.Endpoint, Pleroma.Web.UserSocket, websocket_config}}},
         {:_, Phoenix.Endpoint.Cowboy2Handler, {Pleroma.Web.Endpoint, []}}
       ]}
    # end copied from config.exs
    ],
    port: 8080,
    ip: {127, 0, 0, 1}
  ]
```

This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020`

320 321 322 323 324
## :activitypub
* ``accept_blocks``: Whether to accept incoming block activities from other instances
* ``unfollow_blocked``: Whether blocks result in people getting unfollowed
* ``outgoing_blocks``: Whether to federate blocks to other instances
* ``deny_follow_blocked``: Whether to disallow following an account that has blocked the user in question
325

kaniini's avatar
kaniini committed
326
## :http_security
327 328 329
* ``enabled``: Whether the managed content security policy is enabled
* ``sts``: Whether to additionally send a `Strict-Transport-Security` header
* ``sts_max_age``: The maximum age for the `Strict-Transport-Security` header if sent
kaniini's avatar
kaniini committed
330
* ``ct_max_age``: The maximum age for the `Expect-CT` header if sent
331 332
* ``referrer_policy``: The referrer policy to use, either `"same-origin"` or `"no-referrer"`
* ``report_uri``: Adds the specified url to `report-uri` and `report-to` group in CSP header.
kaniini's avatar
kaniini committed
333 334 335 336 337 338 339 340 341

## :mrf_user_allowlist

The keys in this section are the domain names that the policy should apply to.
Each key should be assigned a list of users that should be allowed through by
their ActivityPub ID.

An example:

342
```elixir
kaniini's avatar
kaniini committed
343 344 345
config :pleroma, :mrf_user_allowlist,
  "example.org": ["https://example.org/users/admin"]
```
346

Haelwenn's avatar
Haelwenn committed
347
## :web_push_encryption, :vapid_details
348

lain's avatar
lain committed
349
Web Push Notifications configuration. You can use the mix task `mix web_push.gen.keypair` to generate it.
350 351 352 353

* ``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.
* ``public_key``: VAPID public key
* ``private_key``: VAPID private key
354 355 356 357

## Pleroma.Captcha
* `enabled`: Whether the captcha should be shown on registration
* `method`: The method/service to use for captcha
vaartis's avatar
vaartis committed
358
* `seconds_valid`: The time in seconds for which the captcha is valid
359 360 361

### Pleroma.Captcha.Kocaptcha
Kocaptcha is a very simple captcha service with a single API endpoint,
362 363
the source code is here: https://github.com/koto-bank/kocaptcha. The default endpoint
`https://captcha.kotobank.ch` is hosted by the developer.
364

365 366 367 368 369 370
* `endpoint`: the kocaptcha endpoint to use

## :admin_token

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. Example:

371
```elixir
372 373 374 375
config :pleroma, :admin_token, "somerandomtoken"
```

You can then do
minibikini's avatar
minibikini committed
376 377

```sh
378 379
curl "http://localhost:4000/api/pleroma/admin/invite_token?admin_token=somerandomtoken"
```
lain's avatar
lain committed
380

381
## :pleroma_job_queue
minibikini's avatar
minibikini committed
382

383 384
[Pleroma Job Queue](https://git.pleroma.social/pleroma/pleroma_job_queue) configuration: a list of queues with maximum concurrent jobs.

rinpatch's avatar
qs  
rinpatch committed
385
Pleroma has the following queues:
386

387 388
* `federator_outgoing` - Outgoing federation
* `federator_incoming` - Incoming federation
389
* `mailer` - Email sender, see [`Pleroma.Emails.Mailer`](#pleroma-emails-mailer)
390
* `transmogrifier` - Transmogrifier
391
* `web_push` - Web push notifications
392
* `scheduled_activities` - Scheduled activities, see [`Pleroma.ScheduledActivities`](#pleromascheduledactivity)
minibikini's avatar
minibikini committed
393 394 395

Example:

396 397 398 399
```elixir
config :pleroma_job_queue, :queues,
  federator_incoming: 50,
  federator_outgoing: 50
minibikini's avatar
minibikini committed
400 401 402
```

This config contains two queues: `federator_incoming` and `federator_outgoing`. Both have the `max_jobs` set to `50`.
lain's avatar
lain committed
403 404 405 406

## Pleroma.Web.Federator.RetryQueue

* `enabled`: If set to `true`, failed federation jobs will be retried
scarlett's avatar
scarlett committed
407
* `max_jobs`: The maximum amount of parallel federation jobs running at the same time.
lain's avatar
lain committed
408 409
* `initial_timeout`: The initial timeout in seconds
* `max_retries`: The maximum number of times a federation job is retried
rinpatch's avatar
rinpatch committed
410 411

## Pleroma.Web.Metadata
Alexander Strizhakov's avatar
Alexander Strizhakov committed
412
* `providers`: a list of metadata providers to enable. Providers available:
rinpatch's avatar
rinpatch committed
413 414
  * Pleroma.Web.Metadata.Providers.OpenGraph
  * Pleroma.Web.Metadata.Providers.TwitterCard
Alexander Strizhakov's avatar
Alexander Strizhakov committed
415
  * Pleroma.Web.Metadata.Providers.RelMe - add links from user bio with rel=me into the `<header>` as `<link rel=me>`
416
* `unfurl_nsfw`: If set to `true` nsfw attachments will be shown in previews
href's avatar
href committed
417

rinpatch's avatar
rinpatch committed
418 419 420
## :rich_media
* `enabled`: if enabled the instance will parse metadata from attached links to generate link previews

421 422 423 424
## :fetch_initial_posts
* `enabled`: if enabled, when a new user is federated with, fetch some of their latest posts
* `pages`: the amount of pages to fetch

href's avatar
href committed
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440
## :hackney_pools

Advanced. Tweaks Hackney (http client) connections pools.

There's three pools used:

* `:federation` for the federation jobs.
  You may want this pool max_connections to be at least equal to the number of federator jobs + retry queue jobs.
* `:media` for rich media, media proxy
* `:upload` for uploaded media (if using a remote uploader and `proxy_remote: true`)

For each pool, the options are:

* `max_connections` - how much connections a pool can hold
* `timeout` - retention duration for connections

minibikini's avatar
minibikini committed
441 442 443 444 445 446 447 448 449 450 451 452 453 454
## :auto_linker

Configuration for the `auto_linker` library:

* `class: "auto-linker"` - specify the class to be added to the generated link. false to clear
* `rel: "noopener noreferrer"` - override the rel attribute. false to clear
* `new_window: true` - set to false to remove `target='_blank'` attribute
* `scheme: false` - Set to true to link urls with schema `http://google.com`
* `truncate: false` - Set to a number to truncate urls longer then the number. Truncated urls will end in `..`
* `strip_prefix: true` - Strip the scheme prefix
* `extra: false` - link urls with rarely used schemes (magnet, ipfs, irc, etc.)

Example:

455
```elixir
minibikini's avatar
minibikini committed
456 457 458 459 460 461 462 463 464 465
config :auto_linker,
  opts: [
    scheme: true,
    extra: true,
    class: false,
    strip_prefix: false,
    new_window: false,
    rel: false
  ]
```
466

467 468 469 470 471 472
## Pleroma.ScheduledActivity

* `daily_user_limit`: the number of scheduled activities a user is allowed to create in a single day (Default: `25`)
* `total_user_limit`: the number of scheduled activities a user is allowed to create in total (Default: `300`)
* `enabled`: whether scheduled activities are sent to the job queue to be executed

473 474 475 476 477
## Pleroma.Web.Auth.Authenticator

* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator
* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication

link0ff's avatar
link0ff committed
478 479
## :ldap

link0ff's avatar
link0ff committed
480 481 482 483 484 485
Use LDAP for user authentication.  When a user logs in to the Pleroma
instance, the name and password will be verified by trying to authenticate
(bind) to an LDAP server.  If a user exists in the LDAP directory but there
is no account with the same name yet on the Pleroma instance then a new
Pleroma account will be created with the same name as the LDAP user name.

link0ff's avatar
link0ff committed
486 487 488
* `enabled`: enables LDAP authentication
* `host`: LDAP server hostname
* `port`: LDAP port, e.g. 389 or 636
link0ff's avatar
link0ff committed
489
* `ssl`: true to use SSL, usually implies the port 636
link0ff's avatar
link0ff committed
490
* `sslopts`: additional SSL options
link0ff's avatar
link0ff committed
491 492
* `tls`: true to start TLS, usually implies the port 389
* `tlsopts`: additional TLS options
link0ff's avatar
link0ff committed
493
* `base`: LDAP base, e.g. "dc=example,dc=com"
link0ff's avatar
link0ff committed
494
* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base"
495

lain's avatar
lain committed
496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511
## BBS / SSH access

To enable simple command line interface accessible over ssh, add a setting like this to your configuration file:

```exs
app_dir = File.cwd!
priv_dir = Path.join([app_dir, "priv/ssh_keys"])

config :esshd,
  enabled: true,
  priv_dir: priv_dir,
  handler: "Pleroma.BBS.Handler",
  port: 10_022,
  password_authenticator: "Pleroma.BBS.Authenticator"
```

512
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`
513

514
## :auth
515

516 517 518
* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator
* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication

519
Authentication / authorization settings.
520

521
* `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`.
522
* `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`.
523
* `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>`).
524

Maksim's avatar
Maksim committed
525
## OAuth consumer mode
526 527 528 529 530 531 532 533

OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.).
Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies).

Note: 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.

534
Note: each strategy requires separate setup (on external provider side and Pleroma side). Below are the guidelines on setting up most popular strategies.
535

536 537
Note: 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"`

538 539 540 541 542 543 544 545 546 547 548
* For Twitter, [register an app](https://developer.twitter.com/en/apps), configure callback URL to https://<your_host>/oauth/twitter/callback

* 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/

* For Google, [register an app](https://console.developers.google.com), configure callback URL to https://<your_host>/oauth/google/callback

* For Microsoft, [register an app](https://portal.azure.com), configure callback URL to https://<your_host>/oauth/microsoft/callback

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`,
per strategy's documentation (e.g. [ueberauth_twitter](https://github.com/ueberauth/ueberauth_twitter)). Example config basing on environment variables:

549
```elixir
550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570
# Twitter
config :ueberauth, Ueberauth.Strategy.Twitter.OAuth,
  consumer_key: System.get_env("TWITTER_CONSUMER_KEY"),
  consumer_secret: System.get_env("TWITTER_CONSUMER_SECRET")

# Facebook
config :ueberauth, Ueberauth.Strategy.Facebook.OAuth,
  client_id: System.get_env("FACEBOOK_APP_ID"),
  client_secret: System.get_env("FACEBOOK_APP_SECRET"),
  redirect_uri: System.get_env("FACEBOOK_REDIRECT_URI")

# Google
config :ueberauth, Ueberauth.Strategy.Google.OAuth,
  client_id: System.get_env("GOOGLE_CLIENT_ID"),
  client_secret: System.get_env("GOOGLE_CLIENT_SECRET"),
  redirect_uri: System.get_env("GOOGLE_REDIRECT_URI")

# Microsoft
config :ueberauth, Ueberauth.Strategy.Microsoft.OAuth,
  client_id: System.get_env("MICROSOFT_CLIENT_ID"),
  client_secret: System.get_env("MICROSOFT_CLIENT_SECRET")
571

572 573 574 575
config :ueberauth, Ueberauth,
  providers: [
    microsoft: {Ueberauth.Strategy.Microsoft, [callback_params: []]}
  ]
576

577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593
# Keycloak
# Note: make sure to add `keycloak:ueberauth_keycloak_strategy` entry to `OAUTH_CONSUMER_STRATEGIES` environment variable
keycloak_url = "https://publicly-reachable-keycloak-instance.org:8080"

config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth,
  client_id: System.get_env("KEYCLOAK_CLIENT_ID"),
  client_secret: System.get_env("KEYCLOAK_CLIENT_SECRET"),
  site: keycloak_url,
  authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth",
  token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token",
  userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo",
  token_method: :post

config :ueberauth, Ueberauth,
  providers: [
    keycloak: {Ueberauth.Strategy.Keycloak, [uid_field: :email]}
  ]
594
```
ilja's avatar
ilja committed
595

Maksim's avatar
Maksim committed
596 597 598 599 600 601
## OAuth 2.0 provider - :oauth2

Configure OAuth 2 provider capabilities:

* `token_expires_in` - The lifetime in seconds of the access token.
* `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token.
602 603
* `clean_expired_tokens` - Enable a background job to clean expired oauth tokens. Defaults to `false`.
* `clean_expired_tokens_interval` - Interval to run the job to clean expired tokens. Defaults to `86_400_000` (24 hours).
Maksim's avatar
Maksim committed
604

ilja's avatar
ilja committed
605 606 607 608
## :emoji
* `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]`
* `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"]]`
* `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).
609 610 611 612 613 614 615 616 617 618 619 620 621 622 623

## Database options

### RUM indexing for full text search
* `rum_enabled`: If RUM indexes should be used. Defaults to `false`.

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.

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.

To enable them, both the `rum_enabled` flag has to be set and the following special migration has to be run:

`mix ecto.migrate --migrations-path priv/repo/optional_migrations/rum_indexing/`

This will probably take a long time.
minibikini's avatar
minibikini committed
624 625 626 627 628 629 630 631 632 633 634

## :rate_limit

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:

* The first element: `scale` (Integer). The time scale in milliseconds.
* The second element: `limit` (Integer). How many requests to limit in the time scale provided.

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.

See [`Pleroma.Plugs.RateLimiter`](Pleroma.Plugs.RateLimiter.html) documentation for examples.