+
+Here is some content
", + "reblog":null, + "account":{ + "id":"123454321", + "username":"cheeseperson", + "acct":"cheeseperson@someothermastodonsite.com", + "display_name":"cheeseperson", + "locked":false, + "bot":false, + "discoverable":false, + "group":false, + "created_at":"2023-08-20T00:00:00.000Z", + "note":"", + "url":"https://someothermastodonsite.com/@cheeseperson", + "uri":"https://someothermastodonsite.com/users/cheeseperson", + "avatar":"https://someothermastadonsite.com/avatars/original/missing.png", + "avatar_static":"https://someothermastadonsite.com/avatars/original/missing.png", + "header":"locationofheader.com/image.jpg", + "header_static":"locationofheader.com/image.jpg", + "followers_count":2, + "following_count":2, + "statuses_count":95, + "last_status_at":"2023-10-26", + "emojis":[ + + ], + "fields":[ + + ] + }, + "media_attachments":[ + + ], + "mentions":[ + { + "id":"101010101010", + "username":"thirdperson", + "url":"https://thirdpersonsinstance.com/@thirdperson", + "acct":"thirdperson@emailwebsite.com" + } + ], + "tags":[ + + ], + "emojis":[ + + ], + "card":null, + "poll":null + } + ], + "rules":[ + { + "id":"2", + "text":"Don't be a meanie!" + } + ] + } +} + + +``` diff --git a/content/en/admin/optional.md b/content/en/admin/optional.md index 3439f0a1..2b15bae7 100644 --- a/content/en/admin/optional.md +++ b/content/en/admin/optional.md @@ -9,6 +9,6 @@ menu: Mastodon offers a few optional features that can be used if needed. -- [Full-text search](./elasticsearch/) +- [Object storage](./object-storage/) - [Hidden services](./tor/) - [Single Sign On](./sso/) diff --git a/content/en/admin/optional/elasticsearch.md b/content/en/admin/optional/elasticsearch.md deleted file mode 100644 index e6c52bf6..00000000 --- a/content/en/admin/optional/elasticsearch.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Full-text search -description: Setting up ElasticSearch to search for statuses authored, favourited, or mentioned in. -menu: - docs: - weight: 10 - parent: admin-optional ---- - -Mastodon supports full-text search when ElasticSearch is available. Mastodon’s full-text search allows logged in users to find results from their own statuses, their mentions, their favourites, and their bookmarks. It deliberately does not allow searching for arbitrary strings in the entire database. - -## Installing ElasticSearch {#install} - -ElasticSearch requires a Java runtime. If you don’t have Java already installed, do it now. Assuming you are logged in as `root`: - -```bash -apt install openjdk-17-jre-headless -``` - -Add the official ElasticSearch repository to apt: - -```bash -wget -O /usr/share/keyrings/elasticsearch.asc https://artifacts.elastic.co/GPG-KEY-elasticsearch -echo "deb [signed-by=/usr/share/keyrings/elasticsearch.asc] https://artifacts.elastic.co/packages/7.x/apt stable main" > /etc/apt/sources.list.d/elastic-7.x.list -``` - -Now you can install ElasticSearch: - -```bash -apt update -apt install elasticsearch -``` - -{{< hint style="warning" >}} -**Security warning:** By default, ElasticSearch is supposed to bind to localhost only, i.e. be inaccessible from the outside network. You can check which address ElasticSearch binds to by looking at `network.host` within `/etc/elasticsearch/elasticsearch.yml`. Consider that anyone who can access ElasticSearch can access and modify any data within it, as there is no authentication layer. So it’s really important that the access is secured. Having a firewall that only exposes the 22, 80 and 443 ports is advisable, as outlined in the [main installation instructions](../../prerequisites/#install-a-firewall-and-only-whitelist-ssh-http-and-https-ports). If you have a multi-host setup, you must know how to secure internal traffic. -{{< /hint >}} - -{{< hint style="danger" >}} -**Security warning:** ElasticSearch versions between `2.0` and `2.14.1` are affected by an [exploit](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228) in the `log4j` library. If affected, please refer to the [temporary mitigation](https://github.com/elastic/elasticsearch/issues/81618#issuecomment-991000240) from the ElasticSearch issue tracker. -{{< /hint >}} - -To start ElasticSearch: - -```bash -systemctl daemon-reload -systemctl enable --now elasticsearch -``` - -## Configuring Mastodon {#config} - -Edit `.env.production` to add the following variables: - -```bash -ES_ENABLED=true -ES_HOST=localhost -ES_PORT=9200 -``` - -If you have multiple Mastodon servers on the same machine, and you are planning to use the same ElasticSearch installation for all of them, make sure that all of them have unique `REDIS_NAMESPACE` in their configurations, to differentiate the indices. If you need to override the prefix of the ElasticSearch indices, you can set `ES_PREFIX` directly. - -After saving the new configuration, restart Mastodon processes for it to take effect: - -```bash -systemctl restart mastodon-sidekiq -systemctl reload mastodon-web -``` - -Now it's time to create the ElasticSearch indices and fill them with data: - -```bash -su - mastodon -cd live -RAILS_ENV=production bin/tootctl search deploy -``` - -## Search optimization for other languages -### Chinese search optimization {#chinese-search-optimization} - -The default analyzer of the ElasticSearch is the standard analyzer, which may not be the best especially for Chinese. To improve search experience, you can install a language specific analyzer. Before creating the indices in ElasticSearch, install the following ElasticSearch extensions: - -- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik) -- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert) - -And then modify Mastodon's index definition as follows: - -```diff -diff --git a/app/chewy/accounts_index.rb b/app/chewy/accounts_index.rb ---- a/app/chewy/accounts_index.rb -+++ b/app/chewy/accounts_index.rb -@@ -4,7 +4,7 @@ class AccountsIndex < Chewy::Index - settings index: { refresh_interval: '5m' }, analysis: { - analyzer: { - content: { -- tokenizer: 'whitespace', -+ tokenizer: 'ik_max_word', - filter: %w(lowercase asciifolding cjk_width), - }, - -diff --git a/app/chewy/statuses_index.rb b/app/chewy/statuses_index.rb ---- a/app/chewy/statuses_index.rb -+++ b/app/chewy/statuses_index.rb -@@ -16,9 +16,17 @@ class StatusesIndex < Chewy::Index - language: 'possessive_english', - }, - }, -+ char_filter: { -+ tsconvert: { -+ type: 'stconvert', -+ keep_both: false, -+ delimiter: '#', -+ convert_type: 't2s', -+ }, -+ }, - analyzer: { - content: { -- tokenizer: 'uax_url_email', -+ tokenizer: 'ik_max_word', - filter: %w( - english_possessive_stemmer - lowercase -@@ -27,6 +35,7 @@ class StatusesIndex < Chewy::Index - english_stop - english_stemmer - ), -+ char_filter: %w(tsconvert), - }, - }, - } -diff --git a/app/chewy/tags_index.rb b/app/chewy/tags_index.rb ---- a/app/chewy/tags_index.rb -+++ b/app/chewy/tags_index.rb -@@ -2,10 +2,19 @@ - - class TagsIndex < Chewy::Index - settings index: { refresh_interval: '15m' }, analysis: { -+ char_filter: { -+ tsconvert: { -+ type: 'stconvert', -+ keep_both: false, -+ delimiter: '#', -+ convert_type: 't2s', -+ }, -+ }, - analyzer: { - content: { -- tokenizer: 'keyword', -+ tokenizer: 'ik_max_word', - filter: %w(lowercase asciifolding cjk_width), -+ char_filter: %w(tsconvert), - }, - - edge_ngram: { -``` - diff --git a/content/en/admin/optional/object-storage-proxy.md b/content/en/admin/optional/object-storage-proxy.md index b29842cc..66ad68b6 100644 --- a/content/en/admin/optional/object-storage-proxy.md +++ b/content/en/admin/optional/object-storage-proxy.md @@ -3,12 +3,12 @@ title: Proxying object storage through nginx description: Serving user-uploaded files in Mastodon from your own domain --- -When you are using Mastodon with an object storage provider like Amazon S3, Wasabi, Google Cloud or other, by default the URLs of the files go through the storage providers themselves. This has the following downsides: +When you are using Mastodon with an object storage provider like Amazon S3, Wasabi, Google Cloud or others, by default the URLs of the files go through the storage providers themselves. This has the following downsides: - Bandwidth is usually metered and very expensive - URLs will be broken if you decide to switch providers later -You can instead serve the files from your own domain, caching them in the process. Access patterns on Mastodon are such that **new files are usually accessed simultaneously by a lot of clients** as new posts stream in through the streaming API or as they get distributed through federation; older content is accessed comparatively rarely. For that reason, caching alone would not reduce bandwidth consumed by your proxy from the actual object storage. To mitigate this, we can use a **cache lock** mechanism that ensures that only one proxy request is made at the same time. +You can choose to serve the files from your own domain, incorporating caching in the process. In Mastodon, access patterns show that new files are often simultaneously accessed by many clients as they appear in new posts via the streaming API or are shared through federation; in contrast, older content is accessed less frequently. Therefore, relying solely on caching won't significantly reduce the bandwidth usage of your proxy from the actual object storage. To address this, we can implement a cache lock mechanism, which ensures that only one proxy request is made at a time. Here is an example nginx configuration that accomplishes this: @@ -19,6 +19,9 @@ server { server_name files.example.com; root /var/www/html; + ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; + ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key; + keepalive_timeout 30; location = / { @@ -37,7 +40,7 @@ server { } resolver 8.8.8.8; - proxy_set_header Host YOUR_S3_HOSTNAME; + proxy_set_header Host YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME; proxy_set_header Connection ''; proxy_set_header Authorization ''; proxy_hide_header Set-Cookie; @@ -63,6 +66,8 @@ server { add_header Cache-Control public; add_header 'Access-Control-Allow-Origin' '*'; add_header X-Cache-Status $upstream_cache_status; + add_header X-Content-Type-Options nosniff; + add_header Content-Security-Policy "default-src 'none'; form-action 'none'"; } } ``` @@ -97,7 +102,7 @@ ln -s /etc/nginx/sites-available/files.example.com /etc/nginx/sites-enabled/ systemctl reload nginx ``` -You'll also want to get a SSL certificate for it: +You'll also want to get an SSL certificate for it: ```bash certbot --nginx -d files.example.com diff --git a/content/en/admin/optional/object-storage.md b/content/en/admin/optional/object-storage.md new file mode 100644 index 00000000..3a48ae0d --- /dev/null +++ b/content/en/admin/optional/object-storage.md @@ -0,0 +1,232 @@ +--- +title: Configuring object storage +description: Serving user-uploaded files in Mastodon using external object storage +menu: + docs: + weight: 15 + parent: admin-optional +--- + +User-uploaded files can be stored on the main server's file system, or using an external object storage server, which can be required for scaling. + +## Using the filesystem {#FS} + +The simplest way to store user uploads is by using the server's file system. This is how it works by default and is suitable for small servers. + +By default, Mastodon will store file uploads under `public/system` in its installation directory, but that can be overridden using the `PAPERCLIP_ROOT_PATH` environment variable. + +By default, the files are served at `https://your-domain/system`, which can be overridden using `PAPERCLIP_ROOT_URL` and `CDN_HOST`. + +{{< hint style="info" >}} +While using the server's file system is perfectly serviceable for small servers, using external object storage is more scalable. +{{}} + +{{< hint style="danger" >}} +The web server must be configured to serve those files but not allow listing them (that is, `https://your-domain/system/` should not return a file list). This should be the case if you use the configuration files distributed with Mastodon, but it is worth double-checking. +{{}} + +## S3-compatible object storage backends {#S3} + +Mastodon can use S3-compatible object storage backends. ACL support is recommended as it allows Mastodon to quickly make the content of temporarily suspended users unavailable, or marginally improve the security of private data. + +On Mastodon's end, you need to configure the following environment variables: +- `S3_ENABLED=true` +- `S3_BUCKET=mastodata` (replacing `mastodata` with the name of your bucket) +- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` need to be set to your credentials +- `S3_ALIAS_HOST` is optional but highly recommended in order to set up a caching proxy and not lock you to a specific provider +- `S3_REGION` +- `S3_HOSTNAME` (optional if you use Amazon AWS) +- `S3_PERMISSION` (optional, if you use a provider that does not support ACLs or want to use custom ACLs) +- `S3_FORCE_SINGLE_REQUEST=true` (optional, if you run into trouble processing large files) + +{{< page-ref page="admin/optional/object-storage-proxy.md" >}} + +{{< hint style="info" >}} +You must serve the files with CORS headers, otherwise some functions of Mastodon's web UI will not work. For example, `Access-Control-Allow-Origin: *` +{{}} + +{{< hint style="danger" >}} +Regardless of the ACL configuration, your S3 bucket must be set up to ensure that all objects are publicly readable but not writable or listable. At the same time, Mastodon itself should have write access to the bucket. This configuration is generally consistent across all S3 providers, and common ones are highlighted below. +{{}} + +### MinIO + +MinIO is an open-source implementation of an S3 object provider. This section does not cover how to install it, but how to configure a bucket for use in Mastodon. + +You need to set a policy for anonymous access that allows read-only access to objects contained by the bucket without allowing listing them. + +To do this, you need to set a custom policy (replace `mastodata` with the actual name of your S3 bucket): +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "*" + }, + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + +Mastodon itself needs to be able to write to the bucket, so either use your admin MinIO account (discouraged) or an account specific to Mastodon (recommended) with the following policy attached (replace `mastodata` with the actual name of your S3 bucket): +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:*", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + +You can set those policies from the MinIO Console (web-based user interface) or the command-line client (`mcli` / `mc`). + +#### Using the MinIO Console + +Connect to the MinIO Console web interface and create a new bucket (or navigate to your existing bucket): + + +Then, configure the “Access Policy” to a custom one that allows read access (`s3:GetObject`) without write access or the ability to list objects (see above): + + +{{< hint style="info" >}} +If the MinIO Console does not allow you to set a “Custom” policy, you will likely need to update MinIO. If you are using MinIO in *standalone* or *filesystem* mode, [`RELEASE.2022-10-24T18-35-07Z`](https://github.com/minio/minio/releases/tag/RELEASE.2022-10-24T18-35-07Z) should be a safe version to update to that does not require [an involved migration procedure](https://min.io/docs/minio/linux/operations/install-deploy-manage/migrate-fs-gateway.html#migrate-from-gateway-or-filesystem-mode). +{{< /hint >}} + +Create a new `mastodon-readwrite` policy (see above): + + +Finally, create a new `mastodon` user with the `mastodon-readwrite` policy: + + +#### Using the command-line utility + +The same can be achieved using the [MinIO Client](https://min.io/docs/minio/linux/reference/minio-mc.html) command-line utility (which can be called `mc` or `mcli` depending on where it is installed from). + +Create a new bucket: +`mc mb myminio/mastodata` + +Save the anonymous access policy from above as `anonymous-readonly-policy.json` and the Mastodon user access policy as `mastodon-readwrite.json` (make sure to replace `mastodata` with the name of your newly-created bucket). + +Set the anonymous access policy for your bucket: +`mc anonymous set-json anonymous-readonly-policy.json myminio/mastodata` + +Add a `mastodon-readwrite` policy: +`mc admin policy add myminio mastodon-readwrite mastodon-readwrite.json` + +Add the `mastodon` user (replace the password): +`mc admin user add myminio mastodon SECRET_PASSWORD` + +Apply the `mastodon-readwrite` policy to the `mastodon` user: +`mc admin policy set myminio mastodon-readwrite user=mastodon` + +### Wasabi Object Storage + +Create a new bucket and define its policy to allow objects to be anonymously readable but not listable: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "*" + }, + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + + + +{{< hint style="info" >}} +If you are using an old bucket, ensure you are not giving “Everyone” read access to objects through Wasabi's legacy Access Control settings, as that allows listing objects and take precedence over the IAM policy defined above. + + +{{< /hint >}} + +Then, create a `mastodon-readwrite` policy to grant read and write access to your bucket: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:*", + "Resource": "arn:aws:s3:::mastodata/*" + } + ] +} +``` + + + +Finally, create a new `mastodon` user and don't forget to enable the `mastodon-readwrite` policy: + + +On Mastodon's side, you need to set `S3_FORCE_SINGLE_REQUEST=true` to properly handle large uploads. + +### DigitalOcean Spaces + +In your DigitalOcean Spaces Bucket, make sure that “File Listing” is “Restricted” to users with access keys. + + + +### Scaleway + +If you want to use Scaleway Object Storage, we strongly recommend you create a Scaleway project dedicated to your Mastodon instance assets and use a custom IAM policy. + +First, create a new Scaleway project, in which you create your object storage bucket. You need to set your bucket visibility to "Private" to not allow objects to be listed. + + + +Now that your bucket is created, you need to create API keys to be used in your Mastodon instance configuration. + +Head to the IAM settings (in your organization menu, top right of the screen), and create a new IAM policy (eg `mastodon-media-access`) + + + +This policy needs to have one rule, allowing it to read, write and delete objects in the Scaleway project you created above (the scope). + + + +Then head to the IAM Applications page, and create a new one (eg `my-mastodon-instance`) and select the policy you created above. + +Finally, click on the application you just created, then "API Keys", and create a new API key to use in your instance configuration. You should use the "Yes, set up preferred Project" option and select the project you created above as the default project for this key. + + + +Copy the Access Key ID and Secret, and use them for your `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` Mastodon config variables. + +### Exoscale + +In Exoscale, your bucket should not have any read ACLs (Mastodon will set the ACLs on the object themselves as appropriate). + +You need to create an API Key for the Mastodon app, restricted to the Object Storage (`sos`) service, restricted to your bucket, and with unrestricted operations. + + + +On Mastodon's side, you need to set `S3_FORCE_SINGLE_REQUEST=true` to properly handle large uploads. + +### Cloudflare R2 + +Cloudflare R2 does not support ACLs, so Mastodon needs to be instructed not to try setting them. To do that, set the `S3_PERMISSION` environment variable to an empty string. + +{{< hint style="warning" >}} +Without support for ACLs, media files from temporarily-suspended users will remain accessible. +{{< /hint >}} + +To get credentials for use in Mastodon, select “Manage R2 API Tokens” and create a new API token with “Edit” permissions. + +{{< hint style="warning" >}} +This section is currently under construction. +{{< /hint >}} diff --git a/content/en/admin/optional/tor.md b/content/en/admin/optional/tor.md index 67c1d795..d4e2efc6 100644 --- a/content/en/admin/optional/tor.md +++ b/content/en/admin/optional/tor.md @@ -1,6 +1,6 @@ --- -title: Hidden services -description: Serving Mastodon through TOR hidden services. +title: Onion services +description: Serving Mastodon through Tor onion services. menu: docs: weight: 20 @@ -36,24 +36,24 @@ apt install tor deb.torproject.org-keyring Edit the file at `/etc/tor/torrc` and add the following configuration. ```text -HiddenServiceDir /var/lib/tor/hidden_service/ +HiddenServiceDir /var/lib/tor/onion_service/ HiddenServiceVersion 3 HiddenServicePort 80 127.0.0.1:80 ``` -Restart tor. +Restart Tor. ```bash sudo service tor restart ``` -Your tor hostname can now be found at `/var/lib/tor/hidden_service/hostname`. +You can now find your Tor hostname in `/var/lib/tor/hidden_service/hostname`. ## Move your Mastodon configuration {#nginx} -We will need to tell Nginx about your Mastodon configuration twice. To keep things [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) we need to move the Mastodon configuration into its own file that can be referenced. +We will need to tell Nginx about your Mastodon configuration twice. To keep things ["DRY"](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) we need to move the Mastodon configuration into its own file that can we can refer to later. -Create a new file at `/etc/nginx/snippets/mastodon.conf`. Put all of your Mastodon configuration parameters in this file with the exception of the `listen`, `server_name`, `include` and all of the SSL options. Your new file may look something like this. +Create a new file at `/etc/nginx/snippets/mastodon.conf`. Copy every Mastodon configuration parameter, apart from the `listen`, `server_name`, `include` directives, as well as all of the SSL options. Your new file should look somewhat like this: ```nginx add_header Referrer-Policy "same-origin"; @@ -72,14 +72,14 @@ access_log /var/log/nginx/mastodon_access.log; error_log /var/log/nginx/mastodon_error.log warn; ``` -In place of your old Mastodon configuration add an include directive to this new configuration file. +In the new configuration file, add an include directive in the place of where your Mastodon configurations were. -Your Nginx configuration file will be left looking something like this. +Your Nginx configuration file should now look a bit like this: ```nginx server { listen 80; - server_name mastodon.myhosting.com; + server_name mastodon.example.com; return 301 https://$server_name$request_uri; } @@ -91,19 +91,21 @@ map $http_upgrade $connection_upgrade { server { listen 443 ssl http2; list [::]:443 ssl http2; - server_name mastodon.myhosting.com; + server_name mastodon.example.com; include /etc/nginx/snippets/mastodon.conf; - ssl_certificate /etc/letsencrypt/live/mastodon.myhosting.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/mastodon.myhosting.com/privkey.pem; + ssl_certificate /etc/letsencrypt/live/mastodon.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/mastodon.example.com/privkey.pem; } ``` ## Serve Tor over http {#http} -While it may be tempting to serve your Tor version of Mastodon over https it is not a good idea for most people. See [this](https://blog.torproject.org/facebook-hidden-services-and-https-certs) blog post from the Tor Project about why https certificates do not add value. Since you cannot get an SSL cert for an onion domain, you will also be plagued with certificate errors when trying to use your Mastodon instance. A Tor developer has more recently spelled out the reasons why serving a Tor service over https is not beneficial for most use cases [here](https://matt.traudt.xyz/posts/2017-12-02-dont-https-your-onions/). +This section assumes that you want to expose your instance on both Tor and the public Internet *simultaneously*. -The solution is to serve your Mastodon instance over http, but only for Tor. This can be added by prepending an additional configuration to your Nginx configuration. +While it may be tempting to serve your Tor version of Mastodon over HTTPS, it isn't always ideal. They are mostly useful for large companies that can produce their own certificates with their own company information. There is no Certificate Authority (CA) that provides them [for free](https://community.torproject.org/onion-services/advanced/https/), and there is also [a blog post from the Tor Project](https://blog.torproject.org/facebook-hidden-services-and-https-certs) explains why HTTPS certificates are not really beneficial for security. On the other hand, however, Mastodon uses a lot of redirects to the HTTPS version of your site, where the presence of a validated certificate may make it easier for your users to use your instance on Tor without having to manually remove the `https://` prefix in URLs. + +In this section, we will go over how to serve your Mastodon instance over HTTP, but for Tor **only**. This can be added by prepending an additional configuration to your existing Nginx configuration. ```nginx server { @@ -114,7 +116,7 @@ server { server { listen 80; - server_name mastodon.myhosting.com; + server_name mastodon.example.com; return 301 https://$server_name$request_uri; } @@ -126,19 +128,19 @@ map $http_upgrade $connection_upgrade { server { listen 443 ssl http2; list [::]:443 ssl http2; - server_name mastodon.myhosting.com; + server_name mastodon.example.com; include /etc/nginx/snippets/mastodon.conf; - ssl_certificate /etc/letsencrypt/live/mastodon.myhosting.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/mastodon.myhosting.com/privkey.pem; + ssl_certificate /etc/letsencrypt/live/mastodon.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/mastodon.example.com/privkey.pem; } ``` Replace the long hash provided here with your Tor domain located in the file at `/var/lib/tor/hidden_service/hostname`. -Note that the onion hostname has been prefixed with “mastodon.”. Your Tor address acts a wildcard domain. All subdomains will be routed through, and you can configure Nginx to respond to any subdomain you wish. If you do not wish to host any other services on your tor address you can omit the subdomain, or choose a different subdomain. +Note that the onion hostname has been prefixed with “mastodon.”. Your Tor address acts as a wildcard domain. All subdomains will be routed through, and you can configure Nginx to respond to any subdomain you wish. If you do not wish to host any other services on your tor address you can omit the subdomain, or choose a different subdomain. -Here you can see the payoff of moving your mastodon configurations to a different file. Without this all of your configurations would have to be copied to both places. Any change to your configuration would have to be made both places. +Here you can see the payoff of moving your mastodon configurations to a different file. Without this, all of your configurations would have to be copied to both places. Any change to your configuration would have to be made in both places. Restart your web server. @@ -148,7 +150,7 @@ service nginx restart ## Gotchas {#gotchas} -There are a few things you will need to be aware of. Certain redirects will push your users to https. They will have to manually replace the URL with http to continue. - -Various resources, such as images, will still be offered through your regular non-Tor domain. How much of a problem this is will depend greatly on your user’s level of caution. +There are a few things you will need to be aware of. +- As mentioned earlier, certain URLs in the Mastodon frontend will force your users to a HTTPS URL. They will have to manually replace the URL with HTTP to continue. +- Various resources, such as images, will **still** be offered through your regular clearnet domain. This could possibly be a problem, depending on how cautious your users want, try or need to be. diff --git a/content/en/admin/prerequisites.md b/content/en/admin/prerequisites.md index d2457599..691d53b0 100644 --- a/content/en/admin/prerequisites.md +++ b/content/en/admin/prerequisites.md @@ -10,7 +10,7 @@ If you are setting up a fresh machine, it is recommended that you secure it firs ## Do not allow password-based SSH login (keys only) -First make sure you are actually logging in to the server using keys and not via a password, otherwise this will lock you out. Many hosting providers support uploading a public key and automatically set up key-based root login on new machines for you. +First, make sure you are actually logging in to the server using keys and not via a password, otherwise, this will lock you out. Many hosting providers support uploading a public key and automatically set up key-based root login on new machines for you. Edit `/etc/ssh/sshd_config` and find `PasswordAuthentication`. Make sure it’s uncommented and set to `no`. If you made any changes, restart sshd: @@ -42,13 +42,10 @@ sendername = Fail2Ban [sshd] enabled = true port = 22 - -[sshd-ddos] -enabled = true -port = 22 +mode = aggressive ``` -Finally restart fail2ban: +Finally, restart fail2ban: ```bash systemctl restart fail2ban @@ -56,7 +53,7 @@ systemctl restart fail2ban ## Install a firewall and only allow SSH, HTTP and HTTPS ports -First, install iptables-persistent. During installation it will ask you if you want to keep current rules–decline. +First, install iptables-persistent. During installation, it will ask you if you want to keep the current rules–decline. ```bash apt install -y iptables-persistent @@ -80,6 +77,8 @@ Edit `/etc/iptables/rules.v4` and put this inside: # Allow HTTP and HTTPS connections from anywhere (the normal ports for websites and SSL). -A INPUT -p tcp --dport 80 -j ACCEPT -A INPUT -p tcp --dport 443 -j ACCEPT +# (optional) Allow HTTP/3 connections from anywhere. +-A INPUT -p udp --dport 443 -j ACCEPT # Allow SSH connections # The -dport number should be the same port number you set in sshd_config @@ -124,6 +123,8 @@ If your server is also reachable over IPv6, edit `/etc/iptables/rules.v6` and ad # Allow HTTP and HTTPS connections from anywhere (the normal ports for websites and SSL). -A INPUT -p tcp --dport 80 -j ACCEPT -A INPUT -p tcp --dport 443 -j ACCEPT +# (optional) Allow HTTP/3 connections from anywhere. +-A INPUT -p udp --dport 443 -j ACCEPT # Allow SSH connections # The -dport number should be the same port number you set in sshd_config diff --git a/content/en/admin/roles.md b/content/en/admin/roles.md new file mode 100644 index 00000000..079ebdfb --- /dev/null +++ b/content/en/admin/roles.md @@ -0,0 +1,98 @@ +--- +title: Roles +description: Management of roles from the admin dashboard. +menu: + docs: + parent: admin +--- + +# Roles {#roles} +When the database is seeded, roles are derived from the values present in [`~/config/roles.yml`](https://github.com/mastodon/mastodon/blob/main/config/roles.yml). + +{{< page-ref page="entities/Role" >}} + +The resultant [default roles](#default-roles) are `Owner`, `Admin`, and `Moderator`. + +A role and its attributes can be created using [Add role](#add-role), present on the *Roles* (`/admin/roles`) page. + + + +An existing role's attributes can be changed using the [edit role](#edit-role) feature. + +## Default roles {#default-roles} +### Base role (*Default permissions*) {#default-base-role} + +Affects all users, including users without an assigned role. + +The only permission flag that can be altered for this role is **Invite Users**. Enabling this permission allows all users to send invitations. + +The base role has a priority of `0`, and this value cannot be altered. + +### Owner {#default-owner-role} + +A role that is assigned the **Administrator** permission flag, bypassing all permissions. Users with the owner role have every [permission flag](/entities/Role/#permission-flags) enabled. + +The role's *Name*, *Badge color*, and *Display badge* attributes can be changed. No permissions can be edited / revoked from this role. + +The owner role has the highest [priority](#role-priority) of any role (`1000`). The owner can modify any other role attributes. No role can be created which supersedes the owner role, as [role priority](#role-priority) for new and existing roles must be <= `999`. + +### Admin {#default-admin-role} + +A role that is assigned all **Moderation** and **Administration** permission flags. + +The **DevOps** permission flag for this role is disabled, but can be enabled by an **Owner** (or a custom role with a higher priority value). + +The role's *Name*, *Badge color*, and *Display badge* attributes can be changed. + +The admin role has a priority of `100`. + +### Moderator {#default-moderator-role} + +A role that is assigned certain **Moderation** permission flags. These include... +- **View Dashboard** +- **View Audit Log** +- **Manage Users** +- **Manage Reports** +- **Manage Taxonomies** + +The role's *Name*, *Badge color*, and *Display badge* attributes can be changed. + +The moderator role has a priority of `10`. + +## Add Role {#add-role} + +The `admin/roles/new` page allows for the creation of a custom role. + + + +### Input Fields {#add-role-input-fields} + +{{< page-relref ref="entities/Role#name" caption="Name">}} + +Duplicate role names can exist. They are discerned in the database by their `id`, which cannot be set from the web interface. + +{{< page-relref ref="entities/Role#color" caption="Badge color">}} + +### Priority {#role-priority} + +- Defaults to `0` + - Cannot be > `999` + - Can be any negative integer value +- Two roles can have the same priority value + +> "Higher role decides conflict resolution in certain situations. Certain actions can only be performed on roles with a lower priority." + +{{< page-relref ref="entities/Role#highlighted" caption="Display role as badge on user profiles">}} + +{{< page-relref ref="entities/Role#permissions" caption="Permissions">}} + + +## Edit role {#edit-role} + + + +An existing role and its attributes can be edited using *Edit* in the role list. [Input fields](#add-role-input-fields) can be changed and saved, just as they can when creating a new role. The role can also be deleted using this form. + + + +A logged in user with permission to **Manage Roles** will always be able to see every role, but cannot modify roles that exceed or are equal to their assigned role's [priority](#role-priority). \ No newline at end of file diff --git a/content/en/admin/scaling.md b/content/en/admin/scaling.md index 3494d69c..434fa1f6 100644 --- a/content/en/admin/scaling.md +++ b/content/en/admin/scaling.md @@ -11,18 +11,18 @@ menu: Mastodon has three types of processes: -* Web (Puma) -* Streaming API -* Background processing (Sidekiq) +- Web (Puma) +- Streaming API +- Background processing (Sidekiq) ### Web (Puma) {#web} The web process serves short-lived HTTP requests for most of the application. The following environment variables control it: -* `WEB_CONCURRENCY` controls the number of worker processes -* `MAX_THREADS` controls the number of threads per process +- `WEB_CONCURRENCY` controls the number of worker processes +- `MAX_THREADS` controls the number of threads per process -Threads share the memory of their parent process. Different processes allocate their own memory, though they share some memory via copy-on-write. A larger number of threads maxes out your CPU first, a larger number of processes maxes out your RAM first. +Threads share the memory of their parent process. Different processes allocate their own memory, though they share some memory via copy-on-write. A larger number of threads maxes out your CPU first, and a larger number of processes maxes out your RAM first. These values affect how many HTTP requests can be served at the same time. @@ -32,10 +32,53 @@ In terms of throughput, more processes are better than more threads. The streaming API handles long-lived HTTP and WebSockets connections, through which clients receive real-time updates. The following environment variables control it: -* `STREAMING_CLUSTER_NUM` controls the number of worker processes -* `STREAMING_API_BASE_URL` controls the base URL of the streaming API +- `STREAMING_API_BASE_URL` controls the base URL of the streaming API +- `PORT` controls the port the streaming server will listen on, by default 4000. The `BIND` and `SOCKET` environment variables are also able to be used. +- Additionally, the shared [database](/admin/config#postgresql) and [redis](/admin/config#redis) environment variables are used. -One process can handle a reasonably high number of connections. The streaming API can be hosted on a different subdomain if you want to e.g. avoid the overhead of nginx proxying the connections. +The streaming API can use a different subdomain if you want to by setting `STREAMING_API_BASE_URL`. This allows you to have one load balancer for streaming and one for web/API requests. However, this also requires applications to correctly request the streaming URL from the [instance endpoint](/methods/instance/#v2), instead of assuming that it's hosted on the same host as the Web API. + +One process of the streaming server can handle a reasonably high number of connections and throughput, but if you find that a single process isn't handling your instance's load, you can run multiple processes by varying the `PORT` number of each, and then using nginx to load balance traffic to each of those instances. For example, a community of about 50,000 accounts with 10,000-20,000 monthly active accounts, you'll typically have an average concurrent load of about 800-1200 streaming connections. + +The streaming server also exposes a [Prometheus](https://prometheus.io/) endpoint on `/metrics` with a lot of metrics to help you understand the current load on your mastodon streaming server, some key metrics are: + +* `mastodon_streaming_connected_clients`: This is the number of connected clients, tagged by client type (websocket or eventsource) +* `mastodon_streaming_connected_channels`: This is the number of "channels" that are currently subscribed (note that this is much higher than connected clients due to how our internal "system" channels currently work) +* `mastodon_streaming_messages_sent_total`: This is the total number of messages sent to clients since last restart. +* `mastodon_streaming_redis_messages_received_total`: This is the number of messages received from Redis pubsub, and intended to complement [monitoring Redis directly](https://sysdig.com/blog/redis-prometheus/). + +{{< hint style="info" >}} +The more streaming server processes that you run, the more database connections will be consumed on PostgreSQL, so you'll likely want to use PgBouncer, as documented below. +{{< /hint >}} + +An example nginx configuration to route traffic to three different processes on `PORT` 4000, 4001, and 4002 is as follows: + +``` +upstream streaming { + least_conn; + server 127.0.0.1:4000 fail_timeout=0; + server 127.0.0.1:4001 fail_timeout=0; + server 127.0.0.1:4002 fail_timeout=0; +} +``` + +If you're using the distributed systemd files, then you can start up multiple streaming servers with the following commands: + +``` +$ sudo systemctl start mastodon-streaming@4000.service +$ sudo systemctl start mastodon-streaming@4001.service +$ sudo systemctl start mastodon-streaming@4002.service +``` + +By default, `sudo systemctl start mastodon-streaming` starts just one process on port 4000, equivalent to running `sudo systemctl start mastodon-streaming@4000.service`. + +{{< hint style="warning" >}} +Previous versions of Mastodon had a `STREAMING_CLUSTER_NUM` environment variable that made the streaming server use clustering, which started mulitple workers processes and used node.js to load balance them. + +This interacted with the other settings in ways which made capacity planning difficult, especially when it comes to database connections and CPU resources. By default the streaming server would consume resources on all available CPUs which could cause contention with other software running on that server. Another common issue was that misconfiguring the `STREAMING_CLUSTER_NUM` would exhaust your database connections by opening up a connection pool per cluster worker process, so a `STREAMING_CLUSTER_NUM` of `5` and `DB_POOL` of `10` would potentially consume 50 database connections. + +Now a single streaming server process will only use at maximum `DB_POOL` PostgreSQL connections, and scaling is handled by running more instances of the streaming server. +{{< /hint >}} ### Background processing (Sidekiq) {#sidekiq} @@ -45,26 +88,26 @@ Many tasks in Mastodon are delegated to background processing to ensure the HTTP While the amount of threads in the web process affects the responsiveness of the Mastodon instance to the end-user, the amount of threads allocated to background processing affects how quickly posts can be delivered from the author to anyone else, how soon e-mails are sent out, etc. -The amount of threads is not controlled by an environment variable in this case, but a command line argument in the invocation of Sidekiq, e.g.: +The number of threads is not regulated by an environment variable, but rather through a command line argument when invoking Sidekiq, as shown in the following example: ```bash bundle exec sidekiq -c 15 ``` -Would start the sidekiq process with 15 threads. Please mind that each threads needs to be able to connect to the database, which means that the database pool needs to be large enough to support all the threads. The database pool size is controlled with the `DB_POOL` environment variable and must be at least the same as the number of threads. +This would initiate the Sidekiq process with 15 threads. It's important to note that each thread requires a database connection, necessitating a sufficiently large database pool. The size of this pool is managed by the DB_POOL environment variable, which should be set to a value at least equal to the number of threads. #### Queues {#sidekiq-queues} Sidekiq uses different queues for tasks of varying importance, where importance is defined by how much it would impact the user experience of your server’s local users if the queue wasn’t working, in order of descending importance: -| Queue | Significance | -| :--- | :--- | -| `default` | All tasks that affect local users | -| `push` | Delivery of payloads to other servers | -| `mailers` | Delivery of e-mails | -| `pull` | Lower priority tasks such as handling imports, backups, resolving threads, deleting users, forwarding replies | -| `scheduler` | Doing cron jobs like refreshing trending hashtags and cleaning up logs | -| `ingress` | Incoming remote activities. Lower priority than the default queue so local users still see their posts when the server is under load | +| Queue | Significance | +| :---------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| `default` | All tasks that affect local users | +| `push` | Delivery of payloads to other servers | +| `mailers` | Delivery of e-mails | +| `pull` | Lower priority tasks such as handling imports, backups, resolving threads, deleting users, forwarding replies | +| `scheduler` | Doing cron jobs like refreshing trending hashtags and cleaning up logs | +| `ingress` | Incoming remote activities. Lower priority than the default queue so local users still see their posts when the server is under load | The default queues and their priorities are stored in [config/sidekiq.yml](https://github.com/mastodon/mastodon/blob/main/config/sidekiq.yml), but can be overridden by the command-line invocation of Sidekiq, e.g.: @@ -74,20 +117,19 @@ bundle exec sidekiq -q default To run just the `default` queue. -The way Sidekiq works with queues, it first checks for tasks from the first queue, and if there are none, checks the next queue. This means, if the first queue is overfilled, the other queues will lag behind. +Sidekiq processes queues by first checking for tasks in the first queue, and if it finds none, it then checks the subsequent queue. Consequently, if the first queue is overfilled, tasks in the other queues may experience delays. As a solution, it is possible to start different Sidekiq processes for the queues to ensure truly parallel execution, by e.g. creating multiple systemd services for Sidekiq with different arguments. **Make sure you only have one `scheduler` queue running!!** - -## Transaction pooling with pgBouncer {#pgbouncer} +## Transaction pooling with PgBouncer {#pgbouncer} ### Why you might need PgBouncer {#pgbouncer-why} -If you start running out of available Postgres connections (the default is 100) then you may find PgBouncer to be a good solution. This document describes some common gotchas as well as good configuration defaults for Mastodon. +If you start running out of available PostgreSQL connections (the default is 100) then you may find PgBouncer to be a good solution. This document describes some common gotchas as well as good configuration defaults for Mastodon. -Note that you can check “PgHero” in the administration view to see how many Postgres connections are currently being used. Typically Mastodon uses as many connections as there are threads both in Puma, Sidekiq and the streaming API combined. +User roles with `DevOps` permissions in Mastodon can monitor the current usage of PostgreSQL connections through the PgHero link in the Administration view. Generally, the number of connections open is equal to the total threads in Puma, Sidekiq, and the streaming API combined. ### Installing PgBouncer {#pgbouncer-install} @@ -101,7 +143,7 @@ sudo apt install pgbouncer #### Setting a password {#pgbouncer-password} -First off, if your `mastodon` user in Postgres is set up without a password, you will need to set a password. +First off, if your `mastodon` user in PostgreSQL is set up without a password, you will need to set a password. Here’s how you might reset the password: @@ -145,20 +187,20 @@ You’ll also want to create a `pgbouncer` admin user to log in to the PgBouncer "pgbouncer" "md5a45753afaca0db833a6f7c7b2864b9d9" ``` -In both cases the password is just `password`. +In both cases, the password is just `password`. #### Configuring pgbouncer.ini {#pgbouncer-ini} Edit `/etc/pgbouncer/pgbouncer.ini` -Add a line under `[databases]` listing the Postgres databases you want to connect to. Here we’ll just have PgBouncer use the same username/password and database name to connect to the underlying Postgres database: +Add a line under `[databases]` listing the PostgreSQL databases you want to connect to. Here we’ll just have PgBouncer use the same username/password and database name to connect to the underlying PostgreSQL database: ```text [databases] mastodon_production = host=127.0.0.1 port=5432 dbname=mastodon_production user=mastodon password=password ``` -The `listen_addr` and `listen_port` tells PgBouncer which address/port to accept connections. The defaults are fine: +The `listen_addr` and `listen_port` tell PgBouncer which address/port to accept connections. The defaults are fine: ```text listen_addr = 127.0.0.1 @@ -167,11 +209,23 @@ listen_port = 6432 Put `md5` as the `auth_type` (assuming you’re using the md5 format in `userlist.txt`): +```ini +auth_type = md5 +``` + Make sure the `pgbouncer` user is an admin: -**This next part is very important!** The default pooling mode is session-based, but for Mastodon we want transaction-based. In other words, a Postgres connection is created when a transaction is created and dropped when the transaction is done. So you’ll want to change the `pool_mode` from `session` to `transaction`: +```ini +admin_users = pgbouncer +``` -Next up, `max_client_conn` defines how many connections PgBouncer itself will accept, and `default_pool_size` puts a limit on how many Postgres connections will be opened under the hood. (In PgHero the number of connections reported will correspond to `default_pool_size` because it has no knowledge of PgBouncer.) +Mastodon requires a different pooling mode than the default session-based one. Specifically, it needs a transaction-based pooling mode. This means that a PostgreSQL connection is established at the start of a transaction and terminated upon its completion. Therefore, it's essential to change the `pool_mode` setting from `session` to `transaction`: + +```ini +pool_mode = transaction +``` + +Next up, `max_client_conn` defines how many connections PgBouncer itself will accept, and `default_pool_size` puts a limit on how many PostgreSQL connections will be opened under the hood. (In PgHero the number of connections reported will correspond to `default_pool_size` because it has no knowledge of PgBouncer.) The defaults are fine to start, and you can always increase them later: @@ -180,7 +234,7 @@ max_client_conn = 100 default_pool_size = 20 ``` -Don’t forget to reload or restart pgbouncer after making your changes: +Don’t forget to reload or restart PgBouncer after making your changes: ```bash sudo systemctl reload pgbouncer @@ -188,13 +242,13 @@ sudo systemctl reload pgbouncer #### Debugging that it all works {#pgbouncer-debug} -You should be able to connect to PgBouncer just like you would with Postgres: +You should be able to connect to PgBouncer just like you would with PostgreSQL: ```bash psql -p 6432 -U mastodon mastodon_production ``` -And then use your password to log in. +Then use your password to log in. You can also check the PgBouncer logs like so: @@ -212,7 +266,7 @@ PREPARED_STATEMENTS=false Since we’re using transaction-based pooling, we can’t use prepared statements. -Next up, configure Mastodon to use port 6432 (PgBouncer) instead of 5432 (Postgres) and you should be good to go: +Next up, configure Mastodon to use port 6432 (PgBouncer) instead of 5432 (PostgreSQL) and you should be good to go: ```bash DB_HOST=localhost @@ -223,7 +277,7 @@ DB_PORT=6432 ``` {{< hint style="warning" >}} -You cannot use pgBouncer to perform `db:migrate` tasks. But this is easy to work around. If your postgres and pgbouncer are on the same host, it can be as simple as defining `DB_PORT=5432` together with `RAILS_ENV=production` when calling the task, for example: `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` (you can specify `DB_HOST` too if it’s different, etc) +You cannot use PgBouncer to perform `db:migrate` tasks. But this is easy to work around. If your PostgreSQL and PgBouncer are on the same host, it can be as simple as defining `DB_PORT=5432` together with `RAILS_ENV=production` when calling the task, for example: `RAILS_ENV=production DB_PORT=5432 bundle exec rails db:migrate` (you can specify `DB_HOST` too if it’s different, etc) {{< /hint >}} #### Administering PgBouncer {#pgbouncer-admin} @@ -250,18 +304,87 @@ Then use `\q` to quit. ## Separate Redis for cache {#redis} -Redis is used widely throughout the application, but some uses are more important than others. Home feeds, list feeds, and Sidekiq queues as well as the streaming API are backed by Redis and that’s important data you wouldn’t want to lose (even though the loss can be survived, unlike the loss of the PostgreSQL database - never lose that!). However, Redis is also used for volatile cache. If you are at a stage of scaling up where you are worried if your Redis can handle everything, you can use a different Redis database for the cache. In the environment, you can specify `CACHE_REDIS_URL` or individual parts like `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the cache prefix. +Redis is used widely throughout the application, but some uses are more important than others. Home feeds, list feeds, and Sidekiq queues as well as the streaming API are backed by Redis and that’s important data you wouldn’t want to lose (even though the loss can be survived, unlike the loss of the PostgreSQL database - never lose that!). However, Redis is also used for volatile cache. If you are at a stage of scaling up where you are worried about whether your Redis can handle everything, you can use a different Redis database for the cache. In the environment, you can specify `CACHE_REDIS_URL` or individual parts like `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the cache prefix. -As far as configuring the Redis database goes, basically you can get rid of background saving to disk, since it doesn’t matter if the data gets lost on restart and you can save some disk I/O on that. You can also add a maximum memory limit and a key eviction policy, for that, see this guide: [Using Redis as an LRU cache](https://redis.io/topics/lru-cache) +Additionally, Redis is used for volatile caching. If you're scaling up and concerned about Redis's capacity to handle the load, you can allocate a separate Redis database specifically for caching. To do this, set `CACHE_REDIS_URL` in the environment, or define individual components such as `CACHE_REDIS_HOST`, `CACHE_REDIS_PORT`, etc. + +Unspecified components will default to their values without the cache prefix. + +When configuring the Redis database for caching, it's possible to disable background saving to disk, as data loss on restart is not critical in this context, and this can save some disk I/O. Additionally, consider setting a maximum memory limit and implementing a key eviction policy. For more details on these configurations, refer to this guide:[Using Redis as an LRU cache](https://redis.io/topics/lru-cache) + +## Seperate Redis for Sidekiq {#redis-sidekiq} + +Redis is used in Sidekiq to keep track of its locks and queue. Although in general the performance gain is not that big, some instances may benefit from having a seperate Redis instance for Sidekiq. + +In the environment file, you can specify `SIDEKIQ_REDIS_URL` or individual parts like `SIDEKIQ_REDIS_HOST`, `SIDEKIQ_REDIS_PORT` etc. Unspecified parts fallback to the same values as without the `SIDEKIQ_` prefix. + +Creating a seperate Redis instance for Sidekiq is relatively simple: + +Start by making a copy of the default redis systemd service: +```bash +cp /etc/systemd/system/redis.service /etc/systemd/system/redis-sidekiq.service +``` + +In the `redis-sidekiq.service` file, change the following values: +```bash +ExecStart=/usr/bin/redis-server /etc/redis/redis-sidekiq.conf --supervised systemd --daemonize no +PIDFile=/run/redis/redis-server-sidekiq.pid +ReadWritePaths=-/var/lib/redis-sidekiq +Alias=redis-sidekiq.service +``` + +Make a copy of the Redis configuration file for the new Sidekiq Redis instance + +```bash +cp /etc/redis/redis.conf /etc/redis/redis-sidekiq.conf +``` + +In this `redis-sidekiq.conf` file, change the following values: +```bash +port 6479 +pidfile /var/run/redis/redis-server-sidekiq.pid +logfile /var/log/redis/redis-server-sidekiq.log +dir /var/lib/redis-sidekiq +``` + +Before starting the new Redis instance, create a data directory: + +```bash +mkdir /var/lib/redis-sidekiq +chown redis /var/lib/redis-sidekiq +``` + +Start the new Redis instance: + +```bash +systemctl enable --now redis-sidekiq +``` + +Update your environment, add the following line: + +```bash +SIDEKIQ_REDIS_URL=redis://127.0.0.1:6479/ +``` + +Restart Mastodon to use the new Redis instance, make sure to restart both web and Sidekiq (otherwise, one of them will still be working from the wrong instance): + +```bash +systemctl restart mastodon-web.service +systemctl restart redis-sidekiq.service +``` ## Read-replicas {#read-replicas} -To reduce the load on your Postgresql server, you may wish to setup hot streaming replication (read replica). [See this guide for an example](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). You can make use of the replica in Mastodon in these ways: +To reduce the load on your PostgreSQL server, you may wish to set up hot streaming replication (read replica). [See this guide for an example](https://cloud.google.com/community/tutorials/setting-up-postgres-hot-standby). You can make use of the replica in Mastodon in these ways: -* The streaming API server does not issue writes at all, so you can connect it straight to the replica. But it’s not querying the database very often anyway so the impact of this is little. -* Use the Makara driver in the web and sidekiq processes, so that writes go to the master database, while reads go to the replica. Let’s talk about that. +* The streaming API server does not issue writes at all, so you can connect it straight to the replica (it is not querying the database very often anyway, so the impact of this is small). +* Use the Makara driver in the web and Sidekiq processes, so that writes go to the master database, while reads go to the replica. Let’s talk about that. -You will have to edit the `config/database.yml` file and replace the `production` section as follows: +{{< hint style="warning" >}} +Read replicas are currently not supported for the Sidekiq processes, and using them will lead to failing jobs and data loss. +{{< /hint >}} + +You will have to use a separate `config/database.yml` file for the web processes and edit it to replace the `production` section as follows: ```yaml production: @@ -279,9 +402,25 @@ production: url: postgresql://db_user:db_password@db_host:db_port/db_name ``` -Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed pgBouncer with configuration to connect to two different servers based on database name, e.g. “mastodon” going to master, “mastodon_replica” going to the replica, so in the file above both URLs would point to the local pgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be setup! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml). +Make sure the URLs point to wherever your PostgreSQL servers are. You can add multiple replicas. You could have a locally installed PgBouncer with a configuration to connect to two different servers based on the database name, e.g. “mastodon” going to the primary, “mastodon_replica” going to the replica, so in the file above both URLs would point to the local PgBouncer with the same user, password, host and port, but different database name. There are many possibilities how this could be set up! For more information on Makara, [see their documentation](https://github.com/taskrabbit/makara#databaseyml). {{< hint style="warning" >}} -Sidekiq cannot reliably use read-replicas because even the tiniest replication lag leads to failing jobs due to queued up records not being found. +Make sure the sidekiq processes run with the stock `config/database.yml` to avoid failing jobs and data loss! {{< /hint >}} +## Using a web load balancer + +Cloud providers like DigitalOcean, AWS, Hetzner, etc., offer virtual load balancing solutions that distribute network traffic across multiple servers, but provide a single public IP address. + +Scaling your deployment to provision multiple web/Puma servers behind one of these virtual load balancers can help provide more consistent performance by reducing the risk that a single server may become overwhelmed by user traffic, and decrease downtime when performing maintenance or upgrades. You should consult your provider documentation on how to setup and configure a load balancer, but consider that you need to configure your load balancer to monitor the health of the backend web/Puma nodes, otherwise you may send traffic to a service that is not responsive. + +The following endpoints are available to monitor for this purpose: + +- **Web/Puma:** `/health` +- **Streaming API:** `/api/v1/streaming/health` + +These endpoints should both return an HTTP status code of 200, and the text `OK` as a result. + +{{< hint style="info" >}} +You can also use these endpoints for health checks with a third-party monitoring/alerting utility. +{{< /hint >}} \ No newline at end of file diff --git a/content/en/admin/tootctl.md b/content/en/admin/tootctl.md index 73f20db1..3ae1285e 100644 --- a/content/en/admin/tootctl.md +++ b/content/en/admin/tootctl.md @@ -22,7 +22,7 @@ RAILS_ENV=production bin/tootctl help ## Base CLI -{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/cli.rb" caption="lib/cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/base.rb" caption="lib/mastodon/cli/base.rb" >}} --- @@ -32,7 +32,7 @@ RAILS_ENV=production bin/tootctl help Erase this server from the federation by broadcasting account Delete activities to all known other servers. This allows a "clean exit" from running a Mastodon server, as it leaves next to no cache behind on other servers. This command is always interactive and requires confirmation twice. -No local data is actually deleted, because emptying the database or deleting the entire VPS is faster. If you run this command then continue to operate the instance anyway, then there will be a state mismatch that might lead to glitches and issues with federation. +No local data is actually deleted because emptying the database or deleting the entire VPS is faster. If you run this command and then continue to operate the instance anyway, then there will be a state mismatch that might lead to glitches and issues with federation. {{< hint style="danger" >}} **Make sure you know exactly what you are doing before running this command.** This operation is NOT reversible, and it can take a long time. The server will be in a BROKEN STATE after this command finishes. A running Sidekiq process is required, so do not shut down the server until the queues are fully cleared. @@ -61,7 +61,7 @@ Show the version of the currently running Mastodon instance. ## Accounts CLI {#accounts} -{{< caption-link url="https://github.com/mastodon/mastodon/blob/master/lib/mastodon/accounts_cli.rb" caption="lib/mastodon/accounts_cli.rb" >}} +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/lib/mastodon/cli/accounts.rb" caption="lib/mastodon/cli/accounts.rb" >}} --- @@ -86,7 +86,7 @@ Generate and broadcast new RSA keys, as part of security maintenance. ### `tootctl accounts create` {#accounts-create} -Create a new user account with given `USERNAME` and provided `--email`. +Create a new user account with the given `USERNAME` and provided `--email`. `USERNAME` : Local username for the new account. {{Hola mundo
", - "detected_source_language": "en", + "content": "Hello world
", + "spoiler_text": "Greatings ahead", + "media_attachments": [ + { + "id": 22345792, + "description": "Status author waving at the camera" + } + ], + "poll": null, + "detected_source_language": "es", "provider": "DeepL.com" } ``` +Translation of status with poll: +```json +{ + "content": "Should I stay or should I go?
", + "spoiler_text": "", + "media_attachments": [], + "poll": [ + { + "id": 34858, + "options": [ + { + "title": "Stay" + }, + { + "title": "Go" + } + ] + } + ], + "detected_source_language": "ja", + "provider": "DeepL.com" +} +``` + + ## Attributes ### `content` {#content} -**Description:** The translated text of the status.\ +**Description:** HTML-encoded translated content of the status.\ **Type:** String (HTML)\ **Version history:**\ 4.0.0 - added +### `spoiler_warning` {#spoiler_warning} + +**Description:** The translated spoiler warning of the status.\ +**Type:** String\ +**Version history:**\ +4.2.0 - added + +### `poll` {#poll} + +**Description:** The translated poll options of the status.\ +**Type:** Array\ +**Version history:**\ +4.2.0 - added + +### `media_attachments` {#media_attachments} + +**Description:** The translated media descriptions of the status.\ +**Type:** Array\ +**Version history:**\ +4.2.0 - added + ### `detected_source_language` {#detected_source_language} **Description:** The language of the source text, as auto-detected by the machine translation provider.\ diff --git a/content/en/methods/accounts.md b/content/en/methods/accounts.md index 5803a249..9882005f 100644 --- a/content/en/methods/accounts.md +++ b/content/en/methods/accounts.md @@ -313,7 +313,10 @@ Update the user's display and preferences. 1.1.1 - added\ 2.3.0 - added `locked` parameter\ 2.4.0 - added `source[privacy,sensitive]` parameters\ -2.7.0 - added `discoverable` parameter +2.4.2 - added `source[language]` parameter\ +2.7.0 - added `discoverable` parameter\ +4.1.0 - added `hide_collections` parameter\ +4.2.0 - added `indexable` parameter #### Request @@ -345,6 +348,12 @@ bot discoverable : Boolean. Whether the account should be shown in the profile directory. +hide_collections +: Boolean. Whether to hide followers and followed accounts. + +indexable +: Boolean. Whether public posts should be searchable to anyone. + fields_attributes : Hash. The profile fields to be set. Inside this hash, the key is an integer cast to a string (although the exact integer does not matter), and the value is another hash including `name` and `value`. By default, max 4 fields. @@ -745,14 +754,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than this ID +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than this ID +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than this ID +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. @@ -767,7 +776,7 @@ exclude_reblogs : Boolean. Filter out boosts from the response. pinned -: Boolean. Filter for pinned statuses only. +: Boolean. Filter for pinned statuses only. Defaults to false, which includes all statuses. Pinned statuses do not receive special priority in the order of the returned results. tagged : String. Filter for statuses using a specific hashtag. @@ -1940,7 +1949,8 @@ Find out whether a given account is followed, blocked, muted, etc. **Returns:** Array of [Relationship]({{< relref "entities/Relationship">}})\ **OAuth:** User token + `read:follows`\ **Version history:**\ -0.0.0 - added +0.0.0 - added\ +4.3.0 - added `with_suspended` parameter #### Request ##### Headers @@ -1951,7 +1961,10 @@ Authorization ##### Query parameters id[] -: Array. Check relationships for the provided account IDs. +: Array of String. Check relationships for the provided account IDs. + +with_suspended +: Boolean. Whether relationships should be returned for suspended users, defaults to false. #### Response ##### 200: OK @@ -2322,4 +2335,4 @@ Token does not have an authorized user {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/statuses_controller.rb" caption="app/controllers/api/v1/accounts/statuses_controller.rb" >}} -{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_statuses_filter.rb" caption="app/models/account_statuses_filter.rb" >}} \ No newline at end of file +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_statuses_filter.rb" caption="app/models/account_statuses_filter.rb" >}} diff --git a/content/en/methods/admin/accounts.md b/content/en/methods/admin/accounts.md index e15a1419..e53c73ed 100644 --- a/content/en/methods/admin/accounts.md +++ b/content/en/methods/admin/accounts.md @@ -3,7 +3,7 @@ title: admin/accounts API methods description: Perform moderation actions with accounts. menu: docs: - name: admin/accounts + name: accounts parent: methods-admin identifier: methods-admin-accounts aliases: [ @@ -83,14 +83,14 @@ ip staff : Boolean. Filter for staff accounts? -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts. @@ -233,14 +233,14 @@ email ip : String. Lookup users with this IP address. -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts. @@ -686,7 +686,7 @@ POST /api/v1/admin/accounts/:id/action HTTP/1.1 Perform an action against an account and log this action in the moderation history. Also resolves any open reports against this account. -**Returns:** empty object\ +**Returns:** Empty\ **OAuth:** User token + `admin:write:accounts`\ **Permissions:** Manage Users, Manage Reports\ **Version history:**\ diff --git a/content/en/methods/admin/canonical_email_blocks.md b/content/en/methods/admin/canonical_email_blocks.md index c8cacb95..cdf44a7d 100644 --- a/content/en/methods/admin/canonical_email_blocks.md +++ b/content/en/methods/admin/canonical_email_blocks.md @@ -94,6 +94,11 @@ GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1 #### Request +##### Path parameters + +:id +: {{