zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity

Added a lot of spelling fixes in the English documentation (#1350) 

* Added many spelling fixes
* Apply suggestions from code review

Co-authored-by: Michael Stanclift <mx@vmstan.com>
This commit is contained in:
Frigyes 2023-12-07 11:46:29 -08:00 committed by GitHub
parent e3d00bd75e
commit 8d26904e04
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 131 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
content/en/admin/backups.md
View File

@ -20,21 +20,21 @@ Things that need to be backed up in order of importance:
## Failure modes {#failure}
There are two failure types that people in general may guard for: The failure of the hardware, such as data corruption on the disk; and human and software error, such as wrongful deletion of particular piece of data. In this documentation, only the former type is considered.
There are two failure types that people in general may guard for: The failure of the hardware, such as data corruption on the disk; and human and software error, such as wrongful deletion of a particular piece of data. In this documentation, only the former type is considered.
A lost PostgreSQL database is complete game over. Mastodon stores all the most important data in the PostgreSQL database. If the database disappears, all the accounts, posts and followers on your server will disappear with it.
Mastodon stores all the most important data in the PostgreSQL database. The loss of the PostgreSQL database will result in the complete failure of the server, including all the accounts, their posts and followers.
If you lose application secrets, some functions of Mastodon will stop working for your users, they will be logged out, two-factor authentication will become unavailable, Web Push API subscriptions will stop working.
If you lose application secrets, some functions of Mastodon will stop working for your users, they will be logged out, two-factor authentication will become unavailable, and Web Push API subscriptions will stop working.
If you lose user-uploaded files, you will lose avatars, headers, and media attachments, but Mastodon _will_ work moving forward.
Losing the Redis database is almost harmless: The only irrecoverable data will be the contents of the Sidekiq queues and scheduled retries of previously failed jobs. The home and list feeds are stored in Redis, but can be regenerated with tootctl.
Losing the Redis database is almost harmless: The only irrecoverable data will be the contents of the Sidekiq queues and scheduled retries of previously failed jobs. The home and list feeds are stored in Redis but can be regenerated with tootctl.
The best backups are so-called off-site backups, i.e. ones that are not stored on the same machine as Mastodon itself. If the server you are hosted on goes on fire and the hard disk drive explodes, backups stored on that same hard drive won’t be of much use.
## Backing up application secrets {#env}
Application secrets are the easiest to backup, since they never change. You only need to store `.env.production` somewhere safe.
Application secrets are the easiest to back up since they never change. You only need to store `.env.production` somewhere safe.
## Backing up PostgreSQL {#postgresql}

50
content/en/admin/config.md
View File

@ -9,7 +9,7 @@ menu:
Mastodon uses environment variables as its configuration.
For convenience, it can read them from a flat file called `.env.production` in the Mastodon directory (called a "dotenv" file), but they can always be overridden by a specific process. For example, systemd service files can read environment variables from an `EnvironmentFile` or from inline definitions with `Environment`, so you can have different configuration parameters for specific services. They can also be specified when calling Mastodon from the command line.
For convenience, it can read them from a flat file called `.env.production` in the Mastodon directory (called a "dotenv" file), but they can always be overridden by a specific process. For example, systemd service files can read environment variables from an `EnvironmentFile` or inline definitions with `Environment`, so you can have different configuration parameters for specific services. They can also be specified when calling Mastodon from the command line.
## Basic {#basic}
@ -21,11 +21,11 @@ This is the unique identifier of your server in the network. It cannot be safely
#### `WEB_DOMAIN`
`WEB_DOMAIN` is an optional environment variable allowing to install Mastodon on one domain, while having the users' handles on a different domain, e.g. addressing users as `@alice@example.com` but accessing Mastodon on `mastodon.example.com`. This may be useful if your domain name is already used for a different website but you still want to use it as a Mastodon identifier because it looks better or shorter.
`WEB_DOMAIN` is an optional environment variable allowing the installation of Mastodon on one domain, while having the users' handles on a different domain, e.g. addressing users as `@alice@example.com` but accessing Mastodon on `mastodon.example.com`. This may be useful if your domain name is already used for a different website but you still want to use it as a Mastodon identifier because it looks better or shorter.
As with `LOCAL_DOMAIN`, `WEB_DOMAIN` cannot be safely changed once set, as this will confuse remote servers that knew of your previous settings and may break communication with them or make it unreliable. As the issues lie with remote servers' understanding of your accounts, re-installing Mastodon from scratch will not fix the issue. Therefore, please be extremely cautious when setting up `LOCAL_DOMAIN` and `WEB_DOMAIN`.
As with `LOCAL_DOMAIN`, `WEB_DOMAIN` cannot be safely changed once set, as this will confuse remote servers that know of your previous settings and may break communication with them or make it unreliable. As the issues lie with remote servers' understanding of your accounts, re-installing Mastodon from scratch will not fix the issue. Therefore, please be extremely cautious when setting up `LOCAL_DOMAIN` and `WEB_DOMAIN`.
To install Mastodon on `mastodon.example.com` in such a way it can serve `@alice@example.com`, set `LOCAL_DOMAIN` to `example.com` and `WEB_DOMAIN` to `mastodon.example.com`. This also requires additional configuration on the server hosting `example.com` to redirect or proxy requests to `https://example.com/.well-known/webfinger` to `https://mastodon.example.com/.well-known/webfinger`. For instance, with nginx, the configuration could look like the following:
To install Mastodon on `mastodon.example.com` in such a way it can serve `@alice@example.com`, set `LOCAL_DOMAIN` to `example.com` and `WEB_DOMAIN` to `mastodon.example.com`. This also requires additional configuration on the server hosting `example.com` to redirect requests from `https://example.com/.well-known/webfinger` to `https://mastodon.example.com/.well-known/webfinger`. For instance, with nginx, the configuration could look like the following:
```
location /.well-known/webfinger {
@ -40,7 +40,7 @@ If you have multiple domains pointed at your Mastodon server, this setting will
#### `ALLOWED_PRIVATE_ADDRESSES`
Comma-separated specific addresses/subnets allowed in outgoing HTTP queries.
Comma-separated specific addresses/subnets are allowed in outgoing HTTP queries.
#### `AUTHORIZED_FETCH`
@ -48,12 +48,12 @@ Also called "secure mode". When set to `true`, the following changes occur:
- Mastodon will stop generating linked-data signatures for public posts, which prevents them from being re-distributed efficiently but without precise control. Since a linked-data object with a signature is entirely self-contained, it can be passed around without making extra requests to the server where it originates.
- Mastodon will require HTTP signature authentication on ActivityPub representations of public posts and profiles, which are normally available without any authentication. Profiles will only return barebones technical information when no authentication is supplied.
- Prior to v4.0.0: Mastodon will require any REST/streaming API access to have a user context (i.e. having gone through an OAuth authorization screen with an active user), when normally some API endpoints are available without any authentication.
- Prior to v4.0.0: Mastodon will require any REST/streaming API access to have a user context (i.e. having gone through an OAuth authorization screen with an active user) when normally some API endpoints are available without any authentication.
As a result, through the authentication mechanism and avoiding re-distribution mechanisms that do not have your server in the loop, it becomes possible to enforce who can and cannot retrieve even public content from your server, e.g. servers whose domains you have blocked.
{{< hint style="warning" >}}
Unfortunately, secure mode is not without its drawbacks, which is why it is not enabled by default. Not all software in the fediverse can support it fully, in particular some functionality will be broken with Mastodon servers older than 3.0; you lose some useful functionality even with up-to-date servers since linked-data signatures are used to make public conversation threads more complete; and because an authentication mechanism on public content means no caching is possible, it comes with an increased computational cost.
Unfortunately, secure mode is not without its drawbacks, which is why it is not enabled by default. Not all software in the fediverse can support it fully, in particular, some functionality will be broken with Mastodon servers older than 3.0; you lose some useful functionality even with up-to-date servers since linked-data signatures are used to make public conversation threads more complete; and because an authentication mechanism on public content means no caching is possible, it comes with an increased computational cost.
{{</ hint >}}
{{< hint style="warning" >}}
@ -80,15 +80,15 @@ This setting was known as `WHITELIST_MODE` prior to 3.1.5.
#### `DISALLOW_UNAUTHENTICATED_API_ACCESS`
As of Mastodon v4.0.0, the web app is now used to render all requests, even for logged-out viewers. In order to make these views work, the web app makes public API requests in order to fetch accounts and statuses. If you would like to disallow this, then set this variable to `true`. Note that disallowing unauthenticated API access will cause profile and post permalinks to return an error to logged-out users, essentially making it so that the only ways to view content is to either log in locally or fetch it via ActivityPub.
As of Mastodon v4.0.0, the web app is now used to render all requests, even for logged-out viewers. To make these views work, the web app makes public API requests to fetch accounts and statuses. If you would like to disallow this, then set this variable to `true`. Note that disallowing unauthenticated API access will cause profile and post permalinks to return an error to logged-out users, essentially making it so that the only way to view content is to either log in locally or fetch it via ActivityPub.
#### `SINGLE_USER_MODE`
If set to `true`, the frontpage of your Mastodon server will always redirect to the first profile in the database and registrations will be disabled.
If set to `true`, the front page of your Mastodon server will always redirect to the first profile in the database and registrations will be disabled.
#### `DEFAULT_LOCALE`
By default, Mastodon will automatically detect the visitor's language from browser headers and display the Mastodon interface in that language (if it's supported). If you are running a language-specific or regional server, that behaviour may mislead visitors who do not speak your language into signing up on your server. For this reason, you may want to set this variable to a specific language.
By default, Mastodon will automatically detect the visitor's language from browser headers and display the Mastodon interface in that language (if it's supported). If you are running a language-specific or regional server, that behavior may mislead visitors who do not speak your language into signing up on your server. For this reason, you may want to set this variable to a specific language.
Example value: `de`
@ -204,7 +204,7 @@ Determines the amount of logs generated by Mastodon. Defaults to `info`, which g
Tells the Mastodon web and streaming processes which IPs act as your trusted reverse proxy (e.g. nginx, Cloudflare). It affects how Mastodon determines the source IP of each request, which is used for important rate limits and security functions. If the value is set incorrectly then Mastodon could use the IP of the reverse proxy instead of the actual source.
By default the loopback and private network address ranges are trusted. Specifically:
By default, the loopback and private network address ranges are trusted. Specifically:
- `127.0.0.1/8`
- `::1/128`
@ -311,7 +311,7 @@ Defaults to `5432`.
#### `DB_POOL`
How many database connections to pool in the process. This value should cover every thread in the process, for this reason, it defaults to the value of `MAX_THREADS`.
Defines how many database connections to pool in the process. This value should cover every thread in the process, for this reason, it defaults to the value of `MAX_THREADS`.
#### `DB_SSLMODE`
@ -345,23 +345,23 @@ Example value: `redis://user:password@localhost:6379`
#### `REDIS_NAMESPACE`
If provided, namespaces all Redis keys. This allows sharing the same Redis database between different projects or Mastodon servers.
If provided, namespaces all Redis keys. This allows the sharing of the same Redis database between different projects or Mastodon servers.
#### `CACHE_REDIS_HOST`
Defaults to value of `REDIS_HOST`.
Defaults to the value of `REDIS_HOST`.
#### `CACHE_REDIS_PORT`
Defaults to value of `REDIS_PORT`.
Defaults to the value of `REDIS_PORT`.
#### `CACHE_REDIS_URL`
If provided, takes precedence over `CACHE_REDIS_HOST` and `CACHE_REDIS_PORT`. Defaults to value of `REDIS_URL`.
If provided, takes precedence over `CACHE_REDIS_HOST` and `CACHE_REDIS_PORT`. Defaults to the value of `REDIS_URL`.
#### `CACHE_REDIS_NAMESPACE`
Defaults to value of `REDIS_NAMESPACE`.
Defaults to the value of `REDIS_NAMESPACE`.
#### `SIDEKIQ_REDIS_URL`
@ -375,7 +375,7 @@ If set to `true`, Mastodon will use Elasticsearch for its search functions.
#### `ES_PRESET`
It controls the ElasticSearch indices configuration (number of shards and replica).
It controls the Elasticsearch indices configuration (number of shards and replica).
Possible values are:
@ -383,7 +383,7 @@ Possible values are:
- `small_cluster`
- `large_cluster`
See the [ElasticSearch setup page for details on each setting](../elasticsearch#choosing-the-correct-preset).
See the [Elasticsearch setup page for details on each setting](../elasticsearch#choosing-the-correct-preset).
#### `ES_HOST`
@ -403,7 +403,7 @@ Used for optionally authenticating with Elasticsearch
#### `ES_PREFIX`
Useful if the Elasticsearch server is shared between multiple projects or different Mastodon servers. Defaults to value of `REDIS_NAMESPACE`.
Useful if the Elasticsearch server is shared between multiple projects or different Mastodon servers. Defaults to the value of `REDIS_NAMESPACE`.
### StatsD {#statsd}
@ -461,7 +461,7 @@ E-mail configuration is based on the *action_mailer* component of the *Ruby on R
### Basic configuration {#basic}
* `SMTP_SERVER`: Specify the server to use. For example `sub.domain.tld`.
* `SMTP_PORT`: By default, the value is `25` (usual port for SMTP). If StartTLS is detected, it may be switched to port 587.
* `SMTP_PORT`: By default, the value is `25` (the usual port for SMTP). If StartTLS is detected, it may be switched to port 587.
* `SMTP_DOMAIN`: Only required if a HELO domain is needed. Will be set to the `SMTP_SERVER` domain by default.
* `SMTP_FROM_ADDRESS`: Specify a sender address.
* `SMTP_DELIVERY_METHOD`: By default, the value is `smtp` (can also be `sendmail`).
@ -470,7 +470,7 @@ E-mail configuration is based on the *action_mailer* component of the *Ruby on R
* `SMTP_LOGIN`: Login for the SMTP user.
* `SMTP_PASSWORD`: Password for the SMTP user.
* `SMTP_AUTH_METHOD`: Either `plain` (default; password is transmitted in the clear), `login` (password will be base64 encoded) or `cram_md5`.
* `SMTP_AUTH_METHOD`: Either `plain` (default; the password is transmitted in the clear), `login` (password will be base64 encoded) or `cram_md5`.
### Secured SMTP
By default, a StartTLS connection will be attempted to the specified SMTP server.
@ -499,7 +499,7 @@ You must serve the files with CORS headers, otherwise some functions of Mastodon
#### `S3_ALIAS_HOST`
Similar to `CDN_HOST`, you may serve _user-uploaded_ files from a separate host. In fact, if you are using external storage like Amazon S3, Minio or Google Cloud, you will by default be serving files from those services' URLs.
Similar to `CDN_HOST`, you may serve _user-uploaded_ files from a separate host. If you are using external storage like Amazon S3, Minio or Google Cloud, you will by default be serving files from those services' URLs.
It is _extremely recommended_ to use your own host instead, for a few reasons:
@ -736,14 +736,14 @@ If set, registrations will not be possible with any e-mails **except** those fro
If set, registrations will not be possible with any e-mails from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
{{< hint style="warning" >}}
This option is deprecated. You can dynamically block e-mail domains from the admin interface or from the `tootctl` command-line interface.
This option is deprecated. You can dynamically block e-mail domains from the admin interface or the `tootctl` command-line interface.
{{</ hint >}}
### Sessions
#### `MAX_SESSION_ACTIVATIONS`
How many browser sessions are allowed per-user. Defaults to `10`. If a new browser session is created, then the oldest session is deleted, e.g. user in that browser is logged out.
Defines the maximum number of browser sessions allowed per user, which defaults to 10. If a new browser session is created and the limit is exceeded, the oldest session is deleted, resulting in the user being logged out of that session.
### Home feeds

10
content/en/admin/elasticsearch.md
View File

@ -11,8 +11,8 @@ menu:
Mastodon supports full-text search when Elasticsearch is available. It is strongly recommended to configure this feature.
Mastodon’s full-text search allows logged in users to find results from:
- public statuses from account that opted into appearing in search results
Mastodon’s full-text search allows logged-in users to find results from:
- public statuses from accounts that opted into appearing in search results
- their own statuses
- their mentions
- their favourites
@ -75,7 +75,7 @@ _Note_: If using TLS, prepend the hostname with `https://`. For example: `https:
### Choosing the correct preset
The value for `ES_PRESET` depends on the size of your Elasticsearch and will be used to set the number of shards and replica for your indices to the best value for your setup:
The value for `ES_PRESET` depends on the size of your Elasticsearch and will be used to set the number of shards and replicas for your indices to the best value for your setup:
- `single_node_cluster` if you only have one node in your Elasticsearch cluster. Indices will be configured without any replica
- `small_cluster` if you have less than 6 nodes in your cluster. Indices will be configured with 1 replica
- `large_cluster` if you have 6 or more nodes in your cluster. Indices will be configured with more shards than with the `small_cluster` setting, to allow them to be distributed over more nodes
@ -88,7 +88,7 @@ By default, Elasticsearch does not handle any authentication and every request i
To configure it, please refer [to the official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/security-minimal-setup.html). It will guide you through:
- Enabling the security features (`xpack.security.enabled: true`)
- Creating password for built-in users
- Creating passwords for built-in users
Once done, you can create a custom role for Mastodon to connect.
@ -154,7 +154,7 @@ 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:
The standard analyzer is the default for Elasticsearch, but for some languages like Chinese it may not be the optimal choice. To enhance the search experience, consider installing a language-specific analyzer. Before creating indices in Elasticsearch, be sure to install the following extensions:
- [elasticsearch-analysis-ik](https://github.com/medcl/elasticsearch-analysis-ik)
- [elasticsearch-analysis-stconvert](https://github.com/medcl/elasticsearch-analysis-stconvert)

10
content/en/admin/install.md
View File

@ -17,7 +17,7 @@ You will be running the commands as root. If you aren’t already root, switch t
### System repositories {#system-repositories}
Make sure curl, wget, gnupg, apt-transport-https, lsb-release and ca-certificates is installed first:
Make sure curl, wget, gnupg, apt-transport-https, lsb-release and ca-certificates are installed first:
```bash
apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates
@ -58,7 +58,7 @@ yarn set version classic
### Installing Ruby {#installing-ruby}
We will be using rbenv to manage Ruby versions, because it’s easier to get the right versions and to update once a newer release comes out. rbenv must be installed for a single Linux user, therefore, first we must create the user Mastodon will be running as:
We will use rbenv to manage Ruby versions as it simplifies obtaining the correct versions and updating them when new releases are available. Since rbenv needs to be installed for an individual Linux user, we must first create the user account under which Mastodon will run:
```bash
adduser --disabled-login mastodon
@ -87,7 +87,7 @@ RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.2
rbenv global 3.2.2
```
We’ll also need to install bundler:
We’ll also need to install the bundler:
```bash
gem install bundler --no-document
@ -180,7 +180,7 @@ You’re done with the mastodon user for now, so switch back to root:
exit
```
### Acquiring a SSL certificate {#acquiring-a-ssl-certificate}
### Acquiring an SSL certificate {#acquiring-a-ssl-certificate}
We’ll use Let’s Encrypt to get a free SSL certificate:
@ -209,7 +209,7 @@ Reload nginx for the changes to take effect:
systemctl reload nginx
```
At this point you should be able to visit your domain in the browser and see the elephant hitting the computer screen error page. This is because we haven’t started the Mastodon process yet.
At this point, you should be able to visit your domain in the browser and see the elephant hitting the computer screen error page. This is because we haven’t started the Mastodon process yet.
### Setting up systemd services {#setting-up-systemd-services}

4
content/en/admin/migrating.md
View File

@ -7,7 +7,7 @@ menu:
parent: admin
---
Sometimes, for various reasons, you may want to migrate your Mastodon instance from one server to another. Fortunately this is not too difficult of a process, although it may result in some downtime.
Sometimes, for various reasons, you may want to migrate your Mastodon instance from one server to another. Fortunately, this is not too difficult of a process, although it may result in some downtime.
{{< hint style="info" >}}
This guide was written with Ubuntu Server in mind; your mileage may vary for other setups.
@ -24,7 +24,7 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
7. Run `RAILS_ENV=production ./bin/tootctl feeds build` to rebuild the home timelines for each user.
8. Start Mastodon on the new server.
9. Update your DNS settings to point to the new server.
10. Update or copy your Nginx configuration, re-run LetsEncrypt as necessary.
10. Update or copy your Nginx configuration, and re-run LetsEncrypt as necessary.
11. Enjoy your new server!
## Detailed steps {#detailed-steps}

20
content/en/admin/moderation.md
View File

@ -15,33 +15,33 @@ As of v3.5.0, all default user moderation decisions will notify the affected use
### Sensitive {#sensitive-user}
When an account is marked as sensitive, all media that user posts will be automatically [marked as sensitive](https://docs.joinmastodon.org/user/posting/#cw).
When an account is marked as sensitive, all media that the user posts will be automatically [marked as sensitive](https://docs.joinmastodon.org/user/posting/#cw).
### Freeze {#freeze-user}
A Mastodon account can be frozen. This prevents the user from doing anything with the account, but all of the content is still there untouched. This limitation is reversible; the account can be un-frozen at any time. This limitation is only available for local users on your server.
A Mastodon account can be frozen. This prevents the user from doing anything with the account, but all of the content is still there untouched. This limitation is reversible; the account can be unfrozen at any time. This limitation is only available for local users on your server.
When a user's account is frozen, they are redirected to their **Account Settings** page, where the following message is displayed:
> You can no longer login to your account or use it in any other way, but your profile and other data remains intact.
When the user's account is un-frozen, normal functionality resumes.
When the user's account is unfrozen, normal functionality resumes.
### Limit {#limit-user}
Previously known as "silencing". A limited account is hidden to all other users on that instance, except for its followers. All of the content is still there, and it can still be found via search, mentions, and following, but the content is invisible publicly.
Previously known as "silencing". A limited account is hidden from all other users on that instance, except for its followers. All of the content is still there, and it can still be found via search, mentions, and following, but the content is invisible publicly.
At this moment, limit does not affect federation. A locally limited account is *not* limited automatically on other servers. Account limitations are reversible.
### Suspend {#suspend-user}
A Mastodon suspension means the account is effectively deleted. The account no longer appears in search, the profile page is gone, all of the posts, uploads, followers, and all other data is removed publicly. However, all the data is available in the admin back-end for a period of 30 days from suspension. This is to give the user an opportunity to work with instance admins to resolve any potential issues and have the account re-instated.
A Mastodon suspension means the account is effectively deleted. The account no longer appears in search, the profile page is gone, and all of the posts, uploads, followers, and all other data are removed publicly. However, all the data is available in the admin back-end for a period of 30 days from suspension. This is to give the user an opportunity to work with instance admins to resolve any potential issues and have the account re-instated.
If the account is reinstated within the 30 day period, all data is once again accessible publicly without any adverse effects. If the 30 day period lapses, **all** that user's data is purged from the instance. Admins also have the option to immediately delete the user's account data at any point during the 30 days.
If the account is reinstated within the 30-day period, all data is once again accessible publicly without any adverse effects. If the 30-day period lapses, **all** that user's data is purged from the instance. Admins also have the option to immediately delete the user's account data at any point during the 30 days.
Once the data has been deleted, whether that is after the 30 day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (statuses, profile information, avatar or header image) associated with it.
Once the data has been deleted, whether that is after the 30-day period, or if an admin has force deleted it, the account can still be un-suspended. However, the account will have no data (statuses, profile information, avatar or header image) associated with it.
For remote accounts, suspending will make them unfollow any local account. Those relationships are not restored in case the remote account is un-suspended, even within the 30-day time window.
For remote accounts, suspending will make them unfollow any local account. Those relationships are not restored in case the remote account is unsuspended, even within the 30-day time window.
## Moderating entire websites {#server-wide-moderation}
@ -68,7 +68,7 @@ There are a few baseline measures for preventing spam in Mastodon:
* Signing up requires confirming an e-mail address
* Signing up is rate-limited by IP
However, dedicated spammers will get through that. The other measure you can employ is **e-mail domain blacklisting**. During sign up, Mastodon resolves the given e-mail address for an A or MX record, i.e. the IP address of the e-mail server, and checks that IP address against a dynamically stored blacklist.
However, dedicated spammers will get through that. The other measure you can employ is **e-mail domain blacklisting**. During sign-up, Mastodon resolves the given e-mail address for an A or MX record, i.e. the IP address of the e-mail server, and checks that IP address against a dynamically stored blacklist.
### Blocking by e-mail server {#blocking-by-e-mail-server}
@ -76,7 +76,7 @@ Spammers will often use different e-mail domains so it looks like they are using
### Blocking by IP {#blocking-by-ip}
It is not possible to block visitors by IP address in Mastodon itself, and it is not a fool-proof strategy. IPs are sometimes shared by a lot of different people, and sometimes change hands. But it is possible to block visitors by IP address in Linux using a firewall. Here is an example using `iptables` and `ipset`:
It is not possible to block visitors by IP address in Mastodon itself, and it is not a foolproof strategy. IPs are sometimes shared by a lot of different people and sometimes change hands. However, it is possible to block visitors by IP address in Linux using a firewall. Here is an example using `iptables` and `ipset`:
```bash
# Install ipset

6
content/en/admin/optional/object-storage-proxy.md
View File

@ -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:
@ -99,7 +99,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

24
content/en/admin/optional/object-storage.md
View File

@ -27,7 +27,7 @@ The web server must be configured to serve those files but not allow listing the
## 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 security of private data.
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`
@ -37,7 +37,7 @@ On Mastodon's end, you need to configure the following environment variables:
- `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 in trouble processing large files)
- `S3_FORCE_SINGLE_REQUEST=true` (optional, if you run into trouble processing large files)
{{< page-ref page="admin/optional/object-storage-proxy.md" >}}
@ -46,16 +46,16 @@ You must serve the files with CORS headers, otherwise some functions of Mastodon
{{</ hint >}}
{{< hint style="danger" >}}
In any case, your S3 bucket must be configured so that -- ACL configuration nonwithstanding -- all objects are publicly readable but neither writable or listable, while Mastodon itself can write to it. The configuration should be similar for all S3 providers, but common ones have been highlighted below.
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.
{{</ hint >}}
### 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.
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` by the actual name of your S3 bucket):
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",
@ -72,7 +72,7 @@ To do this, you need to set a custom policy (replace `mastodata` by the actual n
}
```
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` by the actual name of your S3 bucket):
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",
@ -93,7 +93,7 @@ You can set those policies from the MinIO Console (web-based user interface) or
Connect to the MinIO Console web interface and create a new bucket (or navigate to your existing bucket):
![](/assets/object-storage/minio-bucket.png)
Then, configure the “Access Policy” to a custom one that allows read access (`s3:GetObject`) without write access or ability to list objects (see above):
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):
![](/assets/object-storage/minio-access-policy.png)
{{< hint style="info" >}}
@ -108,7 +108,7 @@ 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 (can be called `mc` or `mcli` depending on where it is installed from).
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`
@ -183,7 +183,7 @@ In your DigitalOcean Spaces Bucket, make sure that “File Listing” is “Rest
### Scaleway
If you want to use Scaleway Object Storage, we strongly recommend you to create a Scaleway project dedicaced to your Mastodon instance assets and to use a custom IAM policy.
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.
@ -191,7 +191,7 @@ First, create a new Scaleway project, in which you create your object storage bu
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 organisation menu, top right of the screen), and create a new IAM policy (eg `mastodon-media-access`)
Head to the IAM settings (in your organization menu, top right of the screen), and create a new IAM policy (eg `mastodon-media-access`)
![](/assets/object-storage/scaleway-policy.jpg)
@ -199,7 +199,7 @@ This policy needs to have one rule, allowing it to read, write and delete object
![](/assets/object-storage/scaleway-policy-rules.jpg)
Then head to the IAM Applications page, and a create a new one (eg `my-mastodon-instance`) and select the policy you created above.
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.
@ -225,7 +225,7 @@ Cloudflare R2 does not support ACLs, so Mastodon needs to be instructed not to t
Without support for ACLs, media files from temporarily-suspended users will remain accessible.
{{< /hint >}}
To get credentials for use in Mastodon, selecte “Manage R2 API Tokens” and create a new API token with “Edit” permissions.
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.

4
content/en/admin/optional/tor.md
View File

@ -136,9 +136,9 @@ server {
Replace the long hash provided here with your Tor domain located in the file at `/var/lib/tor/onion_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.

6
content/en/admin/prerequisites.md
View File

@ -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:
@ -48,7 +48,7 @@ enabled = true
port = 22
```
Finally restart fail2ban:
Finally, restart fail2ban:
```bash
systemctl restart fail2ban
@ -56,7 +56,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

32
content/en/admin/scaling.md
View File

@ -22,7 +22,7 @@ The web process serves short-lived HTTP requests for most of the application. Th
- `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.
@ -34,9 +34,9 @@ The streaming API handles long-lived HTTP and WebSockets connections, through wh
- `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.
- Additionally, the shared [database](/admin/config#postgresql) and [redis](/admin/config#redis) environment variables are used.
The streaming API can be 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.
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.
@ -88,13 +88,13 @@ 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}
@ -117,7 +117,7 @@ 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.
@ -129,7 +129,7 @@ As a solution, it is possible to start different Sidekiq processes for the queue
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.
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 Postgres 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}
@ -187,7 +187,7 @@ 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}
@ -200,7 +200,7 @@ Add a line under `[databases]` listing the Postgres databases you want to connec
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
@ -219,7 +219,7 @@ Make sure the `pgbouncer` user is an admin:
admin_users = pgbouncer
```
**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`:
Mastodon requires a different pooling mode than the default session-based one. Specifically, it needs a transaction-based pooling mode. This means that a Postgres 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
@ -248,7 +248,7 @@ You should be able to connect to PgBouncer just like you would with Postgres:
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:
@ -306,7 +306,11 @@ Then use `\q` to quit.
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}
@ -371,7 +375,7 @@ 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 (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.
@ -398,7 +402,7 @@ 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 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 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" >}}
Make sure the sidekiq processes run with the stock `config/database.yml` to avoid failing jobs and data loss!

16
content/en/admin/tootctl.md
View File

@ -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.
@ -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. {{<required>}}
@ -146,7 +146,7 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
: Approve `USERNAME`'s account, if you are/were in approval mode.
`--disable-2fa`
: Remove additional factors and allow login with password.
: Remove additional factors and allow login with a password.
`--reset-password`
: Resets the password of the given account.
@ -165,7 +165,7 @@ Modify a user account's role, email, active status, approval mode, or 2FA requir
### `tootctl accounts delete` {#accounts-delete}
Delete a user account with given USERNAME.
Delete a user account with the given USERNAME.
`USERNAME`
: Local username for the new account. {{<required>}}
@ -179,7 +179,7 @@ Delete a user account with given USERNAME.
### `tootctl accounts backup` {#accounts-backup}
Request a backup for a user account with given USERNAME. The backup will be created in Sidekiq asynchronously, and the user will receive an email with a link to it once it's done.
Request a backup for a user account with the given USERNAME. The backup will be created in Sidekiq asynchronously, and the user will receive an email with a link to it once it's done.
`USERNAME`
: Local username for the new account. {{<required>}}
@ -207,7 +207,7 @@ Remove remote accounts that no longer exist. Queries every single remote account
**Version history:**\
2.6.0 - added\
2.8.0 - add `--dry-run`\
3.5.0 - add ability to pass specific domains
3.5.0 - add the ability to pass specific domains
---
@ -230,7 +230,7 @@ Refetch remote user data and files for one or multiple accounts.
: The number of workers to use for this task. Defaults to N=5.
`--verbose`
: Print additional information while task is processing.
: Print additional information while a task is processing.
`--dry-run`
: Print expected results only, without performing any actions.
@ -557,7 +557,7 @@ Imports custom emoji from a .tar.gz archive at a given path. The archive should
### `tootctl emoji purge` {#emoji-purge}
Remove all custom emoji.
Remove all custom emojis.
`--remote-only`
: If provided, remove only from remote domains.

4
content/en/admin/troubleshooting.md
View File

@ -11,7 +11,7 @@ menu:
All error messages with stack traces are written to the system log. When using systemd, the logs of each systemd service can be browsed with `journalctl -u mastodon-web` (substitute with the correct service name). When using Docker, it’s similar: `docker logs mastodon_web_1` (substitute with the correct container name).
Specific details of server-side errors are _never_ displayed to the public, as they can reveal what your setup looks like internally and give attackers clues how to get in, or how to abuse the system more efficiently.
Specific details of server-side errors are _never_ displayed to the public, as they can reveal what your setup looks like internally and give attackers clues on how to get in, or how to abuse the system more efficiently.
Each response from Mastodon’s web server carries a header with a unique request ID, which is also reflected in the logs. By inspecting the headers of the error page, you can easily find the corresponding stack trace in the log.
@ -29,7 +29,7 @@ Check that you are specifying the correct environment with `RAILS_ENV=production
## **I encountered a compilation error while executing `RAILS_ENV=production bundle exec rails assets:precompile`, but no more information is given. How to fix it?**
Usually it's because your server ran out of memory while compiling assets. Use a swapfile or increase the swap space to increase the memory capacity. Run `RAILS_ENV=production bundle exec rake tmp:cache:clear` to clear cache, then execute `RAILS_ENV=production bundle exec rails assets:precompile` to compile again. Make sure you clear the cache after a compilation error, or it will show "Everything's OK" but leave the assets unchanged.
Usually, it's because your server ran out of memory while compiling assets. Use a swapfile or increase the swap space to increase the memory capacity. Run `RAILS_ENV=production bundle exec rake tmp:cache:clear` to clear cache, then execute `RAILS_ENV=production bundle exec rails assets:precompile` to compile again. Make sure you clear the cache after a compilation error, or it will show "Everything's OK" but leave the assets unchanged.
## **I am getting this error: `Read-only file system @ dir_s_mkdir`. Why?**

8
content/en/admin/troubleshooting/index-corruption.md
View File

@ -15,17 +15,17 @@ Textual values in the database, such as usernames, or status identifiers, are co
When setting up a database, Mastodon will use the database server's default locale settings, including the default collation rules, which often is defined by the operating system's settings.
Unfortunately, in late 2018, a `glibc` update changed the collation rules for many locales, which means databases using an affected locale would now order textual values differently.
Since the database indexes are algorithmic structures which rely on the ordering of the values they are indexing, some of them would become inconsistent.
Since the database indexes are algorithmic structures that rely on the ordering of the values they are indexing, some of them would become inconsistent.
More information: https://wiki.postgresql.org/wiki/Locale_data_changes https://postgresql.verite.pro/blog/2018/08/27/glibc-upgrade.html
## Am I affected by this issue? {#am-i-affected}
If your database is not using `C` or `POSIX` for its collation setting (which you can check with `SELECT datcollate FROM pg_database WHERE datname = current_database();`),
your indexes might be inconsistent, if you ever ran with a version of glibc prior to 2.28 and did not immediately reindex your databases after updating to glibc 2.28 or newer.
your indexes might be inconsistent if you ever ran with a version of glibc prior to 2.28 and did not immediately reindex your databases after updating to glibc 2.28 or newer.
{{< hint style="info" >}}
You may have found this page because of **PgHero** warnings about "Duplicate Indexes". While such warnings can sometimes be indicative of an issue in deploying or updating Mastodon, **they are not related to database index corruption and not indicative of any functional issue with your database**.
You may have found this page because of PgHero warnings about "Duplicate Indexes". While such warnings can sometimes be indicative of an issue in deploying or updating Mastodon, **they are not related to database index corruption and are not indicative of any functional issue with your database**.
{{< /hint >}}
You can check whether your indexes are consistent using [PostgreSQL's `amcheck` module](https://www.postgresql.org/docs/10/amcheck.html): as the database server's super user, connect to your Mastodon database and issue the following (this may take a while):
@ -79,7 +79,7 @@ If this succeeds, without returning an error, your database should be consistent
## Fixing the issue {#fixing}
Unless you take action, if you are affected, your database could get more and more inconsistent as the time pass. Therefore, it is important to fix it as soon as possible.
Unless you take action, if you are affected, your database could get more and more inconsistent as time passes. Therefore, it is important to fix it as soon as possible.
Mastodon 3.2.2 and later come with a semi-interactive script to fix those corruptions as best as possible. If you're on an earlier version, update to 3.2.2 first. It is possible that running the database migrations to 3.2.2 will fail because of those very corruptions, but the database should then be brought to a state that the maintenance tool bundled with Mastodon 3.2.2 can then recover from.

4
content/en/admin/upgrading.md
View File

@ -34,7 +34,7 @@ And navigate to the Mastodon root directory:
cd /home/mastodon/live
```
Download the releases’s code, assuming that the version is called `v3.1.2`:
Download the release’s code, assuming that the version is called `v3.1.2`:
```bash
git fetch --tags
@ -69,7 +69,7 @@ systemctl reload mastodon-web
The `reload` operation is a zero-downtime restart, also called "phased restart". As such, Mastodon upgrades usually do not require any advance notice to users about planned downtime. In rare cases, you can use the `restart` operation instead, but there will be a (short) felt interruption of service for your users.
{{< /hint >}}
The **streaming API** server is also updated and requires a restart, doing so will result in all connected clients being disconnected, which can increase load on your server:
The **streaming API** server is also updated and requires a restart, doing so will result in all connected clients being disconnected, which can increase the load on your server:
```bash
systemctl restart mastodon-streaming

26
content/en/api/guidelines.md
View File

@ -9,7 +9,7 @@ menu:
## Login {#login}
**The user must be able to login to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials.
**The user must be able to log in to any Mastodon server from the app**. This means you must ask for the server's domain and use the app registrations API to dynamically obtain OAuth2 credentials.
{{< page-ref page="client/authorized" >}}
@ -19,11 +19,11 @@ menu:
## Usernames {#username}
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, for example, by displaying their `acct` somewhere. Note that `acct` is equal to `username` for local users, and equal to `username@domain` for remote users.
**Decentralization must be transparent to the user**. It should be possible to see that a given user is from another server, for example, by displaying their `acct` somewhere. Note that `acct` is equal to `username` for local users and equal to `username@domain` for remote users.
## Handling and sorting IDs {#id}
Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integer! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.**
Vanilla Mastodon entity IDs are generated as integers and cast to string. However, this does not mean that IDs _are_ integers, nor should they be cast to integers! Doing so can lead to broken client apps due to integer overflow, so **always treat IDs as strings.**
With that said, because IDs are string representations of numbers, they can still be sorted chronologically very easily by doing the following:
@ -48,11 +48,11 @@ min_id
For example, we might fetch `https://mastodon.example/api/v1/accounts/1/statuses` with certain parameters, and we will get the following results in the following cases:
- Setting `?max_id=1` will return no statuses, since there are no statuses with an ID earlier than `1`.
- Setting `?since_id=1` will return the latest statuses, since there have been many statuses since `1`.
- Setting `?max_id=1` will return no statuses since there are no statuses with an ID earlier than `1`.
- Setting `?since_id=1` will return the latest statuses since there have been many statuses since `1`.
- Setting `?min_id=1` will return the oldest statuses, as `min_id` sets the cursor.
Some API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
Some API methods operate on entity IDs that are not publicly exposed in the API response and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
To get around this, Mastodon may return links to a "prev" and "next" page. These links are made available via the HTTP `Link` header on the response. Consider the following fictitious API call:
@ -91,7 +91,7 @@ Plain text is not available for content from remote servers, and plain text synt
### Mentions, hashtags, and custom emoji {#tags}
Mentions and hashtags are `<a>` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "entities/Status" >}}), which can be matched to a particular tag.
Mentions and hashtags are `<a>` tags. Custom emojis remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "entities/Status" >}}), which can be matched to a particular tag.
{{< page-relref ref="entities/Status" caption="Status entity" >}}
@ -103,7 +103,7 @@ Mentions and hashtags are `<a>` tags. Custom emoji remain in their plain text sh
### Link shortening {#links}
Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters, and are intended to be shortened visually. For that purpose, a link is marked up like this:
Links in Mastodon are not shortened using URL shorteners, and the usage of URL shorteners is heavily discouraged. URLs in text always count for 23 characters and are intended to be shortened visually. For that purpose, a link is marked up like this:
```html
<a href="https://example.com/page/that/is/very/long">
@ -113,7 +113,7 @@ Links in Mastodon are not shortened using URL shorteners, and the usage of URL s
</a>
```
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long; otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup; instead, you are expected to insert it yourself if you need it in your app.
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long; otherwise, it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup; instead, you are expected to insert it yourself if you need it in your app.
## Filters {#filters}
@ -121,7 +121,7 @@ The spans with the `invisible` class can be hidden. The middle span is intended
If a filter applies to a Status, a corresponding FilterResult will be included in the `filtered` attribute. Clients should check this attribute for any matches and use them to apply the intended filter action.
However, client implementations may still want to perform their own rule matching client-side, as this would allow retroactively apply filter changes without re-fetching posts from the server. When doing so, they should take care to not ignore `filtered` entries for which there are other attributes than `keyword_matches`, so as to handle extensions of the filtering system (e.g. `status_matches`).
However, client implementations may still want to perform their own rule matching client-side, as this would allow retroactively applying filter changes without re-fetching posts from the server. When doing so, they should take care to not ignore `filtered` entries for which there are other attributes than `keyword_matches`, so as to handle extensions of the filtering system (e.g. `status_matches`).
Matched filters need to be filtered based on context (`home`, `notifications`, `public`, `thread` or `profile`) and expiration date.
@ -138,8 +138,8 @@ Expired filters are not deleted by the server. They should no longer be applied,
If `whole_word` is true, the client app should do the following:
* Define ‘word constituent characters’ for your app. In the official implementation, it’s `[A-Za-z0-9_]` in JavaScript, and `[[:word:]]` in Ruby. Ruby uses the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation).
* If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match.
* If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match.
* If the phrase starts with a word character, and if the previous character before the matched range is a word character, its matched range should be treated to not match.
* If the phrase ends with a word character, and if the next character after the matched range is a word character, its matched range should be treated to not match.
Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_manager.rb` in the Mastodon source code for more details.
@ -149,6 +149,6 @@ Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_mana
## Focal points for cropping media thumbnails {#focal-points}
Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. See this [guide on how focal points are defined](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point). In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. (0,0) is the center of the image. (0.5, 0.5) would be in the center of the upper-right quadrant. (-0.5, -0.5) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9.
Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. See this [guide on how focal points are defined](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point). In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. (0,0) is the center of the image. (0.5, 0.5) would be in the center of the upper-right quadrant. (-0.5, -0.5) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon front end are most commonly 16:9.
{{< figure src="assets/focal-points.jpg" caption="A demonstration of various focal points and their coordinates." >}}

4
content/en/api/oauth-scopes.md
View File

@ -17,9 +17,9 @@ Multiple scopes can be requested at the same time: During app creation with the
Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate `scopes`.
{{< /hint >}}
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token / app will default to `read` access.
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token/app will default to `read` access.
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise, authorization will fail.
### Version history {#versions}

2
content/en/client/authorized.md
View File

@ -9,7 +9,7 @@ menu:
## Scopes explained {#scopes}
When we registered our app and when we will authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope.
When we register our app and when we authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope.
Scopes must be a subset. When we created our app, we specified `read write push` -- we could request all available scopes by specifying `read write push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it.

4
content/en/client/intro.md
View File

@ -9,7 +9,7 @@ menu:
## An introduction to REST {#rest}
Mastodon provides access to its data over a REST API. REST stands for REpresentational State Transfer, but for our purposes, just think of it as sending and receiving information about various resources based on the request. The Mastodon REST API uses HTTP for its requests, and JSON for its payloads.
Mastodon provides access to its data over a REST API. REST stands for REpresentational State Transfer, but for our purposes, just think of it as sending and receiving information about various resources based on the request. The Mastodon REST API uses HTTP for its requests and JSON for its payloads.
## Understanding HTTP requests and responses {#http}
@ -64,7 +64,7 @@ curl -X POST \
### JSON {#json}
*JavaScript Object Notation* as defined in ECMA-404. Quick one page overview: https://www.json.org/
*JavaScript Object Notation* as defined in ECMA-404. Quick one-page overview: https://www.json.org/
Similar to sending form data, but with an additional header to specify that the data is in JSON format. To send a JSON request with cURL, specify the JSON content type with a header, then send the JSON data as form data:

4
content/en/client/public.md
View File

@ -58,7 +58,7 @@ We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag]
curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2
```
We should once again see 2 statuses have been returned in a JSON array of [Status]({{< relref "entities/status" >}}) entities. We can parse the JSON by array, then by object. If we were using Python, our code might look something like this:
We should once again see that 2 statuses have been returned in a JSON array of [Status]({{< relref "entities/status" >}}) entities. We can parse the JSON by array, then by object. If we were using Python, our code might look something like this:
```python
import requests
@ -71,7 +71,7 @@ print(statuses[0]["content"]) # this prints the status text
```
{{< hint style="info" >}}
Parsing JSON and using it in your program is outside of the scope of this tutorial, as it will be different depending on your choice of programming language and on the design of your program. Look for other tutorials on how to work with JSON in your programming language of choice.
Parsing JSON and using it in your program is outside of the scope of this tutorial, as it will be different depending on your choice of programming language and the design of your program. Look for other tutorials on how to work with JSON in your programming language of choice.
{{< /hint >}}
{{< hint style="info" >}}

4
content/en/client/token.md
View File

@ -11,7 +11,7 @@ menu:
Up until this point, we've been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information (and to potentially revoke or deny access).
This is where [OAuth]({{< relref "spec/oauth" >}}) comes in. OAuth is a mechanism for generating access tokens which can be used to _authenticate (verify)_ that a request is coming from a specific client, and ensure that the requested action is _authorized (allowed)_ by the server's access control policies.
This is where [OAuth]({{< relref "spec/oauth" >}}) comes in. OAuth is a mechanism for generating access tokens that can be used to _authenticate (verify)_ that a request is coming from a specific client, and ensure that the requested action is _authorized (allowed)_ by the server's access control policies.
## Creating our application {#app}
@ -31,7 +31,7 @@ In the above example, we specify the client name and website, which will be show
* `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list.
* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information.
We should see an Application entity returned, but for now we only care about client_id and client_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications.
We should see an Application entity returned, but for now, we only care about client_id and client_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications.
## Example authentication code flow {#flow}

2
content/en/dev/code.md
View File

@ -9,7 +9,7 @@ menu:
### Code structure {#structure}
The following overview should not be seen as complete or authoritative, but as a rough guidance to help you find your way in the application.
The following overview should not be seen as complete or authoritative but as a rough guidance to help you find your way in the application.
#### Ruby {#ruby}

4
content/en/dev/overview.md
View File

@ -11,11 +11,11 @@ Mastodon is a Ruby on Rails application with a React.js front-end. It follows s
The best way of working with Mastodon in a development environment is installing all the dependencies on your system, rather than using Docker or Vagrant. You need Ruby, Node.js, PostgreSQL and Redis, which is a pretty standard set of dependencies for Rails applications.
Tutorials for installing these dependencies can be found on the “Installing from source” page in the Running Mastodon section of the documentation. Please keep in mind that root access to a machine running Ubuntu 18.04 is required. After following the installation guide in the Running Mastodon section, see the “Setting up a dev environment” page for further instruction on how to configure your environment for development.
Tutorials for installing these dependencies can be found on the “Installing from source” page in the Running Mastodon section of the documentation. After following the installation guide in the Running Mastodon section, see the “Setting up a dev environment” page for further instructions on how to configure your environment for development.
### Environments {#environments}
An “environment” is a set of configuration values intended for a specific use case. Some environments could be: development, in which you intend to change the code; test, in which you intend to run the automated test suite; staging, which is meant to preview the code to end-users; and production, which is intended to face end-users. Mastodon comes with configurations for development, test and production.
An “environment” is a set of configuration values intended for a specific use case. Some environments could be: development, in which you intend to change the code; test, in which you intend to run the automated test suite; staging, which is meant to preview the code to end-users; and production, which is intended to face end-users. Mastodon comes with configurations for development, testing and production.
The default value of `RAILS_ENV` is `development`, so you don’t need to set anything extra to run Mastodon in development mode. In fact, all of Mastodon’s configuration has correct defaults for the development environment, so you do not need an `.env` file unless you need to customize something. Here are some of the different behaviours between the development environment and the production environment: