diff options
Diffstat (limited to 'docs')
89 files changed, 774 insertions, 1736 deletions
diff --git a/docs/administration/CLI_tasks/config.md b/docs/administration/CLI_tasks/config.md index fc9f3cb..7c167ec 100755..100644 --- a/docs/administration/CLI_tasks/config.md +++ b/docs/administration/CLI_tasks/config.md @@ -1,4 +1,4 @@ -# Transfering the config to/from the database +# Transferring the config to/from the database {! backend/administration/CLI_tasks/general_cli_task_info.include !} @@ -34,7 +34,7 @@ Options: -- `<path>` - where to save migrated config. E.g. `--path=/tmp`. If file saved into non standart folder, you must manually copy file into directory where Pleroma can read it. For OTP install path will be `PLEROMA_CONFIG_PATH` or `/etc/pleroma`. For installation from source - `config` directory in the pleroma folder. +- `<path>` - where to save migrated config. E.g. `--path=/tmp`. If file saved into non-standard folder, you must manually copy file into directory where Pleroma can read it. For OTP install path will be `PLEROMA_CONFIG_PATH` or `/etc/pleroma`. For installation from source - `config` directory in the pleroma folder. - `<env>` - environment, for which is migrated config. By default is `prod`. - To delete transferred settings from database optional flag `-d` can be used diff --git a/docs/administration/CLI_tasks/database.md b/docs/administration/CLI_tasks/database.md index c53c499..c53c499 100755..100644 --- a/docs/administration/CLI_tasks/database.md +++ b/docs/administration/CLI_tasks/database.md diff --git a/docs/administration/CLI_tasks/digest.md b/docs/administration/CLI_tasks/digest.md index a590581..a590581 100755..100644 --- a/docs/administration/CLI_tasks/digest.md +++ b/docs/administration/CLI_tasks/digest.md diff --git a/docs/administration/CLI_tasks/email.md b/docs/administration/CLI_tasks/email.md index 2bb57be..2bb57be 100755..100644 --- a/docs/administration/CLI_tasks/email.md +++ b/docs/administration/CLI_tasks/email.md diff --git a/docs/administration/CLI_tasks/emoji.md b/docs/administration/CLI_tasks/emoji.md index e3d1b21..e3d1b21 100755..100644 --- a/docs/administration/CLI_tasks/emoji.md +++ b/docs/administration/CLI_tasks/emoji.md diff --git a/docs/administration/CLI_tasks/frontend.md b/docs/administration/CLI_tasks/frontend.md index 4e9d9ee..4e9d9ee 100755..100644 --- a/docs/administration/CLI_tasks/frontend.md +++ b/docs/administration/CLI_tasks/frontend.md diff --git a/docs/administration/CLI_tasks/general_cli_task_info.include b/docs/administration/CLI_tasks/general_cli_task_info.include index a1ff1da..a1ff1da 100755..100644 --- a/docs/administration/CLI_tasks/general_cli_task_info.include +++ b/docs/administration/CLI_tasks/general_cli_task_info.include diff --git a/docs/administration/CLI_tasks/instance.md b/docs/administration/CLI_tasks/instance.md index 88509cf..88509cf 100755..100644 --- a/docs/administration/CLI_tasks/instance.md +++ b/docs/administration/CLI_tasks/instance.md diff --git a/docs/administration/CLI_tasks/oauth_app.md b/docs/administration/CLI_tasks/oauth_app.md index f056849..f056849 100755..100644 --- a/docs/administration/CLI_tasks/oauth_app.md +++ b/docs/administration/CLI_tasks/oauth_app.md diff --git a/docs/administration/CLI_tasks/relay.md b/docs/administration/CLI_tasks/relay.md index bdd7e8b..bdd7e8b 100755..100644 --- a/docs/administration/CLI_tasks/relay.md +++ b/docs/administration/CLI_tasks/relay.md diff --git a/docs/administration/CLI_tasks/robots_txt.md b/docs/administration/CLI_tasks/robots_txt.md index 7eeedf5..7eeedf5 100755..100644 --- a/docs/administration/CLI_tasks/robots_txt.md +++ b/docs/administration/CLI_tasks/robots_txt.md diff --git a/docs/administration/CLI_tasks/uploads.md b/docs/administration/CLI_tasks/uploads.md index 8585ec7..8585ec7 100755..100644 --- a/docs/administration/CLI_tasks/uploads.md +++ b/docs/administration/CLI_tasks/uploads.md diff --git a/docs/administration/CLI_tasks/user.md b/docs/administration/CLI_tasks/user.md index 24fdaea..24fdaea 100755..100644 --- a/docs/administration/CLI_tasks/user.md +++ b/docs/administration/CLI_tasks/user.md diff --git a/docs/administration/backup.md b/docs/administration/backup.md index 5f279ab..93325e7 100755..100644 --- a/docs/administration/backup.md +++ b/docs/administration/backup.md @@ -31,7 +31,7 @@ 1. Optionally you can remove the users of your instance. This will trigger delete requests for their accounts and posts. Note that this is 'best effort' and doesn't mean that all traces of your instance will be gone from the fediverse. * You can do this from the admin-FE where you can select all local users and delete the accounts using the *Moderate multiple users* dropdown. - * You can also list local users and delete them individualy using the CLI tasks for [Managing users](./CLI_tasks/user.md). + * You can also list local users and delete them individually using the CLI tasks for [Managing users](./CLI_tasks/user.md). 2. Stop the Pleroma service `systemctl stop pleroma` 3. Disable pleroma from systemd `systemctl disable pleroma` 4. Remove the files and folders you created during installation (see installation guide). This includes the pleroma, nginx and systemd files and folders. diff --git a/docs/administration/frontends-management.md b/docs/administration/frontends-management.md new file mode 100644 index 0000000..f982c4b --- /dev/null +++ b/docs/administration/frontends-management.md @@ -0,0 +1,71 @@ +# Managing installed frontends + +Pleroma lets you install multiple frontends including multiple versions of same frontend. Right now it's only possible to switch which frontend is the default, but in the future it would be possible for user to select which frontend they prefer to use. + +As of 2.6.0 there are two ways of managing frontends - through PleromaFE's Admin Dashboard (preferred, easier method) or through AdminFE (clunky but also works on versions older than 2.6.0). + +!!! note + Managing frontends through UI requires [in-database configuration](../configuration/howto_database_config.md) to be enabled (default on newer instances but might be off on older ones). + +## How it works + +When installing frontends, it creates a folder in [static directory](../configuration/static_dir.md) that follows this pattern: `/frontends/${front-end name}/${front-end version}/`, puts contents of the built frontend in there. Then when accessing the server backend checks what front-end name and version are set to be default and serves index.html and assets from appropriate path. + +!!! warning + + If you've been putting your frontend build directly into static dir as an antiquated way of serving custom frontend, this system will not work and will still serve the custom index.html you put in there. You can still serve custom frontend builds if you put your build into `/frontends/$name/$version` instead and set the "default frontend" fields appropriately. + +Currently, there is no backup system, i.e. when installing `master` version it _will_ overwrite installed `master` version, for now if you want to keep previous version you should back it up manually, i.e. running `cp -r ./frontends/pleroma-fe/master ./frontends/pleroma-fe/master_old` in your static dir. + +## Managing front-ends through Admin Dashboard + +Open up Admin Dashboard (gauge icon in top bar, same as where link to AdminFE was),__ + +switch to "Front-ends" tab. + +This page is designed to be self-explanatory and easy to use, while avoiding issues and pitfalls of AdminFE, but it's also early in development, everything is subject to change. + +!!! warning + This goes without saying, but if you set default frontend to anything except >2.6.0 version of PleromaFE you'll lose the access to Admin Dashboard and will have to use AdminFE to get it back. See below on how to use AdminFE. + +### Limitations + +Currently the list of available for install frontends is essentially hard-coded in backend's configuration, each providing only one version, with exception for PleromaFE which overrides 'pleroma-fe' to also include `develop` version. There is no way to manually install build with a URL (coming soon) nor add more available frontends to the repository (it's broken). + +There is also no way to tell if there is an update available or not, for now you should watch for [announcements](https://pleroma.social/announcements/) of new PleromaFE stable releases to see if there is new stable version. For `develop` version it's up to you whether you want to follow the development process or just reinstall it periodically hoping for new stuff. + +## Using AdminFE to manage frontends + +Access AdminFE either directly by going to `/pleroma/admin` of your instance or by opening Admin Dashboard and clicking the link at the bottom of the window + + + +Go to Settings -> Frontend. + +### Installing front-ends + +At the very top of the page there's a list of available frontends and button to install custom front-end + +!!! tip + Remember to click "Submit" in bottom right corner to save your changes! + +!!! bug + **Available Frontends** section lets you _install_ frontends but **NOT** update/reinstall them. It's only useful for installing a frontend once. + +Due to aforementioned bug, preferred way of installing frontends in AdminFE is by clicking the "Install another frontend" + +and filling in the fields. Unfortunately AdminFE does not provide the raw data necessary for you to fill those fields, so your best bet is to see what backend returns in browser's devtools or refer to the [source code](https://git.pleroma.social/pleroma/pleroma/-/blob/develop/config/config.exs?ref_type=heads#L742-791). For the most part, only **Name**, **Ref** (i.e. version) and **Build URL** fields are required, although some frontends might also require **Build Directory** to work. + +For pleroma-fe you can use either `master` or `develop` refs, or potentially any ref in GitLab that has artifacts for `build` job, but that's outside scope of this document. + +### Selecting default frontend + +Scroll page waaaaay down, search for "Frontends" section, subtitled "Installed frontends management", change the name and reference of the "Primary" frontend. + + + +!!! danger + If you change "Admin" frontend name/reference you risk losing access to AdminFE as well. + +!!! warning + Don't put anything into the "Available" section as it will break the list of available frontends completely, including the "add another frontend" button. If you accidentally put something in there, click the trashbin icon next to "Available" to reset it and restore the frontends list. diff --git a/docs/administration/updating.md b/docs/administration/updating.md index 00eca36..00eca36 100755..100644 --- a/docs/administration/updating.md +++ b/docs/administration/updating.md diff --git a/docs/assets/admin_dash_location.png b/docs/assets/admin_dash_location.png Binary files differnew file mode 100644 index 0000000..4e1d110 --- /dev/null +++ b/docs/assets/admin_dash_location.png diff --git a/docs/assets/frontends_tab.png b/docs/assets/frontends_tab.png Binary files differnew file mode 100644 index 0000000..f7c66ad --- /dev/null +++ b/docs/assets/frontends_tab.png diff --git a/docs/assets/old_adminfe_link.png b/docs/assets/old_adminfe_link.png Binary files differnew file mode 100644 index 0000000..5ea6a48 --- /dev/null +++ b/docs/assets/old_adminfe_link.png diff --git a/docs/assets/primary_frontend_section.png b/docs/assets/primary_frontend_section.png Binary files differnew file mode 100644 index 0000000..14c3de4 --- /dev/null +++ b/docs/assets/primary_frontend_section.png diff --git a/docs/assets/way_to_install_frontends.png b/docs/assets/way_to_install_frontends.png Binary files differnew file mode 100644 index 0000000..a90ff2b --- /dev/null +++ b/docs/assets/way_to_install_frontends.png diff --git a/docs/clients.md b/docs/clients.md index 31d2d27..ad7eb78 100755..100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -3,12 +3,6 @@ Note: Additional clients may be working but theses are officially supporting Ple Feel free to contact us to be added to this list! ## Desktop -### Roma for Desktop -- Homepage: <https://www.pleroma.com/#desktopApp> -- Source Code: <https://github.com/roma-apps/roma-desktop> -- Platforms: Windows, Mac, Linux -- Features: MastoAPI, Streaming Ready - ### Social - Source Code: <https://gitlab.gnome.org/World/Social> - Contact: [@brainblasted@social.libre.fi](https://social.libre.fi/users/brainblasted) @@ -19,7 +13,14 @@ Feel free to contact us to be added to this list! ### Whalebird - Homepage: <https://whalebird.social/> - Source Code: <https://github.com/h3poteto/whalebird-desktop> -- Contact: [@h3poteto@pleroma.io](https://pleroma.io/users/h3poteto) +- Contact: [@whalebird@pleroma.io](https://pleroma.io/users/whalebird) +- Platforms: Windows, Mac, Linux +- Features: MastoAPI, Streaming Ready + +### Fedistar +- Homepage: <https://fedistar.net> +- Source Code: <https://github.com/h3poteto/fedistar> +- Contact: [@fedistar@pleroma.io](https://pleroma.io/users/fedistar) - Platforms: Windows, Mac, Linux - Features: MastoAPI, Streaming Ready diff --git a/docs/configuration/auth.md b/docs/configuration/auth.md index c80f094..c80f094 100755..100644 --- a/docs/configuration/auth.md +++ b/docs/configuration/auth.md diff --git a/docs/configuration/cheatsheet.md b/docs/configuration/cheatsheet.md index bbdf30a..89a461b 100755..100644 --- a/docs/configuration/cheatsheet.md +++ b/docs/configuration/cheatsheet.md @@ -154,12 +154,15 @@ To add configuration to your config file, you can copy it from the base config. * `Pleroma.Web.ActivityPub.MRF.MentionPolicy`: Drops posts mentioning configurable users. (See [`:mrf_mention`](#mrf_mention)). * `Pleroma.Web.ActivityPub.MRF.VocabularyPolicy`: Restricts activities to a configured set of vocabulary. (See [`:mrf_vocabulary`](#mrf_vocabulary)). * `Pleroma.Web.ActivityPub.MRF.ObjectAgePolicy`: Rejects or delists posts based on their age when received. (See [`:mrf_object_age`](#mrf_object_age)). - * `Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy`: Sets a default expiration on all posts made by users of the local instance. Requires `Pleroma.Workers.PurgeExpiredActivity` to be enabled for processing the scheduled delections. + * `Pleroma.Web.ActivityPub.MRF.ActivityExpirationPolicy`: Sets a default expiration on all posts made by users of the local instance. Requires `Pleroma.Workers.PurgeExpiredActivity` to be enabled for processing the scheduled deletions. * `Pleroma.Web.ActivityPub.MRF.ForceBotUnlistedPolicy`: Makes all bot posts to disappear from public timelines. * `Pleroma.Web.ActivityPub.MRF.FollowBotPolicy`: Automatically follows newly discovered users from the specified bot account. Local accounts, locked accounts, and users with "#nobot" in their bio are respected and excluded from being followed. * `Pleroma.Web.ActivityPub.MRF.AntiFollowbotPolicy`: Drops follow requests from followbots. Users can still allow bots to follow them by first following the bot. * `Pleroma.Web.ActivityPub.MRF.KeywordPolicy`: Rejects or removes from the federated timeline or replaces keywords. (See [`:mrf_keyword`](#mrf_keyword)). * `Pleroma.Web.ActivityPub.MRF.ForceMentionsInContent`: Forces every mentioned user to be reflected in the post content. + * `Pleroma.Web.ActivityPub.MRF.InlineQuotePolicy`: Forces quote post URLs to be reflected in the message content inline. + * `Pleroma.Web.ActivityPub.MRF.QuoteToLinkTagPolicy`: Force a Link tag for posts quoting another post. (may break outgoing federation of quote posts with older Pleroma versions). + * `Pleroma.Web.ActivityPub.MRF.ForceMention`: Forces posts to include a mention of the author of parent post or the author of quoted post. * `transparency`: Make the content of your Message Rewrite Facility settings public (via nodeinfo). * `transparency_exclusions`: Exclude specific instance names from MRF transparency. The use of the exclusions feature will be disclosed in nodeinfo as a boolean value. @@ -261,6 +264,18 @@ Notes: * `follower_nickname`: The name of the bot account to use for following newly discovered users. Using `followbot` or similar is strongly suggested. +#### :mrf_emoji +* `remove_url`: A list of patterns which result in emoji whose URL matches being removed from the message. This will apply to statuses, emoji reactions, and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `remove_shortcode`: A list of patterns which result in emoji whose shortcode matches being removed from the message. This will apply to statuses, emoji reactions, and user profiles. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `federated_timeline_removal_url`: A list of patterns which result in message with emojis whose URLs match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). +* `federated_timeline_removal_shortcode`: A list of patterns which result in message with emojis whose shortcodes match being removed from federated timelines (a.k.a unlisted). This will apply only to statuses. Each pattern can be a string or a [regular expression](https://hexdocs.pm/elixir/Regex.html). + +#### :mrf_inline_quote +* `template`: The template to append to the post. `{url}` will be replaced with the actual link to the quoted post. Default: `<bdi>RT:</bdi> {url}` + +#### :mrf_force_mention +* `mention_parent`: Whether to append mention of parent post author +* `mention_quoted`: Whether to append mention of parent quoted author ### :activitypub * `unfollow_blocked`: Whether blocks result in people getting unfollowed @@ -496,7 +511,7 @@ config :pleroma, :rate_limit, Means that: 1. In 60 seconds, 15 authentication attempts can be performed from the same IP address. -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. +2. In 1 second, 10 search requests can be performed from the same IP address by unauthenticated users, while authenticated users can perform 30 search requests per second. Supported rate limiters: @@ -671,6 +686,12 @@ This filter reads the ImageDescription and iptc:Caption-Abstract fields with Exi No specific configuration. +#### Pleroma.Upload.Filter.OnlyMedia + +This filter rejects uploads that are not identified with Content-Type matching audio/\*, image/\*, or video/\* + +No specific configuration. + #### Pleroma.Upload.Filter.Mogrify * `args`: List of actions for the `mogrify` command like `"strip"` or `["strip", "auto-orient", {"implode", "1"}]`. @@ -873,21 +894,8 @@ This will probably take a long time. ### 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" -``` - -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` +This feature has been removed from Pleroma core. +However, a client has been made and is available at https://git.pleroma.social/Duponin/sshocial. ### :gopher * `enabled`: Enables the gopher interface @@ -1078,7 +1086,7 @@ config :pleroma, Pleroma.Formatter, ## :configurable_from_database -Boolean, enables/disables in-database configuration. Read [Transfering the config to/from the database](../administration/CLI_tasks/config.md) for more information. +Boolean, enables/disables in-database configuration. Read [Transferring the config to/from the database](../administration/CLI_tasks/config.md) for more information. ## :database_config_whitelist @@ -1139,7 +1147,7 @@ Control favicons for instances. !!! note Requires enabled email -* `:purge_after_days` an integer, remove backup achives after N days. +* `:purge_after_days` an integer, remove backup achieves after N days. * `:limit_days` an integer, limit user to export not more often than once per N days. * `:dir` a string with a path to backup temporary directory or `nil` to let Pleroma choose temporary directory in the following order: 1. the directory named by the TMPDIR environment variable diff --git a/docs/configuration/custom_emoji.md b/docs/configuration/custom_emoji.md index 1648840..19250cf 100755..100644 --- a/docs/configuration/custom_emoji.md +++ b/docs/configuration/custom_emoji.md @@ -29,7 +29,7 @@ foo, /emoji/custom/foo.png The files should be PNG (APNG is okay with `.png` for `image/png` Content-type) and under 50kb for compatibility with mastodon. -Default file extentions and locations for emojis are set in `config.exs`. To use different locations or file-extentions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extentions: +Default file extensions and locations for emojis are set in `config.exs`. To use different locations or file-extensions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extensions: ```elixir config :pleroma, :emoji, shortcode_globs: ["/emoji/custom/**/*.png", "/emoji/custom/**/*.gif"] ``` diff --git a/docs/configuration/hardening.md b/docs/configuration/hardening.md index d3bfc4e..cc46d1f 100755..100644 --- a/docs/configuration/hardening.md +++ b/docs/configuration/hardening.md @@ -62,6 +62,20 @@ An additional “Expect-CT” header will be sent with the configured `ct_max_ag If you click on a link, your browser’s request to the other site will include from where it is coming from. The “Referrer policy” header tells the browser how and if it should send this information. (see [Referrer policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy)) +### Uploaded media and media proxy + +It is STRONGLY RECOMMENDED to serve both the locally-uploaded media and the media proxy from another domain than the domain that Pleroma runs on, if applicable. + +```elixir +config :pleroma, :media_proxy, + base_url: "https://some.other.domain" + +config :pleroma, Pleroma.Upload, + base_url: "https://some.other.domain/media" +``` + +See `installation/pleroma-mediaproxy.nginx` for examples on how to configure your media proxy. + ## systemd A systemd unit example is provided at `installation/pleroma.service`. diff --git a/docs/configuration/how_to_serve_another_domain_for_webfinger.md b/docs/configuration/how_to_serve_another_domain_for_webfinger.md index 5ae3e79..5ae3e79 100755..100644 --- a/docs/configuration/how_to_serve_another_domain_for_webfinger.md +++ b/docs/configuration/how_to_serve_another_domain_for_webfinger.md diff --git a/docs/configuration/howto_database_config.md b/docs/configuration/howto_database_config.md index e5af909..e5af909 100755..100644 --- a/docs/configuration/howto_database_config.md +++ b/docs/configuration/howto_database_config.md diff --git a/docs/configuration/howto_ejabberd.md b/docs/configuration/howto_ejabberd.md index 520a0ac..520a0ac 100755..100644 --- a/docs/configuration/howto_ejabberd.md +++ b/docs/configuration/howto_ejabberd.md diff --git a/docs/configuration/howto_mediaproxy.md b/docs/configuration/howto_mediaproxy.md index 16c40c5..16c40c5 100755..100644 --- a/docs/configuration/howto_mediaproxy.md +++ b/docs/configuration/howto_mediaproxy.md diff --git a/docs/configuration/howto_mongooseim.md b/docs/configuration/howto_mongooseim.md index a33e590..a33e590 100755..100644 --- a/docs/configuration/howto_mongooseim.md +++ b/docs/configuration/howto_mongooseim.md diff --git a/docs/configuration/howto_proxy.md b/docs/configuration/howto_proxy.md index 10a6352..10a6352 100755..100644 --- a/docs/configuration/howto_proxy.md +++ b/docs/configuration/howto_proxy.md diff --git a/docs/configuration/howto_search_cjk.md b/docs/configuration/howto_search_cjk.md index a73b10d..a73b10d 100755..100644 --- a/docs/configuration/howto_search_cjk.md +++ b/docs/configuration/howto_search_cjk.md diff --git a/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md b/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md index bfee5a9..bfee5a9 100755..100644 --- a/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md +++ b/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md diff --git a/docs/configuration/howto_theming_your_instance.md b/docs/configuration/howto_theming_your_instance.md index cfa00f5..cfa00f5 100755..100644 --- a/docs/configuration/howto_theming_your_instance.md +++ b/docs/configuration/howto_theming_your_instance.md diff --git a/docs/configuration/i2p.md b/docs/configuration/i2p.md index 8c5207d..17dd9b0 100755..100644 --- a/docs/configuration/i2p.md +++ b/docs/configuration/i2p.md @@ -1,4 +1,4 @@ -# I2P Federation and Accessability +# I2P Federation and Accessibility This guide is going to focus on the Pleroma federation aspect. The actual installation is neatly explained in the official documentation, and more likely to remain up-to-date. It might be added to this guide if there will be a need for that. diff --git a/docs/configuration/mrf.md b/docs/configuration/mrf.md index a31c26b..a31c26b 100755..100644 --- a/docs/configuration/mrf.md +++ b/docs/configuration/mrf.md diff --git a/docs/configuration/onion_federation.md b/docs/configuration/onion_federation.md index 3767321..8a81372 100755..100644 --- a/docs/configuration/onion_federation.md +++ b/docs/configuration/onion_federation.md @@ -29,7 +29,7 @@ HiddenServiceDir /var/lib/tor/pleroma_hidden_service/ HiddenServicePort 80 127.0.0.1:8099 HiddenServiceVersion 3 # Remove if Tor version is below 0.3 ( tor --version ) ``` -Restart Tor to generate an adress: +Restart Tor to generate an address: ``` systemctl restart tor@default.service ``` diff --git a/docs/configuration/optimizing_beam.md b/docs/configuration/optimizing_beam.md index e336bd3..5e81cd0 100755..100644 --- a/docs/configuration/optimizing_beam.md +++ b/docs/configuration/optimizing_beam.md @@ -1,6 +1,6 @@ # Optimizing the BEAM -Pleroma is built upon the Erlang/OTP VM known as BEAM. The BEAM VM is highly optimized for latency, but this has drawbacks in environments without dedicated hardware. One of the tricks used by the BEAM VM is [busy waiting](https://en.wikipedia.org/wiki/Busy_waiting). This allows the application to pretend to be busy working so the OS kernel does not pause the application process and switch to another process waiting for the CPU to execute its workload. It does this by spinning for a period of time which inflates the apparent CPU usage of the application so it is immediately ready to execute another task. This can be observed with utilities like **top(1)** which will show consistently high CPU usage for the process. Switching between procesess is a rather expensive operation and also clears CPU caches further affecting latency and performance. The goal of busy waiting is to avoid this penalty. +Pleroma is built upon the Erlang/OTP VM known as BEAM. The BEAM VM is highly optimized for latency, but this has drawbacks in environments without dedicated hardware. One of the tricks used by the BEAM VM is [busy waiting](https://en.wikipedia.org/wiki/Busy_waiting). This allows the application to pretend to be busy working so the OS kernel does not pause the application process and switch to another process waiting for the CPU to execute its workload. It does this by spinning for a period of time which inflates the apparent CPU usage of the application so it is immediately ready to execute another task. This can be observed with utilities like **top(1)** which will show consistently high CPU usage for the process. Switching between processes is a rather expensive operation and also clears CPU caches further affecting latency and performance. The goal of busy waiting is to avoid this penalty. This strategy is very successful in making a performant and responsive application, but is not desirable on Virtual Machines or hardware with few CPU cores. Pleroma instances are often deployed on the same server as the required PostgreSQL database which can lead to situations where the Pleroma application is holding the CPU in a busy-wait loop and as a result the database cannot process requests in a timely manner. The fewer CPUs available, the more this problem is exacerbated. The latency is further amplified by the OS being installed on a Virtual Machine as the Hypervisor uses CPU time-slicing to pause the entire OS and switch between other tasks. diff --git a/docs/configuration/postgresql.md b/docs/configuration/postgresql.md index e251eb8..56f1c60 100755..100644 --- a/docs/configuration/postgresql.md +++ b/docs/configuration/postgresql.md @@ -22,7 +22,7 @@ config :pleroma, Pleroma.Repo, ] ``` -A more detailed explaination of the issue can be found at <https://blog.soykaf.com/post/postgresql-elixir-troubles/>. +A more detailed explanation of the issue can be found at <https://blog.soykaf.com/post/postgresql-elixir-troubles/>. ## Example configurations diff --git a/docs/configuration/search.md b/docs/configuration/search.md new file mode 100644 index 0000000..0316c9b --- /dev/null +++ b/docs/configuration/search.md @@ -0,0 +1,123 @@ +# Configuring search + +{! backend/administration/CLI_tasks/general_cli_task_info.include !} + +## Built-in search + +To use built-in search that has no external dependencies, set the search module to `Pleroma.Activity`: + +> config :pleroma, Pleroma.Search, module: Pleroma.Search.DatabaseSearch + +While it has no external dependencies, it has problems with performance and relevancy. + +## Meilisearch + +Note that it's quite a bit more memory hungry than PostgreSQL (around 4-5G for ~1.2 million +posts while idle and up to 7G while indexing initially). The disk usage for this additional index is also +around 4 gigabytes. Like [RUM](./cheatsheet.md#rum-indexing-for-full-text-search) indexes, it offers considerably +higher performance and ordering by timestamp in a reasonable amount of time. +Additionally, the search results seem to be more accurate. + +Due to high memory usage, it may be best to set it up on a different machine, if running pleroma on a low-resource +computer, and use private key authentication to secure the remote search instance. + +To use [meilisearch](https://www.meilisearch.com/), set the search module to `Pleroma.Search.Meilisearch`: + +> config :pleroma, Pleroma.Search, module: Pleroma.Search.Meilisearch + +You then need to set the address of the meilisearch instance, and optionally the private key for authentication. You might +also want to change the `initial_indexing_chunk_size` to be smaller if you're server is not very powerful, but not higher than `100_000`, +because meilisearch will refuse to process it if it's too big. However, in general you want this to be as big as possible, because meilisearch +indexes faster when it can process many posts in a single batch. + +> config :pleroma, Pleroma.Search.Meilisearch, +> url: "http://127.0.0.1:7700/", +> private_key: "private key", +> initial_indexing_chunk_size: 100_000 + +Information about setting up meilisearch can be found in the +[official documentation](https://docs.meilisearch.com/learn/getting_started/installation.html). +You probably want to start it with `MEILI_NO_ANALYTICS=true` environment variable to disable analytics. +At least version 0.25.0 is required, but you are strongly advised to use at least 0.26.0, as it introduces +the `--enable-auto-batching` option which drastically improves performance. Without this option, the search +is hardly usable on a somewhat big instance. + +### Private key authentication (optional) + +To set the private key, use the `MEILI_MASTER_KEY` environment variable when starting. After setting the _master key_, +you have to get the _private key_, which is actually used for authentication. + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch show-keys <your master key here> + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch show-keys <your master key here> + ``` + +You will see a "Default Admin API Key", this is the key you actually put into your configuration file. + +### Initial indexing + +After setting up the configuration, you'll want to index all of your already existing posts. Only public posts are indexed. You'll only +have to do it one time, but it might take a while, depending on the amount of posts your instance has seen. This is also a fairly RAM +consuming process for `meilisearch`, and it will take a lot of RAM when running if you have a lot of posts (seems to be around 5G for ~1.2 +million posts while idle and up to 7G while indexing initially, but your experience may be different). + +The sequence of actions is as follows: + +1. First, change the configuration to use `Pleroma.Search.Meilisearch` as the search backend +2. Restart your instance, at this point it can be used while the search indexing is running, though search won't return anything +3. Start the initial indexing process (as described below with `index`), + and wait until the task says it sent everything from the database to index +4. Wait until everything is actually indexed (by checking with `stats` as described below), + at this point you don't have to do anything, just wait a while. + +To start the initial indexing, run the `index` command: + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch index + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch index + ``` + +This will show you the total amount of posts to index, and then show you the amount of posts indexed currently, until the numbers eventually +become the same. The posts are indexed in big batches and meilisearch will take some time to actually index them, even after you have +inserted all the posts into it. Depending on the amount of posts, this may be as long as several hours. To get information about the status +of indexing and how many posts have actually been indexed, use the `stats` command: + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch stats + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch stats + ``` + +### Clearing the index + +In case you need to clear the index (for example, to re-index from scratch, if that needs to happen for some reason), you can +use the `clear` command: + +=== "OTP" + ```sh + ./bin/pleroma_ctl search.meilisearch clear + ``` + +=== "From Source" + ```sh + mix pleroma.search.meilisearch clear + ``` + +This will clear **all** the posts from the search index. Note, that deleted posts are also removed from index by the instance itself, so +there is no need to actually clear the whole index, unless you want **all** of it gone. That said, the index does not hold any information +that cannot be re-created from the database, it should also generally be a lot smaller than the size of your database. Still, the size +depends on the amount of text in posts. diff --git a/docs/configuration/static_dir.md b/docs/configuration/static_dir.md index a294bb6..a294bb6 100755..100644 --- a/docs/configuration/static_dir.md +++ b/docs/configuration/static_dir.md diff --git a/docs/configuration/storing_remote_media.md b/docs/configuration/storing_remote_media.md index c01985d..c01985d 100755..100644 --- a/docs/configuration/storing_remote_media.md +++ b/docs/configuration/storing_remote_media.md diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index f6e9f7d..182a760 100755..100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -303,7 +303,7 @@ Removes the user(s) from follower recommendations. ## `GET /api/v1/pleroma/admin/users/:nickname_or_id` -### Retrive the details of a user +### Retrieve the details of a user - Params: - `nickname` or `id` @@ -313,7 +313,7 @@ Removes the user(s) from follower recommendations. ## `GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses` -### Retrive user's latest statuses +### Retrieve user's latest statuses - Params: - `nickname` or `id` @@ -337,7 +337,7 @@ Removes the user(s) from follower recommendations. ## `GET /api/v1/pleroma/admin/instances/:instance/statuses` -### Retrive instance's latest statuses +### Retrieve instance's latest statuses - Params: - `instance`: instance name @@ -377,7 +377,7 @@ It may take some time. ## `GET /api/v1/pleroma/admin/statuses` -### Retrives all latest statuses +### Retrieves all latest statuses - Params: - *optional* `page_size`: number of statuses to return (default is `20`) @@ -541,7 +541,7 @@ Response: ## `PATCH /api/v1/pleroma/admin/users/force_password_reset` -### Force passord reset for a user with a given nickname +### Force password reset for a user with a given nickname - Params: - `nicknames` @@ -1585,6 +1585,7 @@ Returns the content of the document "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build", "git": "https://git.pleroma.social/pleroma/fedi-fe", "installed": true, + "installed_refs": ["master"], "name": "fedi-fe", "ref": "master" }, @@ -1592,6 +1593,7 @@ Returns the content of the document "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build", "git": "https://git.pleroma.social/lambadalambda/kenoma", "installed": false, + "installed_refs": [], "name": "kenoma", "ref": "master" } diff --git a/docs/development/API/chats.md b/docs/development/API/chats.md index f50144c..f50144c 100755..100644 --- a/docs/development/API/chats.md +++ b/docs/development/API/chats.md diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 4007c63..e3b6a3c 100755..100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -1,6 +1,6 @@ # Differences in Mastodon API responses from vanilla Mastodon -A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance` +A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance` and `/api/v2/instance` ## Flake IDs @@ -39,6 +39,9 @@ Has these additional fields under the `pleroma` object: - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. +- `quotes_count`: the count of status quotes. +- `non_anonymous`: true if the source post specifies the poll results are not anonymous. Currently only implemented by Smithereen. +- `bookmark_folder`: the ID of the folder bookmark is stored within (if any). The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: @@ -64,6 +67,12 @@ Some apps operate under the assumption that no more than 4 attachments can be re Pleroma does not process remote images and therefore cannot include fields such as `meta` and `blurhash`. It does not support focal points or aspect ratios. The frontend is expected to handle it. +## Bookmarks + +The `GET /api/v1/bookmarks` endpoint accepts optional parameter `folder_id` for bookmark folder ID. + +The `POST /api/v1/statuses/:id/bookmark` endpoint accepts optional parameter `folder_id` for bookmark folder ID. + ## Accounts The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. @@ -304,19 +313,27 @@ Has these additional parameters (which are the same as in Pleroma-API): `GET /api/v1/instance` has additional fields - `max_toot_chars`: The maximum characters per post +- `max_media_attachments`: Maximum number of post media attachments - `chat_limit`: The maximum characters per chat message - `description_limit`: The maximum characters per image description - `poll_limits`: The limits of polls +- `shout_limit`: The maximum characters per Shoutbox message - `upload_limit`: The maximum upload file size - `avatar_upload_limit`: The same for avatars - `background_upload_limit`: The same for backgrounds - `banner_upload_limit`: The same for banners - `background_image`: A background image that frontends can use +- `pleroma.metadata.account_activation_required`: Whether users are required to confirm their emails before signing in +- `pleroma.metadata.birthday_required`: Whether users are required to provide their birth day when signing in +- `pleroma.metadata.birthday_min_age`: The minimum user age (in days) - `pleroma.metadata.features`: A list of supported features - `pleroma.metadata.federation`: The federation restrictions of this instance - `pleroma.metadata.fields_limits`: A list of values detailing the length and count limitation for various instance-configurable fields. - `pleroma.metadata.post_formats`: A list of the allowed post format types -- `vapid_public_key`: The public key needed for push messages +- `pleroma.stats.mau`: Monthly active user count +- `pleroma.vapid_public_key`: The public key needed for push messages + +In, `GET /api/v2/instance` Pleroma-specific fields are all moved into `pleroma` object. `max_toot_chars`, `poll_limits` and `upload_limit` are replaced with their MastoAPI counterparts. ## Push Subscription @@ -357,6 +374,122 @@ The message payload consist of: - `follower_count`: follower count - `following_count`: following count +### Authenticating via `sec-websocket-protocol` header + +Pleroma allows to authenticate via the `sec-websocket-protocol` header, for example, if your access token is `your-access-token`, you can authenticate using the following: + +``` +sec-websocket-protocol: your-access-token +``` + +### Authenticating after connection via `pleroma:authenticate` event + +Pleroma allows to authenticate after connection is established, via the `pleroma:authenticate` event. For example, if your access token is `your-access-token`, you can send the following after the connection is established: + +``` +{"type": "pleroma:authenticate", "token": "your-access-token"} +``` + +### Response to client-sent events + +Pleroma will respond to client-sent events that it recognizes. Supported event types are: + +- `subscribe` +- `unsubscribe` +- `pleroma:authenticate` + +The reply will be in the following format: + +``` +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"<type of the client-sent event>\", \"result\": \"<result of the action>\", \"error\": \"<error code>\"}" +} +``` + +Result of the action can be either `success`, `ignored` or `error`. If it is `error`, the `error` property will contain the error code. Otherwise, the `error` property will not be present. Below are some examples: + +``` +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"pleroma:authenticate\", \"result\": \"success\"}" +} + +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"subscribe\", \"result\": \"ignored\"}" +} + +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"unsubscribe\", \"result\": \"error\", \"error\": \"bad_topic\"}" +} +``` + +If the sent event is not of a type that Pleroma supports, it will not reply. + +### The `stream` attribute of a server-sent event + +Technically, this is in Mastodon, but its documentation does nothing to specify its format. + +This attribute appears on every event type except `pleroma:respond` and `delete`. It helps clients determine where they should display the new statuses. + +The value of the attribute is an array containing one or two elements. The first element is the type of the stream. The second is the identifier related to that specific stream, if applicable. + +For the following stream types, there is a second element in the array: + +- `list`: The second element is the id of the list, as a string. +- `hashtag`: The second element is the name of the hashtag. +- `public:remote:media` and `public:remote`: The second element is the domain of the corresponding instance. + +For all other stream types, there is no second element. + +Some examples of valid `stream` values: + +- `["list", "1"]`: List of id 1. +- `["hashtag", "mew"]`: The hashtag #mew. +- `["user:notifications"]`: Notifications for the current user. +- `["user"]`: Home timeline. +- `["public:remote", "mew.moe"]`: Public posts from the instance mew.moe . + +### The unified streaming endpoint + +If you do not specify a stream to connect to when requesting `/api/v1/streaming`, you will enter a connection that subscribes to no streams. After the connection is established, you can authenticate and then subscribe to different streams. + +### List of supported streams + +Below is a list of supported streams by Pleroma. To make a single-stream WebSocket connection, append the string specified in "Query style" to the streaming endpoint url. +To subscribe to a stream after the connection is established, merge the JSON object specified in "Subscribe style" with `{"type": "subscribe"}`. To unsubscribe, merge it with `{"type": "unsubscribe"}`. + +For example, to receive updates on the list 1, you can connect to `/api/v1/streaming/?stream=list&list=1`, or send + +``` +{"type": "subscribe", "stream": "list", "list": "1"} +``` + +upon establishing the websocket connection. + +To unsubscribe to list 1, send + +``` +{"type": "unsubscribe", "stream": "list", "list": "1"} +``` + +Note that if you specify a stream that requires a logged-in user in the query string (for example, `user` or `list`), you have to specify the access token when you are trying to establish the connection, i.e. in the query string or via the `sec-websocket-protocol` header. + +- `list` + - Query style: `?stream=list&list=<id>` + - Subscribe style: `{"stream": "list", "list": "<id>"}` +- `public`, `public:local`, `public:media`, `public:local:media`, `user`, `user:pleroma_chat`, `user:notifications`, `direct` + - Query style: `?stream=<stream name>` + - Subscribe style: `{"stream": "<stream name>"}` +- `hashtag` + - Query style: `?stream=hashtag&tag=<name>` + - Subscribe style: `{"stream": "hashtag", "tag": "<name>"}` +- `public:remote`, `public:remote:media` + - Query style: `?stream=<stream name>&instance=<instance domain>` + - Subscribe style: `{"stream": "<stream name>", "instance": "<instance domain>"}` + ## User muting and thread muting Both user muting and thread muting can be done for only a certain time by adding an `expires_in` parameter to the API calls and giving the expiration time in seconds. diff --git a/docs/development/API/nodeinfo.md b/docs/development/API/nodeinfo.md index 0f998a1..0f998a1 100755..100644 --- a/docs/development/API/nodeinfo.md +++ b/docs/development/API/nodeinfo.md diff --git a/docs/development/API/pleroma_api.md b/docs/development/API/pleroma_api.md index 47fcb74..267dfc1 100755..100644 --- a/docs/development/API/pleroma_api.md +++ b/docs/development/API/pleroma_api.md @@ -129,7 +129,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap * method: `GET` * Authentication: required * OAuth scope: `write:security` -* Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}` +* Response: JSON. Returns `{"codes": codes}` when successful, otherwise HTTP 422 `{"error": "[error message]"}` ## `/api/v1/pleroma/admin/` See [Admin-API](admin_api.md) @@ -251,6 +251,15 @@ See [Admin-API](admin_api.md) ] ``` + +## `/api/v1/pleroma/accounts/:id/endorsements` +### Returns users endorsed by a user +* Method `GET` +* Authentication: not required +* Params: + * `id`: the id of the account for whom to return results +* Response: JSON, returns a list of Mastodon Account entities + ## `/api/v1/pleroma/accounts/update_*` ### Set and clear account avatar, banner, and background @@ -266,6 +275,60 @@ See [Admin-API](admin_api.md) * Authentication: not required * Response: 204 No Content +## `/api/v1/pleroma/statuses/:id/quotes` +### Gets quotes for a given status +* Method `GET` +* Authentication: not required +* Params: + * `id`: the id of the status +* Response: JSON, returns a list of Mastodon Status entities + +## `GET /api/v1/pleroma/bookmark_folders` +### Gets user bookmark folders +* Authentication: required + +* Response: JSON. Returns a list of bookmark folders. +* Example response: +```json +[ + { + "id": "9umDrYheeY451cQnEe", + "name": "Read later", + "emoji": "🕓", + "source": { + "emoji": "🕓" + } + } +] +``` + +## `POST /api/v1/pleroma/bookmark_folders` +### Creates a bookmark folder +* Authentication: required + +* Params: + * `name`: folder name + * `emoji`: folder emoji (optional) +* Response: JSON. Returns a single bookmark folder. + +## `PATCH /api/v1/pleroma/bookmark_folders/:id` +### Updates a bookmark folder +* Authentication: required + +* Params: + * `id`: folder id + * `name`: folder name (optional) + * `emoji`: folder emoji (optional) +* Response: JSON. Returns a single bookmark folder. + +## `DELETE /api/v1/pleroma/bookmark_folders/:id` +### Deletes a bookmark folder +* Authentication: required + +* Params: + * `id`: folder id +* Response: JSON. Returns a single bookmark folder. + ## `/api/v1/pleroma/mascot` ### Gets user mascot image * Method `GET` @@ -372,6 +435,15 @@ See [Admin-API](admin_api.md) * `alias`: the nickname of the alias to delete, e.g. `foo@example.org`. * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise +## `/api/v1/pleroma/remote_interaction` +## Interact with profile or status from remote account +* Metod `POST` +* Authentication: not required +* Params: + * `ap_id`: Profile or status ActivityPub ID + * `profile`: Remote profile webfinger +* Response: JSON. Returns `{"url": "[redirect url]"}` on success, `{"error": "[error message]"}` otherwise + # Pleroma Conversations Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints: @@ -382,7 +454,7 @@ Pleroma Conversations have the same general structure that Mastodon Conversation Conversations have the additional field `recipients` under the `pleroma` key. This holds a list of all the accounts that will receive a message in this conversation. -The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation. +The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visibility to direct and address only the people who are the recipients of that Conversation. ⚠ Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`. @@ -577,6 +649,9 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa 404 if the pack does not exist ## `GET /api/v1/pleroma/accounts/:id/scrobbles` + +Audio scrobbling in Pleroma is **deprecated**. + ### Requests a list of current and recent Listen activities for an account * Method `GET` * Authentication: not required @@ -598,6 +673,9 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa ``` ## `POST /api/v1/pleroma/scrobble` + +Audio scrobbling in Pleroma is **deprecated**. + ### Creates a new Listen activity for an account * Method `POST` * Authentication: required diff --git a/docs/development/API/prometheus.md b/docs/development/API/prometheus.md index a5158d9..a5158d9 100755..100644 --- a/docs/development/API/prometheus.md +++ b/docs/development/API/prometheus.md diff --git a/docs/development/ap_extensions.md b/docs/development/ap_extensions.md index 3d1caeb..75c8a7b 100755..100644 --- a/docs/development/ap_extensions.md +++ b/docs/development/ap_extensions.md @@ -20,16 +20,16 @@ Content-Type: multipart/form-data Parameters: - (required) `file`: The file being uploaded -- (optionnal) `description`: A plain-text description of the media, for accessibility purposes. +- (optional) `description`: A plain-text description of the media, for accessibility purposes. Response: HTTP 201 Created with the object into the body, no `Location` header provided as it doesn't have an `id` -The object given in the reponse should then be inserted into an Object's `attachment` field. +The object given in the response should then be inserted into an Object's `attachment` field. ## ChatMessages `ChatMessage`s are the messages sent in 1-on-1 chats. They are similar to -`Note`s, but the addresing is done by having a single AP actor in the `to` +`Note`s, but the addressing is done by having a single AP actor in the `to` field. Addressing multiple actors is not allowed. These messages are always private, there is no public version of them. They are created with a `Create` activity. diff --git a/docs/development/authentication_authorization.md b/docs/development/authentication_authorization.md index 183bfc2..183bfc2 100755..100644 --- a/docs/development/authentication_authorization.md +++ b/docs/development/authentication_authorization.md diff --git a/docs/development/index.md b/docs/development/index.md index 01a6175..01a6175 100755..100644 --- a/docs/development/index.md +++ b/docs/development/index.md diff --git a/docs/development/setting_up_a_gitlab_runner.md b/docs/development/setting_up_a_gitlab_runner.md index 88beb82..88beb82 100755..100644 --- a/docs/development/setting_up_a_gitlab_runner.md +++ b/docs/development/setting_up_a_gitlab_runner.md diff --git a/docs/development/setting_up_pleroma_dev.md b/docs/development/setting_up_pleroma_dev.md index 8da761d..24f358e 100755..100644 --- a/docs/development/setting_up_pleroma_dev.md +++ b/docs/development/setting_up_pleroma_dev.md @@ -15,7 +15,7 @@ Pleroma requires some adjustments from the defaults for running the instance loc 2. Change the dev.secret.exs * Change the scheme in `config :pleroma, Pleroma.Web.Endpoint` to http (see examples below) * If you want to change other settings, you can do that too -3. You can now start the server `mix phx.server`. Once it's build and started, you can access the instance on `http://<host>:<port>` (e.g.http://localhost:4000 ) and should be able to do everything locally you normaly can. +3. You can now start the server `mix phx.server`. Once it's build and started, you can access the instance on `http://<host>:<port>` (e.g.http://localhost:4000 ) and should be able to do everything locally you normally can. Example config to change the scheme to http. Change the port if you want to run on another port. ```elixir @@ -38,7 +38,7 @@ config :logger, :console, ## Testing -1. Create a `test.secret.exs` file with the content as shown below +1. Create a `config/test.secret.exs` file with the content as shown below 2. Create the database user and test database. 1. You can use the `config/setup_db.psql` as a template. Copy the file if you want and change the database name, user and password to the values for the test-database (e.g. 'pleroma_local_test' for database and user). Then run this file like you did during installation. 2. The tests will try to create the Database, so we'll have to allow our test-database user to create databases, `sudo -Hu postgres psql -c "ALTER USER pleroma_local_test WITH CREATEDB;"` diff --git a/docs/index.md b/docs/index.md index 3799a00..3799a00 100755..100644 --- a/docs/index.md +++ b/docs/index.md diff --git a/docs/installation/alpine_linux_en.md b/docs/installation/alpine_linux_en.md index c37ff0c..7154bca 100755..100644 --- a/docs/installation/alpine_linux_en.md +++ b/docs/installation/alpine_linux_en.md @@ -183,6 +183,9 @@ server { ... } ``` +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. * Enable and start nginx: diff --git a/docs/installation/arch_linux_en.md b/docs/installation/arch_linux_en.md index 285743d..f7d722e 100755..100644 --- a/docs/installation/arch_linux_en.md +++ b/docs/installation/arch_linux_en.md @@ -173,6 +173,11 @@ sudo ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/ple ``` * Before starting nginx edit the configuration and change it to your needs (e.g. change servername, change cert paths) + +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + * Enable and start nginx: ```shell diff --git a/docs/installation/debian_based_en.md b/docs/installation/debian_based_en.md index 4e52b21..b61e4ad 100755..100644 --- a/docs/installation/debian_based_en.md +++ b/docs/installation/debian_based_en.md @@ -4,7 +4,7 @@ ## Installation -This guide will assume you are on Debian 11 (“bullseye”) or later. This guide should also work with Ubuntu 18.04 (“Bionic Beaver”) and later. It also assumes that you have administrative rights, either as root or a user with [sudo permissions](https://www.digitalocean.com/community/tutorials/how-to-add-delete-and-grant-sudo-privileges-to-users-on-a-debian-vps). If you want to run this guide with root, ignore the `sudo` at the beginning of the lines, unless it calls a user like `sudo -Hu pleroma`; in this case, use `su <username> -s $SHELL -c 'command'` instead. +This guide will assume you are on Debian 12 (“bookworm”) or later. This guide should also work with Ubuntu 22.04 (“jammy”) and later. It also assumes that you have administrative rights, either as root or a user with [sudo permissions](https://www.digitalocean.com/community/tutorials/how-to-add-delete-and-grant-sudo-privileges-to-users-on-a-debian-vps). If you want to run this guide with root, ignore the `sudo` at the beginning of the lines, unless it calls a user like `sudo -Hu pleroma`; in this case, use `su <username> -s $SHELL -c 'command'` instead. {! backend/installation/generic_dependencies.include !} @@ -136,6 +136,11 @@ sudo ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/ple ``` * Before starting nginx edit the configuration and change it to your needs (e.g. change servername, change cert paths) + +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + * Enable and start nginx: ```shell diff --git a/docs/installation/debian_based_jp.md b/docs/installation/debian_based_jp.md index 3736e85..b6b5c9c 100755..100644 --- a/docs/installation/debian_based_jp.md +++ b/docs/installation/debian_based_jp.md @@ -1,16 +1,19 @@ # Pleromaの入れ方 + +Note: This article is potentially outdated because at this time we may not have people who can speak this language well enough to update it. To see the up-to-date version, which may have significant differences or important caveats of the installation process, look up the English version. + ## 日本語訳について この記事は [Installing on Debian based distributions](Installing on Debian based distributions) の日本語訳です。何かがおかしいと思ったら、原文を見てください。 ## インストール -このガイドはDebian Stretchを利用することを想定しています。Ubuntu 16.04や18.04でもおそらく動作します。また、ユーザはrootもしくはsudoにより管理者権限を持っていることを前提とします。もし、以下の操作をrootユーザで行う場合は、 `sudo` を無視してください。ただし、`sudo -Hu pleroma` のようにユーザを指定している場合には `su <username> -s $SHELL -c 'command'` を代わりに使ってください。 +このガイドはDebian Bookwormを利用することを想定しています。Ubuntu 22.04でもおそらく動作します。また、ユーザはrootもしくはsudoにより管理者権限を持っていることを前提とします。もし、以下の操作をrootユーザで行う場合は、 `sudo` を無視してください。ただし、`sudo -Hu pleroma` のようにユーザを指定している場合には `su <username> -s $SHELL -c 'command'` を代わりに使ってください。 ### 必要なソフトウェア -- PostgreSQL 9.6以上 (Ubuntu16.04では9.5しか提供されていないので，[](https://www.postgresql.org/download/linux/ubuntu/)こちらから新しいバージョンを入手してください) -- `postgresql-contrib` 9.6以上 (同上) +- PostgreSQL 11.0以上 (Ubuntu16.04では9.5しか提供されていないので，[](https://www.postgresql.org/download/linux/ubuntu/)こちらから新しいバージョンを入手してください) +- `postgresql-contrib` 11.0以上 (同上) - Elixir 1.8 以上 ([Debianのリポジトリからインストールしないこと！！！ ここからインストールすること！](https://elixir-lang.org/install.html#unix-and-unix-like)。または [asdf](https://github.com/asdf-vm/asdf) をpleromaユーザーでインストールしてください) - `erlang-dev` - `erlang-nox` diff --git a/docs/installation/freebsd_en.md b/docs/installation/freebsd_en.md index 9cbe0f2..02513da 100755..100644 --- a/docs/installation/freebsd_en.md +++ b/docs/installation/freebsd_en.md @@ -9,7 +9,7 @@ This document was written for FreeBSD 12.1, but should be work on future release This assumes the target system has `pkg(8)`. ``` -# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake +# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake vips ``` Copy the rc.d scripts to the right directory: @@ -41,6 +41,7 @@ Create a user for Pleroma: ``` # pw add user pleroma -m # echo 'export LC_ALL="en_US.UTF-8"' >> /home/pleroma/.profile +# echo 'export VIX_COMPILATION_MODE=PLATFORM_PROVIDED_LIBVIPS' >> /home/pleroma/.profile # su -l pleroma ``` @@ -173,6 +174,10 @@ Edit the defaults of `/usr/local/etc/nginx/sites-available/pleroma.nginx`: * Change `ssl_certificate_key` to `/var/db/acme/certs/example.tld/example.tld.key`. * Change all references of `example.tld` to your instance's domain name. +#### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + ## Creating a startup script for Pleroma Pleroma will need to compile when it initially starts, which typically takes a longer diff --git a/docs/installation/further_reading.include b/docs/installation/further_reading.include index 46752c7..46752c7 100755..100644 --- a/docs/installation/further_reading.include +++ b/docs/installation/further_reading.include diff --git a/docs/installation/generic_dependencies.include b/docs/installation/generic_dependencies.include index dcaacfd..6572716 100755..100644 --- a/docs/installation/generic_dependencies.include +++ b/docs/installation/generic_dependencies.include @@ -1,11 +1,11 @@ ## Required dependencies -* PostgreSQL 9.6+ -* Elixir 1.10+ -* Erlang OTP 22.2+ +* PostgreSQL >=11.0 +* Elixir >=1.11.0 <1.15 +* Erlang OTP >=22.2.0 (supported: <27) * git * file / libmagic -* gcc (clang might also work) +* gcc or clang * GNU make * CMake diff --git a/docs/installation/gentoo_en.md b/docs/installation/gentoo_en.md index 36882c8..dc47d27 100755..100644 --- a/docs/installation/gentoo_en.md +++ b/docs/installation/gentoo_en.md @@ -1,6 +1,8 @@ -# Installing on Gentoo GNU/Linux +# Manual install on Gentoo GNU/Linux -{! backend/installation/otp_vs_from_source_source.include !} +{! backend/installation/otp_vs_from_source.include !} + +This guide covers a manual from-source installation. To use the gentoo package, please check the [packaged installation guide for gentoo](./gentoo_otp_en.md). ## Installation @@ -57,7 +59,7 @@ Gentoo quite pointedly does not come with a cron daemon installed, and as such i If you would not like to install the optional packages, remove them from this line. -If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, strech a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. +If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, stretch a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. ### Install PostgreSQL @@ -102,7 +104,7 @@ Not only does this make it much easier to deploy changes you make, as you can co * Add a new system user for the Pleroma service and set up default directories: -Remove `,wheel` if you do not want this user to be able to use `sudo`, however note that being able to `sudo` as the `pleroma` user will make finishing the insallation and common maintenence tasks somewhat easier: +Remove `,wheel` if you do not want this user to be able to use `sudo`, however note that being able to `sudo` as the `pleroma` user will make finishing the installation and common maintenance tasks somewhat easier: ```shell # useradd -m -G users,wheel -s /bin/bash pleroma @@ -227,6 +229,10 @@ Replace all instances of `example.tld` with your instance's public URL. If for w Pay special attention to the line that begins with `ssl_ecdh_curve`. It is stongly advised to comment that line out so that OpenSSL will use its full capabilities, and it is also possible you are running OpenSSL 1.0.2 necessitating that you do this. +* (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + * Enable and start nginx: ```shell diff --git a/docs/installation/gentoo_otp_en.md b/docs/installation/gentoo_otp_en.md new file mode 100644 index 0000000..20d8835 --- /dev/null +++ b/docs/installation/gentoo_otp_en.md @@ -0,0 +1,207 @@ +# Packaged install on Gentoo Linux + +{! backend/installation/otp_vs_from_source.include !} + +This guide covers installation via Gentoo provided packaging. A [manual installation guide for gentoo](./gentoo_en.md) is also available. + +## Installation + +This guide will assume that you have administrative rights, either as root or a user with [sudo permissions](https://wiki.gentoo.org/wiki/Sudo). Lines that begin with `#` indicate that they should be run as the superuser. Lines using `$` should be run as the indicated user, e.g. `pleroma$` should be run as the `pleroma` user. + +{! backend/installation/generic_dependencies.include !} + +### Installing a cron daemon + +Gentoo quite pointedly does not come with a cron daemon installed, and as such it is recommended you install one to automate certbot renewals and to allow other system administration tasks to be run automatically. Gentoo has [a whole wide world of cron options](https://wiki.gentoo.org/wiki/Cron) but if you just want A Cron That Works, `emerge --ask virtual/cron` will install the default cron implementation (probably cronie) which will work just fine. For the purpouses of this guide, we will be doing just that. + +### Required ebuilds + +* `www-apps/pleroma` + +#### Optional ebuilds used in this guide + +* `www-servers/nginx` (preferred, example configs for other reverse proxies can be found in the repo) +* `app-crypt/certbot` (or any other ACME client for Let’s Encrypt certificates) +* `app-crypt/certbot-nginx` (nginx certbot plugin that allows use of the all-powerful `--nginx` flag on certbot) +* `media-gfx/imagemagick` +* `media-video/ffmpeg` +* `media-libs/exiftool` + +### Prepare the system + +* If you haven't yet done so, add the [Gentoo User Repository (GURU)](https://wiki.gentoo.org/wiki/Project:GURU), where the `www-apps/pleroma` ebuild currently lives at: +```shell + # eselect repository enable guru +``` + +* Ensure that you have the latest copy of the Gentoo and GURU ebuilds if you have not synced them yet: + +```shell + # emaint sync -a +``` + + +* Emerge all required the required and suggested software in one go: + +```shell + # emerge --ask www-apps/pleroma www-servers/nginx app-crypt/certbot app-crypt/certbot-nginx +``` + +If you would not like to install the optional packages, remove them from this line. + +If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, stretch a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do. + +### Setup PostgreSQL + +[Gentoo Wiki article](https://wiki.gentoo.org/wiki/PostgreSQL) as well as [PostgreSQL QuickStart](https://wiki.gentoo.org/wiki/PostgreSQL/QuickStart) might be worth a quick glance, as the way Gentoo handles postgres is slightly unusual, with built in capability to have two different databases running for testing and live or whatever other purpouse. While it is still straightforward to install, it does mean that the version numbers used in this guide might change for future updates, so keep an eye out for the output you get from `emerge` to ensure you are using the correct ones. + +* Initialize the database cluster + +The output from emerging postgresql should give you a command for initializing the postgres database. The default slot should be indicated in this command, ensure that it matches the command below. + +```shell + # emerge --config dev-db/postgresql:11 +``` + +### Install media / graphics packages (optional) + +See [Optional software packages needed for specific functionality](optional/media_graphics_packages.md) for details. + +```shell +# emerge --ask media-video/ffmpeg media-gfx/imagemagick media-libs/exiftool +``` + +### Setup PleromaBE + +* Generate the configuration: + +```shell + # pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" +``` + +* Create the PostgreSQL database + +```shell + # sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" +``` + +* Now run the database migration: + +```shell + # pleroma_ctl migrate +``` + +* Optional: If you have installed RUM indexes (`dev-db/rum`) you also need to run: +``` + # sudo -Hu pleroma "pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" +``` + +* Now you can start Pleroma already and add it in the default runlevel + +```shell + # rc-service pleroma start + # rc-update add pleroma default +``` + +It probably won't work over the public internet quite yet, however, as we still need to set up a web server to proxy to the pleroma application, as well as configure SSL. + +### Finalize installation + +Assuming you want to open your newly installed federated social network to, well, the federation, you should run nginx or some other webserver/proxy in front of Pleroma. It is also a good idea to set up Pleroma to run as a system service. + +#### Nginx + +* Install nginx, if not already done: + +```shell + # emerge --ask www-servers/nginx +``` + +* Create directories for available and enabled sites: + +```shell + # mkdir -p /etc/nginx/sites-{available,enabled} +``` + +* Append the following line at the end of the `http` block in `/etc/nginx/nginx.conf`: + +```Nginx +include sites-enabled/*; +``` + +* Setup your SSL cert, using your method of choice or certbot. If using certbot, install it if you haven't already: + +```shell + # emerge --ask app-crypt/certbot app-crypt/certbot-nginx +``` + +and then set it up: + +```shell + # mkdir -p /var/lib/letsencrypt/ + # certbot certonly --email <your@emailaddress> -d <yourdomain> --standalone +``` + +If that doesn't work the first time, add `--dry-run` to further attempts to avoid being ratelimited as you identify the issue, and do not remove it until the dry run succeeds. If that doesn’t work, make sure, that nginx is not already running. If it still doesn’t work, try setting up nginx first (change ssl “on” to “off” and try again). Often the answer to issues with certbot is to use the `--nginx` flag once you have nginx up and running. + +If you are using any additional subdomains, such as for a media proxy, you can re-run the same command with the subdomain in question. When it comes time to renew later, you will not need to run multiple times for each domain, one renew will handle it. + +--- + +* Copy the example nginx configuration and activate it: + +```shell + # cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/ + # ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx +``` + +* Take some time to ensure that your nginx config is correct + +Replace all instances of `example.tld` with your instance's public URL. If for whatever reason you made changes to the port that your pleroma app runs on, be sure that is reflected in your configuration. + +Pay special attention to the line that begins with `ssl_ecdh_curve`. It is stongly advised to comment that line out so that OpenSSL will use its full capabilities, and it is also possible you are running OpenSSL 1.0.2 necessitating that you do this. + +* Enable and start nginx: + +```shell + # rc-update add nginx default + # /etc/init.d/nginx start +``` + +If you are using certbot, it is HIGHLY recommend you set up a cron job that renews your certificate, and that you install the suggested `certbot-nginx` plugin. If you don't do these things, you only have yourself to blame when your instance breaks suddenly because you forgot about it. + +First, ensure that the command you will be installing into your crontab works. + +```shell + # /usr/bin/certbot renew --nginx +``` + +Assuming not much time has passed since you got certbot working a few steps ago, you should get a message for all domains you installed certificates for saying `Cert not yet due for renewal`. + +Now, run crontab as a superuser with `crontab -e` or `sudo crontab -e` as appropriate, and add the following line to your cron: + +```cron +0 0 1 * * /usr/bin/certbot renew --nginx +``` + +This will run certbot on the first of the month at midnight. If you'd rather run more frequently, it's not a bad idea, feel free to go for it. + +#### Other webserver/proxies + +If you would like to use other webservers or proxies, there are example configurations for some popular alternatives in `/opt/pleroma/installation/`. You can, of course, check out [the Gentoo wiki](https://wiki.gentoo.org) for more information on installing and configuring said alternatives. + +#### Create your first user + +If your instance is up and running, you can create your first user with administrative rights with the following task: + +```shell +pleroma$ pleroma_ctl user new <username> <your@emailaddress> --admin +``` + +#### Further reading + +{! backend/installation/further_reading.include !} + +## Questions + +Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC. diff --git a/docs/installation/migrating_from_source_otp_en.md b/docs/installation/migrating_from_source_otp_en.md index f6f2340..7988625 100755..100644 --- a/docs/installation/migrating_from_source_otp_en.md +++ b/docs/installation/migrating_from_source_otp_en.md @@ -86,26 +86,26 @@ export FLAVOUR="amd64-musl" # Clone the release build into a temporary directory and unpack it # Replace `stable` with `unstable` if you want to run the unstable branch -su pleroma -s $SHELL -lc " +sudo -Hu pleroma " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip unzip /tmp/pleroma.zip -d /tmp/ " # Move the release to the home directory and delete temporary files -su pleroma -s $SHELL -lc " +sudo -Hu pleroma " mv /tmp/release/* ~pleroma/ rmdir /tmp/release rm /tmp/pleroma.zip " # Start the instance to verify that everything is working as expected -su pleroma -s $SHELL -lc "./bin/pleroma daemon" +sudo -Hu pleroma "./bin/pleroma daemon" # Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly sleep 20 && curl http://localhost:4000/api/v1/instance # Stop the instance -su pleroma -s $SHELL -lc "./bin/pleroma stop" +sudo -Hu pleroma "./bin/pleroma stop" ``` ## Setting up a system service diff --git a/docs/installation/netbsd_en.md b/docs/installation/netbsd_en.md index 41b3b00..2ade7df 100755..100644 --- a/docs/installation/netbsd_en.md +++ b/docs/installation/netbsd_en.md @@ -123,6 +123,10 @@ Edit the defaults: * Change `ssl_certificate_key` to `/etc/nginx/tls/key`. * Change `example.tld` to your instance's domain name. +### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + ## Configuring acme.sh We'll be using acme.sh in Stateless Mode for TLS certificate renewal. diff --git a/docs/installation/nixos_en.md b/docs/installation/nixos_en.md index f3c4988..f3c4988 100755..100644 --- a/docs/installation/nixos_en.md +++ b/docs/installation/nixos_en.md diff --git a/docs/installation/openbsd_en.md b/docs/installation/openbsd_en.md index c80c8f6..e58e144 100755..100644 --- a/docs/installation/openbsd_en.md +++ b/docs/installation/openbsd_en.md @@ -62,7 +62,7 @@ rcctl start postgresql To check that it started properly and didn't fail right after starting, you can run `ps aux | grep postgres`, there should be multiple lines of output. #### httpd -httpd will have three fuctions: +httpd will have three functions: * redirect requests trying to reach the instance over http to the https URL * serve a robots.txt file @@ -195,6 +195,10 @@ rcctl enable relayd rcctl start relayd ``` +##### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + #### pf Enabling and configuring pf is highly recommended. In /etc/pf.conf, insert the following configuration: @@ -221,7 +225,7 @@ pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach par pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh ``` -Replace *<network interface\>* by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized\_ssh\_clients macro by, for exemple, your home IP address, to avoid SSH connection attempts from bots. +Replace *<network interface\>* by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized\_ssh\_clients macro by, for example, your home IP address, to avoid SSH connection attempts from bots. Check pf's configuration by running `pfctl -nf /etc/pf.conf`, load it with `pfctl -f /etc/pf.conf` and enable pf at boot with `rcctl enable pf`. diff --git a/docs/installation/openbsd_fi.md b/docs/installation/openbsd_fi.md index 3c40b2d..73aca3a 100755..100644 --- a/docs/installation/openbsd_fi.md +++ b/docs/installation/openbsd_fi.md @@ -1,5 +1,7 @@ # Pleroman asennus OpenBSD:llä +Note: This article is potentially outdated because at this time we may not have people who can speak this language well enough to update it. To see the up-to-date version, which may have significant differences or important caveats of the installation process, look up the English version. + Tarvitset: * Oman domainin * OpenBSD 6.3 -serverin diff --git a/docs/installation/optional/media_graphics_packages.md b/docs/installation/optional/media_graphics_packages.md index de402d1..ad01d47 100755..100644 --- a/docs/installation/optional/media_graphics_packages.md +++ b/docs/installation/optional/media_graphics_packages.md @@ -1,9 +1,10 @@ # Optional software packages needed for specific functionality For specific Pleroma functionality (which is disabled by default) some or all of the below packages are required: - * `ImageMagic` - * `ffmpeg` - * `exiftool` + +* `ImageMagic` +* `ffmpeg` +* `exiftool` Please refer to documentation in `docs/installation` on how to install them on specific OS. @@ -14,20 +15,23 @@ Note: the packages are not required with the current default settings of Pleroma `ImageMagick` is a set of tools to create, edit, compose, or convert bitmap images. It is required for the following Pleroma features: - * `Pleroma.Upload.Filters.Mogrify`, `Pleroma.Upload.Filters.Mogrifun` upload filters (related config: `Plaroma.Upload/filters` in `config/config.exs`) - * Media preview proxy for still images (related config: `media_preview_proxy/enabled` in `config/config.exs`) + +* `Pleroma.Upload.Filters.Mogrify`, `Pleroma.Upload.Filters.Mogrifun` upload filters (related config: `Plaroma.Upload/filters` in `config/config.exs`) +* Media preview proxy for still images (related config: `media_preview_proxy/enabled` in `config/config.exs`) ## `ffmpeg` `ffmpeg` is software to record, convert and stream audio and video. It is required for the following Pleroma features: - * Media preview proxy for videos (related config: `media_preview_proxy/enabled` in `config/config.exs`) + +* Media preview proxy for videos (related config: `media_preview_proxy/enabled` in `config/config.exs`) ## `exiftool` `exiftool` is media files metadata reader/writer. It is required for the following Pleroma features: - * `Pleroma.Upload.Filters.Exiftool.StripLocation` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) - * `Pleroma.Upload.Filters.Exiftool.ReadDescription` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) + +* `Pleroma.Upload.Filters.Exiftool.StripLocation` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) +* `Pleroma.Upload.Filters.Exiftool.ReadDescription` upload filter (related config: `Plaroma.Upload/filters` in `config/config.exs`) diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index f281234..86efa27 100755..100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -115,13 +115,13 @@ adduser --system --shell /bin/false --home /opt/pleroma pleroma export FLAVOUR="amd64-musl" # Clone the release build into a temporary directory and unpack it -su pleroma -s $SHELL -lc " +sudo -Hu pleroma " curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip unzip /tmp/pleroma.zip -d /tmp/ " # Move the release to the home directory and delete temporary files -su pleroma -s $SHELL -lc " +sudo -Hu pleroma " mv /tmp/release/* /opt/pleroma rmdir /tmp/release rm /tmp/pleroma.zip @@ -142,25 +142,25 @@ mkdir -p /etc/pleroma chown -R pleroma /etc/pleroma # Run the config generator -su pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" +sudo -Hu pleroma "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql" # Create the postgres database -su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" +sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql" # Create the database schema -su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate" +sudo -Hu pleroma "./bin/pleroma_ctl migrate" # If you have installed RUM indexes uncommend and run -# su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" +# sudo -Hu pleroma "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/" # Start the instance to verify that everything is working as expected -su pleroma -s $SHELL -lc "./bin/pleroma daemon" +sudo -Hu pleroma "./bin/pleroma daemon" # Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly sleep 20 && curl http://localhost:4000/api/v1/instance # Stop the instance -su pleroma -s $SHELL -lc "./bin/pleroma stop" +sudo -Hu pleroma "./bin/pleroma stop" ``` ### Setting up nginx and getting Let's Encrypt SSL certificaties @@ -198,6 +198,10 @@ $EDITOR path-to-nginx-config # Verify that the config is valid nginx -t ``` +#### (Strongly recommended) serve media on another domain + +Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors. + #### Start nginx === "Alpine" @@ -234,7 +238,7 @@ At this point if you open your (sub)domain in a browser you should see a 502 err systemctl enable pleroma ``` -If everything worked, you should see Pleroma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Pleroma in the foreground and seeing if there are any errrors. +If everything worked, you should see Pleroma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Pleroma in the foreground and seeing if there are any errors. Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC, you can also [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma-support/issues/new). diff --git a/docs/installation/otp_vs_from_source.include b/docs/installation/otp_vs_from_source.include index 63e837a..6c78202 100755..100644 --- a/docs/installation/otp_vs_from_source.include +++ b/docs/installation/otp_vs_from_source.include @@ -1,3 +1,8 @@ -## OTP releases vs from-source installations +## Packaged (OTP) installation vs Manual (from-source) installations -There are two ways to install Pleroma. You can use OTP releases or do a from-source installation. OTP releases are as close as you can get to binary releases with Erlang/Elixir. The release is self-contained, and provides everything needed to boot it, it is easily administered via the provided shell script to open up a remote console, start/stop/restart the release, start in the background, send remote commands, and more. With from source installations you install Pleroma from source, meaning you have to install certain dependencies like Erlang+Elixir and compile Pleroma yourself. +There is multiple ways to install Pleroma. +<dl> +<dt>Distro-provided packages</dt><dd>This is the recommended method, where you can get the strongest compatibility guarantees and the best dependency-management</dd> +<dt>Pleroma-provided OTP binaries</dt><dd>Intended as fallback for Alpine/Debian-compatible systems lacking a proper Pleroma package, they are heavier than proper distro packages as they also contain Erlang/Elixir and can break after system updates</dd> +<dt>Manual from-source installation</dt><dd>Needs build-dependencies to be installed and manual updates+rebuilds. Allows for easier source-customisations.</dd> +</dl> diff --git a/docs/installation/otp_vs_from_source_source.include b/docs/installation/otp_vs_from_source_source.include index 63482b6..9f71342 100755..100644 --- a/docs/installation/otp_vs_from_source_source.include +++ b/docs/installation/otp_vs_from_source_source.include @@ -1,3 +1,3 @@ {! backend/installation/otp_vs_from_source.include !} -This guide covers a from-source installation. To install using OTP releases, please check out [the OTP guide](./otp_en.md). +This guide covers a manual from-source installation. To install using OTP releases, please check for the presence of a distro package, failing that you can use [Pleroma-provided OTP binaries](./otp_en.md). diff --git a/docs/installation/yunohost_en.md b/docs/installation/yunohost_en.md index 4c34e85..4c34e85 100755..100644 --- a/docs/installation/yunohost_en.md +++ b/docs/installation/yunohost_en.md diff --git a/docs/installation_1/apache-cache-purge.sh.example b/docs/installation_1/apache-cache-purge.sh.example deleted file mode 100755 index 7b42628..0000000 --- a/docs/installation_1/apache-cache-purge.sh.example +++ /dev/null @@ -1,36 +0,0 @@ -#!/bin/sh - -# A simple shell script to delete a media from Apache's mod_disk_cache. -# You will likely need to setup a sudo rule like the following: -# -# Cmnd_Alias HTCACHECLEAN = /usr/local/sbin/htcacheclean -# pleroma ALL=HTCACHECLEAN, NOPASSWD: HTCACHECLEAN -# -# Please also ensure you have enabled: -# -# config :pleroma, Pleroma.Web.MediaProxy.Invalidation.Script, url_format: :htcacheclean -# -# which will correctly format the URLs passed to this script for the htcacheclean utility. -# - -SCRIPTNAME=${0##*/} - -# mod_disk_cache directory -CACHE_DIRECTORY="/tmp/pleroma-media-cache" - -## Removes an item via the htcacheclean utility -## $1 - the filename, can be a pattern . -## $2 - the cache directory. -purge_item() { - sudo htcacheclean -v -p "${2}" "${1}" -} # purge_item - -purge() { - for url in $@ - do - echo "$SCRIPTNAME delete \`$url\` from cache ($CACHE_DIRECTORY)" - purge_item "$url" $CACHE_DIRECTORY - done -} - -purge $@ diff --git a/docs/installation_1/caddyfile-pleroma.example b/docs/installation_1/caddyfile-pleroma.example deleted file mode 100755 index cc7dda0..0000000 --- a/docs/installation_1/caddyfile-pleroma.example +++ /dev/null @@ -1,17 +0,0 @@ -# default Caddyfile config for Pleroma -# -# Simple installation instructions: -# 1. Replace 'example.tld' with your instance's domain wherever it appears. -# 2. Copy this section into your Caddyfile and restart Caddy. - -example.tld { - log { - output file /var/log/caddy/pleroma.log - } - - encode gzip - - # this is explicitly IPv4 since Pleroma.Web.Endpoint binds on IPv4 only - # and `localhost.` resolves to [::0] on some systems: see issue #930 - reverse_proxy 127.0.0.1:4000 -} diff --git a/docs/installation_1/freebsd/rc.d/pleroma b/docs/installation_1/freebsd/rc.d/pleroma deleted file mode 100755 index f62aef1..0000000 --- a/docs/installation_1/freebsd/rc.d/pleroma +++ /dev/null @@ -1,27 +0,0 @@ -#!/bin/sh -# $FreeBSD$ -# PROVIDE: pleroma -# REQUIRE: DAEMON postgresql -# KEYWORD: shutdown - -# sudo -u pleroma MIX_ENV=prod elixir --erl \"-detached\" -S mix phx.server - -. /etc/rc.subr - -name=pleroma -rcvar=pleroma_enable - -desc="Pleroma Social Media Platform" - -load_rc_config ${name} - -: ${pleroma_user:=pleroma} -: ${pleroma_home:=$(getent passwd ${pleroma_user} | awk -F: '{print $6}')} -: ${pleroma_chdir:="${pleroma_home}/pleroma"} -: ${pleroma_env:="HOME=${pleroma_home} MIX_ENV=prod"} - -command=/usr/local/bin/elixir -command_args="--erl \"-detached\" -S /usr/local/bin/mix phx.server" -procname="*beam.smp" - -run_rc_command "$1" diff --git a/docs/installation_1/init.d/pleroma b/docs/installation_1/init.d/pleroma deleted file mode 100755 index 384536f..0000000 --- a/docs/installation_1/init.d/pleroma +++ /dev/null @@ -1,45 +0,0 @@ -#!/sbin/openrc-run -supervisor=supervise-daemon -command_user=pleroma:pleroma -command_background=1 -# Ask process to terminate within 30 seconds, otherwise kill it -retry="SIGTERM/30/SIGKILL/5" -pidfile="/var/run/pleroma.pid" -directory=/opt/pleroma -healthcheck_delay=60 -healthcheck_timer=30 - -: ${pleroma_port:-4000} - -# Needs OpenRC >= 0.42 -#respawn_max=0 -#respawn_delay=5 - -# put pleroma_console=YES in /etc/conf.d/pleroma if you want to be able to -# connect to pleroma via an elixir console -if yesno "${pleroma_console}"; then - command=elixir - command_args="--name pleroma@127.0.0.1 --erl '-kernel inet_dist_listen_min 9001 inet_dist_listen_max 9001 inet_dist_use_interface {127,0,0,1}' -S mix phx.server" - - start_post() { - einfo "You can get a console by using this command as pleroma's user:" - einfo "iex --name console@127.0.0.1 --remsh pleroma@127.0.0.1" - } -else - command=/usr/bin/mix - command_args="phx.server" -fi - -export MIX_ENV=prod - -depend() { - need nginx postgresql -} - -healthcheck() { - # put pleroma_health=YES in /etc/conf.d/pleroma if you want healthchecking - # and make sure you have curl installed - yesno "$pleroma_health" || return 0 - - curl -q "localhost:${pleroma_port}/api/pleroma/healthcheck" -} diff --git a/docs/installation_1/netbsd/rc.d/pleroma b/docs/installation_1/netbsd/rc.d/pleroma deleted file mode 100755 index 1114668..0000000 --- a/docs/installation_1/netbsd/rc.d/pleroma +++ /dev/null @@ -1,57 +0,0 @@ -#!/bin/sh -# PROVIDE: pleroma -# REQUIRE: DAEMON pgsql - -if [ -f /etc/rc.subr ]; then - . /etc/rc.subr -fi - -name="pleroma" -rcvar=${name} -command="/usr/pkg/bin/elixir" -command_args="--detached -S /usr/pkg/bin/mix phx.server" -start_precmd="ulimit -n unlimited" -pidfile="/dev/null" - -pleroma_chdir="${pleroma_home}/pleroma" -pleroma_env="HOME=${pleroma_home} MIX_ENV=prod" - -check_pidfile() -{ - pid=$(pgrep -U "${pleroma_user}" /bin/beam.smp$) - echo -n "${pid}" -} - -if [ -f /etc/rc.subr -a -d /etc/rc.d -a -f /etc/rc.d/DAEMON ]; then - # newer NetBSD - load_rc_config ${name} - run_rc_command "$1" -else - # ancient NetBSD, Solaris and illumos, Linux, etc... - cmd=${1:-start} - - case ${cmd} in - start) - echo "Starting ${name}." - ${start_cmd} - ;; - - stop) - echo "Stopping ${name}." - check_pidfile - ! [ -n ${pid} ] && kill ${pid} - ;; - - restart) - ( $0 stop ) - sleep 5 - $0 start - ;; - - *) - echo 1>&2 "Usage: $0 [start|stop|restart]" - exit 1 - ;; - esac - exit 0 -fi diff --git a/docs/installation_1/nginx-cache-purge.sh.example b/docs/installation_1/nginx-cache-purge.sh.example deleted file mode 100755 index 5f6cbb1..0000000 --- a/docs/installation_1/nginx-cache-purge.sh.example +++ /dev/null @@ -1,40 +0,0 @@ -#!/bin/sh - -# A simple shell script to delete a media from the Nginx cache. - -SCRIPTNAME=${0##*/} - -# NGINX cache directory -CACHE_DIRECTORY="/tmp/pleroma-media-cache" - -## Return the files where the items are cached. -## $1 - the filename, can be a pattern . -## $2 - the cache directory. -## $3 - (optional) the number of parallel processes to run for grep. -get_cache_files() { - local max_parallel=${3-16} - find $2 -maxdepth 2 -type d | xargs -P $max_parallel -n 1 grep -E -Rl "^KEY:.*$1" | sort -u -} - -## Removes an item from the given cache zone. -## $1 - the filename, can be a pattern . -## $2 - the cache directory. -purge_item() { - for f in $(get_cache_files $1 $2); do - echo "found file: $f" - [ -f $f ] || continue - echo "Deleting $f from $2." - rm $f - done -} # purge_item - -purge() { - for url in "$@" - do - echo "$SCRIPTNAME delete \`$url\` from cache ($CACHE_DIRECTORY)" - purge_item $url $CACHE_DIRECTORY - done - -} - -purge $@ diff --git a/docs/installation_1/openbsd/httpd.conf b/docs/installation_1/openbsd/httpd.conf deleted file mode 100755 index 82f4803..0000000 --- a/docs/installation_1/openbsd/httpd.conf +++ /dev/null @@ -1,36 +0,0 @@ -# -# Default httpd.conf file for Pleroma on OpenBSD -# Simple installation instructions -# 1. Place file in /etc -# 2. Replace <IPv4 address> with your public IP address -# 3. If using IPv6, uncomment IPv6 lines and replace <IPv6 address> with your public IPv6 address -# 4. Check file using 'doas httpd -n' -# 5. Enable and start httpd: -# # doas rcctl enable httpd -# # doas rcctl start httpd -# - -ext_inet="<IPv4 address>" -#ext_inet6="<IPv6 address>" - -server "default" { - listen on $ext_inet port 80 # Comment to disable listening on IPv4 -# listen on $ext_inet6 port 80 # Comment to disable listening on IPv6 - listen on 127.0.0.1 port 80 # Do NOT comment this line - - log syslog - directory no index - - location "/.well-known/acme-challenge/*" { - root "/acme" - request strip 2 - } - - location "/robots.txt" { root "/htdocs/local/" } - location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" } -} - -types { - include "/usr/share/misc/mime.types" -} - diff --git a/docs/installation_1/openbsd/rc.d/pleromad b/docs/installation_1/openbsd/rc.d/pleromad deleted file mode 100755 index 19ac4bb..0000000 --- a/docs/installation_1/openbsd/rc.d/pleromad +++ /dev/null @@ -1,34 +0,0 @@ -#!/bin/ksh -# -# Default init file for Pleroma on OpenBSD -# -# Simple installation instructions: -# 1. Install Pleroma per wiki instructions -# 2. Place this pleromad file in /etc/rc.d -# 3. Enable and start Pleroma -# # doas rcctl enable pleromad -# # doas rcctl start pleromad -# - -daemon="/usr/local/bin/elixir" -daemon_flags="--detached -S /usr/local/bin/mix phx.server" -daemon_user="_pleroma" - -. /etc/rc.d/rc.subr - -rc_reload=NO -pexp="phx.server" - -rc_check() { - pgrep -q -U _pleroma -f "phx.server" -} - -rc_start() { - ${rcexec} "cd pleroma; ${daemon} ${daemon_flags}" -} - -rc_stop() { - pkill -q -U _pleroma -f "phx.server" -} - -rc_cmd $1 diff --git a/docs/installation_1/openbsd/relayd.conf b/docs/installation_1/openbsd/relayd.conf deleted file mode 100755 index 31c2c11..0000000 --- a/docs/installation_1/openbsd/relayd.conf +++ /dev/null @@ -1,44 +0,0 @@ -# -# Default relayd.conf file for Pleroma on OpenBSD -# Simple installation instructions: -# 1. Place in /etc -# 2. Replace <ipaddr> with your public IPv4 address -# 3. If using IPv6i, uncomment IPv6 lines and replace <ip6addr> with your public IPv6 address -# 4. Check file using 'doas relayd -n' -# 5. Reload/start relayd -# # doas rcctl enable relayd -# # doas rcctl start relayd -# - -ext_inet="<ipaddr>" -#ext_inet6="<ip6addr>" - -table <pleroma_server> { 127.0.0.1 } -table <httpd_server> { 127.0.0.1 } - -http protocol plerup { # Protocol for upstream pleroma server - #tcp { nodelay, sack, socket buffer 65536, backlog 128 } # Uncomment and adjust as you see fit - tls ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA0-POLY1305" - tls ecdhe secp384r1 - - # Forward some paths to the local server (as pleroma won't respond to them as you might want) - pass request quick path "/robots.txt" forward to <httpd_server> - - # Append a bunch of headers - match request header append "X-Forwarded-For" value "$REMOTE_ADDR" # This two header and the next one are not strictl required by pleroma but adding them won't hurt - match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT" - - match request header append "Connection" value "upgrade" - -} - -relay wwwtls { - listen on $ext_inet port https tls # Comment to disable listening on IPv4 -# listen on $ext_inet6 port https tls # Comment to disable listening on IPv6 - - protocol plerup - - forward to <pleroma_server> port 4000 check http "/" code 200 - forward to <httpd_server> port 80 check http "/robots.txt" code 200 -} - diff --git a/docs/installation_1/pleroma-apache.conf b/docs/installation_1/pleroma-apache.conf deleted file mode 100755 index 139abe9..0000000 --- a/docs/installation_1/pleroma-apache.conf +++ /dev/null @@ -1,84 +0,0 @@ -# Sample Apache config for Pleroma -# -# Simple installation instructions: -# 1. Install your TLS certificate. We recommend using Let's Encrypt via Certbot -# 2. Replace 'example.tld' with your instance's domain. -# 3. This assumes a Debian-style Apache config. Copy this file to -# /etc/apache2/sites-available/ and then activate the site by running -# 'a2ensite pleroma-apache.conf', then restart Apache. -# -# Optional: enable disk-based caching for the media proxy -# For details, see https://git.pleroma.social/pleroma/pleroma/wikis/How%20to%20activate%20mediaproxy -# -# 1. Create a directory as shown below for the CacheRoot and make sure -# the Apache user can write to it. -# 2. Configure Apache's htcacheclean to clean the directory periodically. -# Your OS may provide a service you can enable to do this automatically. - -Define servername example.tld - -<IfModule !proxy_module> - LoadModule proxy_module libexec/apache24/mod_proxy.so -</IfModule> -<IfModule !proxy_http_module> - LoadModule proxy_http_module libexec/apache24/mod_proxy_http.so -</IfModule> -<IfModule !proxy_wstunnel_module> - LoadModule proxy_wstunnel_module libexec/apache24/mod_proxy_wstunnel.so -</IfModule> -<IfModule !rewrite_module> - LoadModule rewrite_module libexec/apache24/mod_rewrite.so -</IfModule> -<IfModule !ssl_module> - LoadModule ssl_module libexec/apache24/mod_ssl.so -</IfModule> -<IfModule !cache_module> - LoadModule cache_module libexec/apache24/mod_cache.so -</IfModule> -<IfModule !cache_disk_module> - LoadModule cache_disk_module libexec/apache24/mod_cache_disk.so -</IfModule> - -ServerName ${servername} -ServerTokens Prod - -# If you want Pleroma-specific logs -#ErrorLog /var/log/httpd-pleroma-error.log -#CustomLog /var/log/httpd-pleroma-access.log combined - -<VirtualHost *:80> - RewriteEngine on - RewriteCond %{SERVER_NAME} =${servername} - RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent] -</VirtualHost> - -<VirtualHost *:443> - SSLEngine on - SSLCertificateFile /etc/letsencrypt/live/${servername}/fullchain.pem - SSLCertificateKeyFile /etc/letsencrypt/live/${servername}/privkey.pem - # Make sure you have the certbot-apache module installed - Include /etc/letsencrypt/options-ssl-apache.conf - - # Uncomment the following to enable MediaProxy caching on disk - #CacheRoot /tmp/pleroma-media-cache/ - #CacheDirLevels 1 - #CacheDirLength 2 - #CacheEnable disk /proxy - #CacheLock on - #CacheHeader on - #CacheDetailHeader on - ## 16MB max filesize for caching, configure as desired - #CacheMaxFileSize 16000000 - #CacheDefaultExpire 86400 - - RewriteEngine On - RewriteCond %{HTTP:Connection} Upgrade [NC] - RewriteCond %{HTTP:Upgrade} websocket [NC] - RewriteRule /(.*) ws://127.0.0.1:4000/$1 [P,L] - - #ProxyRequests must be off or you open your server to abuse as an open proxy - ProxyRequests off - ProxyPass / http://127.0.0.1:4000/ - ProxyPassReverse / http://127.0.0.1:4000/ - ProxyPreserveHost On -</VirtualHost> diff --git a/docs/installation_1/pleroma-mongooseim.cfg b/docs/installation_1/pleroma-mongooseim.cfg deleted file mode 100755 index 3ecba56..0000000 --- a/docs/installation_1/pleroma-mongooseim.cfg +++ /dev/null @@ -1,936 +0,0 @@ -%%% -%%% ejabberd configuration file -%%% -%%%' - -%%% The parameters used in this configuration file are explained in more detail -%%% in the ejabberd Installation and Operation Guide. -%%% Please consult the Guide in case of doubts, it is included with -%%% your copy of ejabberd, and is also available online at -%%% http://www.process-one.net/en/ejabberd/docs/ - -%%% This configuration file contains Erlang terms. -%%% In case you want to understand the syntax, here are the concepts: -%%% -%%% - The character to comment a line is % -%%% -%%% - Each term ends in a dot, for example: -%%% override_global. -%%% -%%% - A tuple has a fixed definition, its elements are -%%% enclosed in {}, and separated with commas: -%%% {loglevel, 4}. -%%% -%%% - A list can have as many elements as you want, -%%% and is enclosed in [], for example: -%%% [http_poll, web_admin, tls] -%%% -%%% Pay attention that list elements are delimited with commas, -%%% but no comma is allowed after the last list element. This will -%%% give a syntax error unlike in more lenient languages (e.g. Python). -%%% -%%% - A keyword of ejabberd is a word in lowercase. -%%% Strings are enclosed in "" and can contain spaces, dots, ... -%%% {language, "en"}. -%%% {ldap_rootdn, "dc=example,dc=com"}. -%%% -%%% - This term includes a tuple, a keyword, a list, and two strings: -%%% {hosts, ["jabber.example.net", "im.example.com"]}. -%%% -%%% - This config is preprocessed during release generation by a tool which -%%% interprets double curly braces as substitution markers, so avoid this -%%% syntax in this file (though it's valid Erlang). -%%% -%%% So this is OK (though arguably looks quite ugly): -%%% { {s2s_addr, "example-host.net"}, {127,0,0,1} }. -%%% -%%% And I can't give an example of what's not OK exactly because -%%% of this rule. -%%% - - -%%%. ======================= -%%%' OVERRIDE STORED OPTIONS - -%% -%% Override the old values stored in the database. -%% - -%% -%% Override global options (shared by all ejabberd nodes in a cluster). -%% -%%override_global. - -%% -%% Override local options (specific for this particular ejabberd node). -%% -%%override_local. - -%% -%% Remove the Access Control Lists before new ones are added. -%% -%%override_acls. - - -%%%. ========= -%%%' DEBUGGING - -%% -%% loglevel: Verbosity of log files generated by ejabberd. -%% 0: No ejabberd log at all (not recommended) -%% 1: Critical -%% 2: Error -%% 3: Warning -%% 4: Info -%% 5: Debug -%% -{loglevel, 3}. - -%%%. ================ -%%%' SERVED HOSTNAMES - -%% -%% hosts: Domains served by ejabberd. -%% You can define one or several, for example: -%% {hosts, ["example.net", "example.com", "example.org"]}. -%% -{hosts, ["pleroma.soykaf.com"] }. - -%% -%% route_subdomains: Delegate subdomains to other XMPP servers. -%% For example, if this ejabberd serves example.org and you want -%% to allow communication with an XMPP server called im.example.org. -%% -%%{route_subdomains, s2s}. - - -%%%. =============== -%%%' LISTENING PORTS - -%% -%% listen: The ports ejabberd will listen on, which service each is handled -%% by and what options to start it with. -%% -{listen, - [ - %% BOSH and WS endpoints over HTTP - { 5280, ejabberd_cowboy, [ - {num_acceptors, 10}, - {transport_options, [{max_connections, 1024}]}, - {modules, [ - - {"_", "/http-bind", mod_bosh}, - {"_", "/ws-xmpp", mod_websockets, [{ejabberd_service, [ - {access, all}, - {shaper_rule, fast}, - {ip, {127, 0, 0, 1}}, - {password, "secret"}]} - %% Uncomment to enable connection dropping or/and server-side pings - %{timeout, 600000}, {ping_rate, 2000} - ]} - %% Uncomment to serve static files - %{"_", "/static/[...]", cowboy_static, - % {dir, "/var/www", [{mimetypes, cow_mimetypes, all}]} - %}, - - %% Example usage of mod_revproxy - - %% {"_", "/[...]", mod_revproxy, [{timeout, 5000}, - %% % time limit for upstream to respond - %% {body_length, 8000000}, - %% % maximum body size (may be infinity) - %% {custom_headers, [{<<"header">>,<<"value">>}]} - %% % list of extra headers that are send to upstream - %% ]} - - %% Example usage of mod_cowboy - - %% {"_", "/[...]", mod_cowboy, [{http, mod_revproxy, - %% [{timeout, 5000}, - %% % time limit for upstream to respond - %% {body_length, 8000000}, - %% % maximum body size (may be infinity) - %% {custom_headers, [{<<"header">>,<<"value">>}]} - %% % list of extra headers that are send to upstream - %% ]}, - %% {ws, xmpp, mod_websockets} - %% ]} - ]} - ]}, - - %% BOSH and WS endpoints over HTTPS - { 5285, ejabberd_cowboy, [ - {num_acceptors, 10}, - {transport_options, [{max_connections, 1024}]}, - {ssl, [{certfile, "priv/ssl/fullchain.pem"}, {keyfile, "priv/ssl/privkey.pem"}, {password, ""}]}, - {modules, [ - {"_", "/http-bind", mod_bosh}, - {"_", "/ws-xmpp", mod_websockets, [ - %% Uncomment to enable connection dropping or/and server-side pings - %{timeout, 600000}, {ping_rate, 60000} - ]} - %% Uncomment to serve static files - %{"_", "/static/[...]", cowboy_static, - % {dir, "/var/www", [{mimetypes, cow_mimetypes, all}]} - %}, - ]} - ]}, - - %% MongooseIM HTTP API it's important to start it on localhost - %% or some private interface only (not accessible from the outside) - %% At least start it on different port which will be hidden behind firewall - - { {8088, "127.0.0.1"} , ejabberd_cowboy, [ - {num_acceptors, 10}, - {transport_options, [{max_connections, 1024}]}, - {modules, [ - {"localhost", "/api", mongoose_api_admin, []} - ]} - ]}, - - { 8089 , ejabberd_cowboy, [ - {num_acceptors, 10}, - {transport_options, [{max_connections, 1024}]}, - {protocol_options, [{compress, true}]}, - {ssl, [{certfile, "priv/ssl/fullchain.pem"}, {keyfile, "priv/ssl/privkey.pem"}, {password, ""}]}, - {modules, [ - {"_", "/api/sse", lasse_handler, [mongoose_client_api_sse]}, - {"_", "/api/messages/[:with]", mongoose_client_api_messages, []}, - {"_", "/api/contacts/[:jid]", mongoose_client_api_contacts, []}, - {"_", "/api/rooms/[:id]", mongoose_client_api_rooms, []}, - {"_", "/api/rooms/[:id]/config", mongoose_client_api_rooms_config, []}, - {"_", "/api/rooms/:id/users/[:user]", mongoose_client_api_rooms_users, []}, - {"_", "/api/rooms/[:id]/messages", mongoose_client_api_rooms_messages, []} - ]} - ]}, - - %% Following HTTP API is deprected, the new one abouve should be used instead - - { {5288, "127.0.0.1"} , ejabberd_cowboy, [ - {num_acceptors, 10}, - {transport_options, [{max_connections, 1024}]}, - {modules, [ - {"localhost", "/api", mongoose_api, [{handlers, [mongoose_api_metrics, - mongoose_api_users]}]} - ]} - ]}, - - %% If you want dual stack, you have to clone this entire config stanza - %% and change the bind to "::" - { {5222, "0.0.0.0"}, ejabberd_c2s, [ - - %% - %% If TLS is compiled in and you installed a SSL - %% certificate, specify the full path to the - %% file and uncomment this line: - %% - {certfile, "priv/ssl/both.pem"}, starttls, - - %%{zlib, 10000}, - %% https://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS - %% {ciphers, "DEFAULT:!EXPORT:!LOW:!SSLv2"}, - {access, c2s}, - {shaper, c2s_shaper}, - {max_stanza_size, 65536}, - {protocol_options, ["no_sslv3"]} - - ]}, - - - - %% - %% To enable the old SSL connection method on port 5223: - %% - %%{5223, ejabberd_c2s, [ - %% {access, c2s}, - %% {shaper, c2s_shaper}, - %% {certfile, "/path/to/ssl.pem"}, tls, - %% {max_stanza_size, 65536} - %% ]}, - - %% If you want dual stack, you have to clone this entire config stanza - %% and change the bind to "::" - { {5269, "0.0.0.0"}, ejabberd_s2s_in, [ - {shaper, s2s_shaper}, - {max_stanza_size, 131072}, - {protocol_options, ["no_sslv3"]} - - ]} - - %% - %% ejabberd_service: Interact with external components (transports, ...) - %% - ,{8888, ejabberd_service, [ - {access, all}, - {shaper_rule, fast}, - {ip, {127, 0, 0, 1}}, - {password, "secret"} - ]} - - %% - %% ejabberd_stun: Handles STUN Binding requests - %% - %%{ {3478, udp}, ejabberd_stun, []} - - ]}. - -%% -%% s2s_use_starttls: Enable STARTTLS + Dialback for S2S connections. -%% Allowed values are: false optional required required_trusted -%% You must specify a certificate file. -%% -{s2s_use_starttls, optional}. -%% -%% s2s_certfile: Specify a certificate file. -%% -{s2s_certfile, "priv/ssl/both.pem"}. - -%% https://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS -%% {s2s_ciphers, "DEFAULT:!EXPORT:!LOW:!SSLv2"}. - -%% -%% domain_certfile: Specify a different certificate for each served hostname. -%% -%%{domain_certfile, "example.org", "/path/to/example_org.pem"}. -%%{domain_certfile, "example.com", "/path/to/example_com.pem"}. - -%% -%% S2S whitelist or blacklist -%% -%% Default s2s policy for undefined hosts. -%% -{s2s_default_policy, deny }. - -%% -%% Allow or deny communication with specific servers. -%% -%%{ {s2s_host, "goodhost.org"}, allow}. -%%{ {s2s_host, "badhost.org"}, deny}. - -{outgoing_s2s_port, 5269 }. - -%% -%% IP addresses predefined for specific hosts to skip DNS lookups. -%% Ports defined here take precedence over outgoing_s2s_port. -%% Examples: -%% -%% { {s2s_addr, "example-host.net"}, {127,0,0,1} }. -%% { {s2s_addr, "example-host.net"}, { {127,0,0,1}, 5269 } }. -%% { {s2s_addr, "example-host.net"}, { {127,0,0,1}, 5269 } }. - -%% -%% Outgoing S2S options -%% -%% Preferred address families (which to try first) and connect timeout -%% in milliseconds. -%% -%%{outgoing_s2s_options, [ipv4, ipv6], 10000}. -%% -%%%. ============== -%%%' SESSION BACKEND - -%%{sm_backend, {mnesia, []}}. - -%% Requires {redis, global, default, ..., ...} outgoing pool -%%{sm_backend, {redis, []}}. - -{sm_backend, {mnesia, []} }. - - -%%%. ============== -%%%' AUTHENTICATION - -%% Advertised SASL mechanisms -{sasl_mechanisms, [cyrsasl_plain]}. - -%% -%% auth_method: Method used to authenticate the users. -%% The default method is the internal. -%% If you want to use a different method, -%% comment this line and enable the correct ones. -%% -%% {auth_method, internal }. -{auth_method, http }. -{auth_opts, [ - {http, global, auth, [{workers, 50}], [{server, "https://pleroma.soykaf.com"}]}, - {password_format, plain} % default - %% {password_format, scram} - - %% {scram_iterations, 4096} % default - - %% - %% For auth_http: - %% {basic_auth, "user:password"} - %% {path_prefix, "/"} % default - %% auth_http requires {http, Host | global, auth, ..., ...} outgoing pool. - %% - %% For auth_external - %%{extauth_program, "/path/to/authentication/script"}. - %% - %% For auth_jwt - %% {jwt_secret_source, "/path/to/file"}, - %% {jwt_algorithm, "RS256"}, - %% {jwt_username_key, user} - %% For cyrsasl_external - %% {authenticate_with_cn, false} - {cyrsasl_external, standard} - ]}. - -%% -%% Authentication using external script -%% Make sure the script is executable by ejabberd. -%% -%%{auth_method, external}. - -%% -%% Authentication using RDBMS -%% Remember to setup a database in the next section. -%% -%%{auth_method, rdbms}. - -%% -%% Authentication using LDAP -%% -%%{auth_method, ldap}. -%% - -%% List of LDAP servers: -%%{ldap_servers, ["localhost"]}. -%% -%% Encryption of connection to LDAP servers: -%%{ldap_encrypt, none}. -%%{ldap_encrypt, tls}. -%% -%% Port to connect to on LDAP servers: -%%{ldap_port, 389}. -%%{ldap_port, 636}. -%% -%% LDAP manager: -%%{ldap_rootdn, "dc=example,dc=com"}. -%% -%% Password of LDAP manager: -%%{ldap_password, "******"}. -%% -%% Search base of LDAP directory: -%%{ldap_base, "dc=example,dc=com"}. -%% -%% LDAP attribute that holds user ID: -%%{ldap_uids, [{"mail", "%u@mail.example.org"}]}. -%% -%% LDAP filter: -%%{ldap_filter, "(objectClass=shadowAccount)"}. - -%% -%% Anonymous login support: -%% auth_method: anonymous -%% anonymous_protocol: sasl_anon | login_anon | both -%% allow_multiple_connections: true | false -%% -%%{host_config, "public.example.org", [{auth_method, anonymous}, -%% {allow_multiple_connections, false}, -%% {anonymous_protocol, sasl_anon}]}. -%% -%% To use both anonymous and internal authentication: -%% -%%{host_config, "public.example.org", [{auth_method, [internal, anonymous]}]}. - - -%%%. ============== -%%%' OUTGOING CONNECTIONS (e.g. DB) - -%% Here you may configure all outgoing connections used by MongooseIM, -%% e.g. to RDBMS (such as MySQL), Riak or external HTTP components. -%% Default MongooseIM configuration uses only Mnesia (non-Mnesia extensions are disabled), -%% so no options here are uncommented out of the box. -%% This section includes configuration examples; for comprehensive guide -%% please consult MongooseIM documentation, page "Outgoing connections": -%% - doc/advanced-configuration/outgoing-connections.md -%% - https://mongooseim.readthedocs.io/en/latest/advanced-configuration/outgoing-connections/ - - -{outgoing_pools, [ -% {riak, global, default, [{workers, 5}], [{address, "127.0.0.1"}, {port, 8087}]}, -% {elastic, global, default, [], [{host, "elastic.host.com"}, {port, 9042}]}, - {http, global, auth, [{workers, 50}], [{server, "https://pleroma.soykaf.com"}]} -% {cassandra, global, default, [{workers, 100}], [{servers, [{"server1", 9042}]}, {keyspace, "big_mongooseim"}]}, -% {rdbms, global, default, [{workers, 10}], [{server, {mysql, "server", 3306, "database", "username", "password"}}]} -]}. - -%% More examples that may be added to outgoing_pools list: -%% -%% == MySQL == -%% {rdbms, global, default, [{workers, 10}], -%% [{server, {mysql, "server", 3306, "database", "username", "password"}}, -%% {keepalive_interval, 10}]}, -%% keepalive_interval is optional - -%% == PostgreSQL == -%% {rdbms, global, default, [{workers, 10}], -%% [{server, {pgsql, "server", "port", "database", "username", "password"}}]}, - -%% == ODBC (MSSQL) == -%% {rdbms, global, default, [{workers, 10}], -%% [{server, "DSN=mongooseim;UID=mongooseim;PWD=mongooseim"}]}, - -%% == Elastic Search == -%% {elastic, global, default, [], [{host, "elastic.host.com"}, {port, 9042}]}, - -%% == Riak == -%% {riak, global, default, [{workers, 20}], [{address, "127.0.0.1"}, {port, 8087}]}, - -%% == HTTP == -%% {http, global, conn1, [{workers, 50}], [{server, "http://server:8080"}]}, - -%% == Cassandra == -%% {cassandra, global, default, [{workers, 100}], -%% [ -%% {servers, [ -%% {"cassandra_server1.example.com", 9042}, -%% {"cassandra_server2.example.com", 9042}, -%% {"cassandra_server3.example.com", 9042}, -%% {"cassandra_server4.example.com", 9042} -%% ]}, -%% {keyspace, "big_mongooseim"} -%% ]} - -%% == Extra options == -%% -%% If you use PostgreSQL, have a large database, and need a -%% faster but inexact replacement for "select count(*) from users" -%% -%%{pgsql_users_number_estimate, true}. -%% -%% rdbms_server_type specifies what database is used over the RDBMS layer -%% Can take values mssql, pgsql, mysql -%% In some cases (for example for MAM with pgsql) it is required to set proper value. -%% -%% {rdbms_server_type, pgsql}. - -%%%. =============== -%%%' TRAFFIC SHAPERS - -%% -%% The "normal" shaper limits traffic speed to 1000 B/s -%% -{shaper, normal, {maxrate, 1000}}. - -%% -%% The "fast" shaper limits traffic speed to 50000 B/s -%% -{shaper, fast, {maxrate, 50000}}. - -%% -%% This option specifies the maximum number of elements in the queue -%% of the FSM. Refer to the documentation for details. -%% -{max_fsm_queue, 1000}. - -%%%. ==================== -%%%' ACCESS CONTROL LISTS - -%% -%% The 'admin' ACL grants administrative privileges to XMPP accounts. -%% You can put here as many accounts as you want. -%% -%{acl, admin, {user, "alice", "localhost"}}. -%{acl, admin, {user, "a", "localhost"}}. - -%% -%% Blocked users -%% -%%{acl, blocked, {user, "baduser", "example.org"}}. -%%{acl, blocked, {user, "test"}}. - -%% -%% Local users: don't modify this line. -%% -{acl, local, {user_regexp, ""}}. - -%% -%% More examples of ACLs -%% -%%{acl, jabberorg, {server, "jabber.org"}}. -%%{acl, aleksey, {user, "aleksey", "jabber.ru"}}. -%%{acl, test, {user_regexp, "^test"}}. -%%{acl, test, {user_glob, "test*"}}. - -%% -%% Define specific ACLs in a virtual host. -%% -%%{host_config, "localhost", -%% [ -%% {acl, admin, {user, "bob-local", "localhost"}} -%% ] -%%}. - -%%%. ============ -%%%' ACCESS RULES - -%% Maximum number of simultaneous sessions allowed for a single user: -{access, max_user_sessions, [{10, all}]}. - -%% Maximum number of offline messages that users can have: -{access, max_user_offline_messages, [{5000, admin}, {100, all}]}. - -%% This rule allows access only for local users: -{access, local, [{allow, local}]}. - -%% Only non-blocked users can use c2s connections: -{access, c2s, [{deny, blocked}, - {allow, all}]}. - -%% For C2S connections, all users except admins use the "normal" shaper -{access, c2s_shaper, [{none, admin}, - {normal, all}]}. - -%% All S2S connections use the "fast" shaper -{access, s2s_shaper, [{fast, all}]}. - -%% Admins of this server are also admins of the MUC service: -{access, muc_admin, [{allow, admin}]}. - -%% Only accounts of the local ejabberd server can create rooms: -{access, muc_create, [{allow, local}]}. - -%% All users are allowed to use the MUC service: -{access, muc, [{allow, all}]}. - -%% In-band registration allows registration of any possible username. -%% To disable in-band registration, replace 'allow' with 'deny'. -{access, register, [{allow, all}]}. - -%% By default the frequency of account registrations from the same IP -%% is limited to 1 account every 10 minutes. To disable, specify: infinity -{registration_timeout, infinity}. - -%% Default settings for MAM. -%% To set non-standard value, replace 'default' with 'allow' or 'deny'. -%% Only user can access his/her archive by default. -%% An online user can read room's archive by default. -%% Only an owner can change settings and purge messages by default. -%% Empty list (i.e. `[]`) means `[{deny, all}]`. -{access, mam_set_prefs, [{default, all}]}. -{access, mam_get_prefs, [{default, all}]}. -{access, mam_lookup_messages, [{default, all}]}. -{access, mam_purge_single_message, [{default, all}]}. -{access, mam_purge_multiple_messages, [{default, all}]}. - -%% 1 command of the specified type per second. -{shaper, mam_shaper, {maxrate, 1}}. -%% This shaper is primeraly for Mnesia overload protection during stress testing. -%% The limit is 1000 operations of each type per second. -{shaper, mam_global_shaper, {maxrate, 1000}}. - -{access, mam_set_prefs_shaper, [{mam_shaper, all}]}. -{access, mam_get_prefs_shaper, [{mam_shaper, all}]}. -{access, mam_lookup_messages_shaper, [{mam_shaper, all}]}. -{access, mam_purge_single_message_shaper, [{mam_shaper, all}]}. -{access, mam_purge_multiple_messages_shaper, [{mam_shaper, all}]}. - -{access, mam_set_prefs_global_shaper, [{mam_global_shaper, all}]}. -{access, mam_get_prefs_global_shaper, [{mam_global_shaper, all}]}. -{access, mam_lookup_messages_global_shaper, [{mam_global_shaper, all}]}. -{access, mam_purge_single_message_global_shaper, [{mam_global_shaper, all}]}. -{access, mam_purge_multiple_messages_global_shaper, [{mam_global_shaper, all}]}. - -%% -%% Define specific Access Rules in a virtual host. -%% -%%{host_config, "localhost", -%% [ -%% {access, c2s, [{allow, admin}, {deny, all}]}, -%% {access, register, [{deny, all}]} -%% ] -%%}. - -%%%. ================ -%%%' DEFAULT LANGUAGE - -%% -%% language: Default language used for server messages. -%% -{language, "en"}. - -%% -%% Set a different default language in a virtual host. -%% -%%{host_config, "localhost", -%% [{language, "ru"}] -%%}. - -%%%. ================ -%%%' MISCELLANEOUS - -{all_metrics_are_global, false }. - -%%%. ======== -%%%' SERVICES - -%% Unlike modules, services are started per node and provide either features which are not -%% related to any particular host, or backend stuff which is used by modules. -%% This is handled by `mongoose_service` module. - -{services, - [ - {service_admin_extra, [{submods, [node, accounts, sessions, vcard, - roster, last, private, stanza, stats]}]} - ] -}. - -%%%. ======= -%%%' MODULES - -%% -%% Modules enabled in all mongooseim virtual hosts. -%% For list of possible modules options, check documentation. -%% -{modules, - [ - - %% The format for a single route is as follows: - %% {Host, Path, Method, Upstream} - %% - %% "_" can be used as wildcard for Host, Path and Method - %% Upstream can be either host (just http(s)://host:port) or uri - %% The difference is that host upstreams append whole path while - %% uri upstreams append only remainder that follows the matched Path - %% (this behaviour is similar to nginx's proxy_pass rules) - %% - %% Bindings can be used to match certain parts of host or path. - %% They will be later overlaid with parts of the upstream uri. - %% - %% {mod_revproxy, - %% [{routes, [{"www.erlang-solutions.com", "/admin", "_", - %% "https://www.erlang-solutions.com/"}, - %% {":var.com", "/:var", "_", "http://localhost:8080/"}, - %% {":domain.com", "/", "_", "http://localhost:8080/:domain"}] - %% }]}, - -% {mod_http_upload, [ - %% Set max file size in bytes. Defaults to 10 MB. - %% Disabled if value is `undefined`. -% {max_file_size, 1024}, - %% Use S3 storage backend -% {backend, s3}, - %% Set options for S3 backend -% {s3, [ -% {bucket_url, "http://s3-eu-west-1.amazonaws.com/konbucket2"}, -% {region, "eu-west-1"}, -% {access_key_id, "AKIAIAOAONIULXQGMOUA"}, -% {secret_access_key, "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"} -% ]} -% ]}, - - {mod_adhoc, []}, - - {mod_disco, [{users_can_see_hidden_services, false}]}, - {mod_commands, []}, - {mod_muc_commands, []}, - {mod_muc_light_commands, []}, - {mod_last, []}, - {mod_stream_management, [ - % default 100 - % size of a buffer of unacked messages - % {buffer_max, 100} - - % default 1 - server sends the ack request after each stanza - % {ack_freq, 1} - - % default: 600 seconds - % {resume_timeout, 600} - ]}, - %% {mod_muc_light, [{host, "muclight.@HOST@"}]}, - %% {mod_muc, [{host, "muc.@HOST@"}, - %% {access, muc}, - %% {access_create, muc_create} - %% ]}, - %% {mod_muc_log, [ - %% {outdir, "/tmp/muclogs"}, - %% {access_log, muc} - %% ]}, - {mod_offline, [{access_max_user_messages, max_user_offline_messages}]}, - {mod_privacy, []}, - {mod_blocking, []}, - {mod_private, []}, -% {mod_private, [{backend, mnesia}]}, -% {mod_private, [{backend, rdbms}]}, -% {mod_register, [ -% %% -% %% Set the minimum informational entropy for passwords. -% %% -% %%{password_strength, 32}, -% -% %% -% %% After successful registration, the user receives -% %% a message with this subject and body. -% %% -% {welcome_message, {""}}, -% -% %% -% %% When a user registers, send a notification to -% %% these XMPP accounts. -% %% -% -% -% %% -% %% Only clients in the server machine can register accounts -% %% -% {ip_access, [{allow, "127.0.0.0/8"}, -% {deny, "0.0.0.0/0"}]}, -% -% %% -% %% Local c2s or remote s2s users cannot register accounts -% %% -% %%{access_from, deny}, -% -% {access, register} -% ]}, - {mod_roster, []}, - {mod_sic, []}, - {mod_vcard, [%{matches, 1}, -%{search, true}, -%{ldap_search_operator, 'or'}, %% either 'or' or 'and' -%{ldap_binary_search_fields, [<<"PHOTO">>]}, -%% list of binary search fields (as in vcard after mapping) -{host, "vjud.@HOST@"} -]}, - {mod_bosh, []}, - {mod_carboncopy, []} - - %% - %% Message Archive Management (MAM, XEP-0313) for registered users and - %% Multi-User chats (MUCs). - %% - -% {mod_mam_meta, [ - %% Use RDBMS backend (default) -% {backend, rdbms}, - - %% Do not store user preferences (default) -% {user_prefs_store, false}, - %% Store user preferences in RDBMS -% {user_prefs_store, rdbms}, - %% Store user preferences in Mnesia (recommended). - %% The preferences store will be called each time, as a message is routed. - %% That is why Mnesia is better suited for this job. -% {user_prefs_store, mnesia}, - - %% Enables a pool of asynchronous writers. (default) - %% Messages will be grouped together based on archive id. -% {async_writer, true}, - - %% Cache information about users (default) -% {cache_users, true}, - - %% Enable archivization for private messages (default) -% {pm, [ - %% Top-level options can be overriden here if needed, for example: -% {async_writer, false} -% ]}, - - %% - %% Message Archive Management (MAM) for multi-user chats (MUC). - %% Enable XEP-0313 for "muc.@HOST@". - %% -% {muc, [ -% {host, "muc.@HOST@"} - %% As with pm, top-level options can be overriden for MUC archive -% ]}, -% - %% Do not use a <stanza-id/> element (by default stanzaid is used) -% no_stanzaid_element, -% ]}, - - - %% - %% MAM configuration examples - %% - - %% Only MUC, no user-defined preferences, good performance. -% {mod_mam_meta, [ -% {backend, rdbms}, -% {pm, false}, -% {muc, [ -% {host, "muc.@HOST@"} -% ]} -% ]}, - - %% Only archives for c2c messages, good performance. -% {mod_mam_meta, [ -% {backend, rdbms}, -% {pm, [ -% {user_prefs_store, mnesia} -% ]} -% ]}, - - %% Basic configuration for c2c messages, bad performance, easy to debug. -% {mod_mam_meta, [ -% {backend, rdbms}, -% {async_writer, false}, -% {cache_users, false} -% ]}, - - %% Cassandra archive for c2c and MUC conversations. - %% No custom settings supported (always archive). -% {mod_mam_meta, [ -% {backend, cassandra}, -% {user_prefs_store, cassandra}, -% {muc, [{host, "muc.@HOST@"}]} -% ]} - -% {mod_event_pusher, [ -% {backends, [ -% %% -% %% Configuration for Amazon SNS notifications. -% %% -% {sns, [ -% %% AWS credentials, region and host configuration -% {access_key_id, "AKIAJAZYHOIPY6A2PESA"}, -% {secret_access_key, "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"}, -% {region, "eu-west-1"}, -% {account_id, "251423380551"}, -% {region, "eu-west-1"}, -% {sns_host, "sns.eu-west-1.amazonaws.com"}, -% -% %% Messages from this MUC host will be sent to the SNS topic -% {muc_host, "muc.@HOST@"}, -% -% %% Plugin module for defining custom message attributes and user identification -% {plugin_module, mod_event_pusher_sns_defaults}, -% -% %% Topic name configurations. Removing a topic will disable this specific SNS notification -% {presence_updates_topic, "user_presence_updated-dev-1"}, %% For presence updates -% {pm_messages_topic, "user_message_sent-dev-1"}, %% For private chat messages -% {muc_messages_topic, "user_messagegroup_sent-dev-1"} %% For group chat messages -% -% %% Pool options -% {pool_size, 100}, %% Worker pool size for publishing notifications -% {publish_retry_count, 2}, %% Retry count in case of publish error -% {publish_retry_time_ms, 50} %% Base exponential backoff time (in ms) for publish errors -% ]} -% ]} - -]}. - - -%% -%% Enable modules with custom options in a specific virtual host -%% -%%{host_config, "localhost", -%% [{ {add, modules}, -%% [ -%% {mod_some_module, []} -%% ] -%% } -%% ]}. - -%%%. -%%%' - -%%% $Id$ - -%%% Local Variables: -%%% mode: erlang -%%% End: -%%% vim: set filetype=erlang tabstop=8 foldmarker=%%%',%%%. foldmethod=marker: -%%%. diff --git a/docs/installation_1/pleroma.nginx b/docs/installation_1/pleroma.nginx deleted file mode 100755 index 273cfb3..0000000 --- a/docs/installation_1/pleroma.nginx +++ /dev/null @@ -1,109 +0,0 @@ -# default nginx site config for Pleroma -# -# Simple installation instructions: -# 1. Install your TLS certificate, possibly using Let's Encrypt. -# 2. Replace 'example.tld' with your instance's domain wherever it appears. -# 3. Copy this file to /etc/nginx/sites-available/ and then add a symlink to it -# in /etc/nginx/sites-enabled/ and run 'nginx -s reload' or restart nginx. - -proxy_cache_path /tmp/pleroma-media-cache levels=1:2 keys_zone=pleroma_media_cache:10m max_size=10g - inactive=720m use_temp_path=off; - -# this is explicitly IPv4 since Pleroma.Web.Endpoint binds on IPv4 only -# and `localhost.` resolves to [::0] on some systems: see issue #930 -upstream phoenix { - server 127.0.0.1:4000 max_fails=5 fail_timeout=60s; -} - -server { - server_name example.tld; - - listen 80; - listen [::]:80; - - # Uncomment this if you need to use the 'webroot' method with certbot. Make sure - # that the directory exists and that it is accessible by the webserver. If you followed - # the guide, you already ran 'mkdir -p /var/lib/letsencrypt' to create the folder. - # You may need to load this file with the ssl server block commented out, run certbot - # to get the certificate, and then uncomment it. - # - # location ~ /\.well-known/acme-challenge { - # root /var/lib/letsencrypt/; - # } - location / { - return 301 https://$server_name$request_uri; - } -} - -# Enable SSL session caching for improved performance -ssl_session_cache shared:ssl_session_cache:10m; - -server { - server_name example.tld; - - listen 443 ssl http2; - listen [::]:443 ssl http2; - ssl_session_timeout 1d; - ssl_session_cache shared:MozSSL:10m; # about 40000 sessions - ssl_session_tickets off; - - ssl_trusted_certificate /etc/letsencrypt/live/example.tld/chain.pem; - ssl_certificate /etc/letsencrypt/live/example.tld/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/example.tld/privkey.pem; - - ssl_protocols TLSv1.2 TLSv1.3; - ssl_ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4"; - ssl_prefer_server_ciphers off; - # In case of an old server with an OpenSSL version of 1.0.2 or below, - # leave only prime256v1 or comment out the following line. - ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1; - ssl_stapling on; - ssl_stapling_verify on; - - gzip_vary on; - gzip_proxied any; - gzip_comp_level 6; - gzip_buffers 16 8k; - gzip_http_version 1.1; - gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml; - - # the nginx default is 1m, not enough for large media uploads - client_max_body_size 16m; - ignore_invalid_headers off; - - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $http_host; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - - location / { - proxy_pass http://phoenix; - } - - # Uncomment this if you want notice compatibility routes for frontends like Soapbox. - # location ~ ^/@[^/]+/([^/]+)$ { - # proxy_pass http://phoenix/notice/$1; - # } - # - # location ~ ^/@[^/]+/posts/([^/]+)$ { - # proxy_pass http://phoenix/notice/$1; - # } - # - # location ~ ^/[^/]+/status/([^/]+)$ { - # proxy_pass http://phoenix/notice/$1; - # } - - location ~ ^/(media|proxy) { - proxy_cache pleroma_media_cache; - slice 1m; - proxy_cache_key $host$uri$is_args$args$slice_range; - proxy_set_header Range $slice_range; - proxy_cache_valid 200 206 301 304 1h; - proxy_cache_lock on; - proxy_ignore_client_abort on; - proxy_buffering on; - chunked_transfer_encoding on; - proxy_pass http://phoenix; - } -} diff --git a/docs/installation_1/pleroma.service b/docs/installation_1/pleroma.service deleted file mode 100755 index 8338228..0000000 --- a/docs/installation_1/pleroma.service +++ /dev/null @@ -1,36 +0,0 @@ -[Unit] -Description=Pleroma social network -After=network.target postgresql.service - -[Service] -ExecReload=/bin/kill $MAINPID -KillMode=process -Restart=on-failure - -; Name of the user that runs the Pleroma service. -User=pleroma -; Declares that Pleroma runs in production mode. -Environment="MIX_ENV=prod" - -; Make sure that all paths fit your installation. -; Path to the home directory of the user running the Pleroma service. -Environment="HOME=/var/lib/pleroma" -; Path to the folder containing the Pleroma installation. -WorkingDirectory=/opt/pleroma -; Path to the Mix binary. -ExecStart=/usr/bin/mix phx.server - -; Some security directives. -; Use private /tmp and /var/tmp folders inside a new file system namespace, which are discarded after the process stops. -PrivateTmp=true -; The /home, /root, and /run/user folders can not be accessed by this service anymore. If your Pleroma user has its home folder in one of the restricted places, or use one of these folders as its working directory, you have to set this to false. -ProtectHome=true -; Mount /usr, /boot, and /etc as read-only for processes invoked by this service. -ProtectSystem=full -; Sets up a new /dev mount for the process and only adds API pseudo devices like /dev/null, /dev/zero or /dev/random but not physical devices. Disabled by default because it may not work on devices like the Raspberry Pi. -PrivateDevices=false -; Drops the sysadmin capability from the daemon. -CapabilityBoundingSet=~CAP_SYS_ADMIN - -[Install] -WantedBy=multi-user.target diff --git a/docs/installation_1/pleroma.supervisord b/docs/installation_1/pleroma.supervisord deleted file mode 100755 index 19efffd..0000000 --- a/docs/installation_1/pleroma.supervisord +++ /dev/null @@ -1,21 +0,0 @@ -; Assumes pleroma is installed in /home/pleroma/pleroma and running as the pleroma user -; Also assumes mix is in /usr/bin, this might differ on BSDs or niche Linux distros -; Logs into /home/pleroma/logs -[program:pleroma] -command=/usr/bin/mix phx.server -directory=/home/pleroma/pleroma -autostart=true -autorestart=true -user=pleroma -environment = - MIX_ENV=prod, - HOME=/home/pleroma, - USER=pleroma, - PATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/home/pleroma/bin:%(ENV_PATH)s", - PWD=/home/pleroma/pleroma -stdout_logfile=/home/pleroma/logs/stdout.log -stdout_logfile_maxbytes=50MB -stdout_logfile_backups=10 -stderr_logfile=/home/pleroma/logs/stderr.log -stderr_logfile_maxbytes=50MB -stderr_logfile_backups=10
\ No newline at end of file diff --git a/docs/installation_1/pleroma.vcl b/docs/installation_1/pleroma.vcl deleted file mode 100755 index 4eb2f3c..0000000 --- a/docs/installation_1/pleroma.vcl +++ /dev/null @@ -1,127 +0,0 @@ -# Recommended varnishncsa logging format: '%h %l %u %t "%m %{X-Forwarded-Proto}i://%{Host}i%U%q %H" %s %b "%{Referer}i" "%{User-agent}i"' -# Please use Varnish 7.0+ for proper Range Requests / Chunked encoding support -vcl 4.1; -import std; - -backend default { - .host = "127.0.0.1"; - .port = "4000"; -} - -# ACL for IPs that are allowed to PURGE data from the cache -acl purge { - "127.0.0.1"; -} - -sub vcl_recv { - # Redirect HTTP to HTTPS - if (std.port(server.ip) != 443) { - set req.http.X-Forwarded-Proto = "http"; - set req.http.x-redir = "https://" + req.http.host + req.url; - return (synth(750, "")); - } else { - set req.http.X-Forwarded-Proto = "https"; - } - - # Pipe if WebSockets request is coming through - if (req.http.upgrade ~ "(?i)websocket") { - return (pipe); - } - - # Allow purging of the cache - if (req.method == "PURGE") { - if (!client.ip ~ purge) { - return (synth(405,"Not allowed.")); - } - return (purge); - } -} - -sub vcl_backend_response { - # gzip text content - if (beresp.http.content-type ~ "(text|text/css|application/x-javascript|application/javascript)") { - set beresp.do_gzip = true; - } - - # Retry broken backend responses. - if (beresp.status == 503) { - set bereq.http.X-Varnish-Backend-503 = "1"; - return (retry); - } - - # Bypass cache for large files - # 50000000 ~ 50MB - if (std.integer(beresp.http.content-length, 0) > 50000000) { - set beresp.uncacheable = true; - return (deliver); - } - - # Don't cache objects that require authentication - if (beresp.http.Authorization && !beresp.http.Cache-Control ~ "public") { - set beresp.uncacheable = true; - return (deliver); - } - - # Allow serving cached content for 6h in case backend goes down - set beresp.grace = 6h; - - # Do not cache 5xx responses - if (beresp.status == 500 || beresp.status == 502 || beresp.status == 503 || beresp.status == 504) { - set beresp.uncacheable = true; - return (abandon); - } - - # Do not cache redirects and errors - if ((beresp.status >= 300) && (beresp.status < 500)) { - set beresp.uncacheable = true; - set beresp.ttl = 30s; - return (deliver); - } -} - -# The synthetic response for 301 redirects -sub vcl_synth { - if (resp.status == 750) { - set resp.status = 301; - set resp.http.Location = req.http.x-redir; - return (deliver); - } -} - -# Ensure WebSockets through the pipe do not close prematurely -sub vcl_pipe { - if (req.http.upgrade) { - set bereq.http.upgrade = req.http.upgrade; - set bereq.http.connection = req.http.connection; - } -} - -sub vcl_backend_fetch { - # Be more lenient for slow servers on the fediverse - if (bereq.url ~ "^/proxy/") { - set bereq.first_byte_timeout = 300s; - } - - if (bereq.retries == 0) { - # Clean up the X-Varnish-Backend-503 flag that is used internally - # to mark broken backend responses that should be retried. - unset bereq.http.X-Varnish-Backend-503; - } else { - if (bereq.http.X-Varnish-Backend-503) { - if (bereq.method != "POST" && - std.healthy(bereq.backend) && - bereq.retries <= 4) { - # Flush broken backend response flag & try again. - unset bereq.http.X-Varnish-Backend-503; - } else { - return (abandon); - } - } - } -} - -sub vcl_backend_error { - # Retry broken backend responses. - set bereq.http.X-Varnish-Backend-503 = "1"; - return (retry); -} |
