: {{<required>}} String. The ID of the SOMETHING in the database.
##### Headers
Authorization
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
**Internal parameter.** Use HTTP `Link` header for pagination.
max_id
: String. Return results older than ID.
since_id
: String. Return results newer than ID.
min_id
: String. Return results immediately newer than ID.
limit
: Integer. Maximum number of results to return. Defaults to 20. Max 40.
##### Form data parameters
#### Response
##### 200: OK
```json
```
Because SOMETHING IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.
```http
Link:
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
##### 403: Forbidden
Authorized user is missing a permission, or invalid or missing Authorization header
```json
{
"error": "This action is not allowed"
}
```
##### 404: Not found
SOMETHING is not owned by you or does not exist
```json
{
"error": "Record not found"
}
```
##### 410: Gone
##### 422: Unprocessable entity
##### 429: Rate limited
```json
{
"error": "Too many requests"
}
```
##### 503: Service unavailable
```json
{
"error": "There was a temporary problem serving your request, please try again"
@ -30,7 +30,7 @@ A Mastodon website can operate alone. Just like a traditional website, people si
Mastodon uses a standardized, open protocol to implement federation. It is called **ActivityPub**. Any software that likewise implements federation via ActivityPub can seamlessly communicate with Mastodon, just like Mastodon websites communicate with one another.
The **fediverse**\(“federated universe”\) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations:
The **fediverse** (“federated universe”) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations:
* Pleroma, a modular microblogging engine,
* Pixelfed, federated image sharing platform, which lets you share and consume media posts,
@ -45,13 +45,13 @@ The fediverse does not have its own brand, so you might more often hear “follo
### Choice of service provider and policy {#choice}
Because Mastodon is simply software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown.
Because Mastodon is just software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown.
> Maintaining communities that feel safe for all of its members is not easy. Mastodon provides a lot of foundational framework and tools for doing it, and shifts the power to effect change from one commercial entity to the communities themselves.
>
> -- Eugen Rochko, Jul 6 2018, ["Cage the Mastodon"](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/)
> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO \[...\] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one.
> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO [...] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one.
>
> -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
@ -91,19 +91,19 @@ Unlike proprietary services, **anyone has the complete freedom to run, examine,
Learn how to use Mastodon:
{{<page-refpage="user/signup.md">}}
{{<page-refpage="user/signup">}}
Learn how to install Mastodon:
{{<page-refpage="admin/prerequisites.md">}}
{{<page-refpage="admin/prerequisites">}}
Learn how to write an app for Mastodon:
{{<page-refpage="client/intro.md">}}
{{<page-refpage="client/intro">}}
Learn about the Mastodon backend and how to contribute:
If you have multiple domains pointed at your Mastodon server, this setting will allow Mastodon to recognize itself when users are addressed using those other domains. Separate the domains by commas, e.g. `foo.com,bar.com`
#### `AUTHORIZED_FETCH` {#authorized_fetch}
#### `ALLOWED_PRIVATE_ADDRESSES`
Comma-separated specific addresses/subnets allowed in outgoing HTTP queries.
#### `AUTHORIZED_FETCH`
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.
- 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.
@ -55,7 +59,7 @@ Unfortunately, secure mode is not without its drawbacks, which is why it is not
Secure mode does not hide HTML representations of public posts and profiles. HTML is a more lossy format compared to first-class ActivityPub representations or the REST API but it is still a potential vector for scraping content.
When set to `true`, Mastodon will restrict federation to servers you have manually approved only, as well as disable all public pages and some REST APIs. Limited federation mode is based on secure mode (`AUTHORIZED_FETCH`).
@ -73,6 +77,92 @@ This mode is intended for private use only, such as in academic instituations or
This setting was known as `WHITELIST_MODE` prior to 3.1.5.
{{</hint>}}
#### `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.
#### `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.
#### `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.
Example value: `de`
Supported languages:
- `ar`
- `ast`
- `bg`
- `bn`
- `br`
- `ca`
- `co`
- `cs`
- `cy`
- `da`
- `de`
- `el`
- `en`
- `eo`
- `es`
- `es-AR`
- `et`
- `eu`
- `fa`
- `fi`
- `fr`
- `ga`
- `gl`
- `he`
- `hi`
- `hr`
- `hu`
- `hy`
- `id`
- `io`
- `is`
- `it`
- `ja`
- `ka`
- `kab`
- `kk`
- `kn`
- `ko`
- `lt`
- `lv`
- `mk`
- `ml`
- `mr`
- `ms`
- `nl`
- `nn`
- `no`
- `oc`
- `pl`
- `pt-BR`
- `pt-PT`
- `ro`
- `ru`
- `sk`
- `sl`
- `sq`
- `sr`
- `sr-Latn`
- `sv`
- `ta`
- `te`
- `th`
- `tr`
- `uk`
- `ur`
- `vi`
- `zh-CN`
- `zh-HK`
- `zh-TW`
### Secrets {#secrets}
#### `SECRET_KEY_BASE`
@ -147,7 +237,7 @@ This variable cannot be defined in dotenv (`.env`) files as it's used before the
### Scaling options {#scaling}
{{<page-refpage="admin/scaling.md">}}
{{<page-refpage="admin/scaling">}}
#### `WEB_CONCURRENCY`
@ -157,6 +247,10 @@ Specific to Puma, this variable determines how many different processes Puma for
Specific to Puma, this variable determines how many threads each Puma process maintains. Defaults to `5`.
#### `PERSISTENT_TIMEOUT`
Specific to Puma, this variable determines how long Puma should wait before closing a connection. Defaults to `20`.
#### `PREPARED_STATEMENTS`
By default, Mastodon uses the prepared statements feature of PostgreSQL, which offers some performance advantages. This feature is not available if you are using a connection pool where connections are shared between transactions and must thus be set to `false`. When you are scaling up, the advantages of having a transaction-based connection pool outweigh those provided by prepared statements.
@ -171,7 +265,7 @@ Example value: `wss://streaming.example.com`
Specific to the streaming API, this variable determines how many different processes the streaming API forks into. Defaults to the number of CPU cores minus one.
## Database connections {#connections}
## Backend {#backend}
### PostgreSQL {#postgresql}
@ -249,9 +343,11 @@ If provided, takes precedence over `CACHE_REDIS_HOST` and `CACHE_REDIS_PORT`. De
@ -265,6 +361,14 @@ Host of the ElasticSearch server. Defaults to `localhost`
Port of the ElasticSearch server. Defaults to `9200`
#### `ES_USER`
Used for optionally authenticating with ElasticSearch
#### `ES_PASS`
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`.
@ -281,137 +385,32 @@ Example value: `localhost:8125`
If set, all StatsD keys will be prefixed with this. Defaults to `Mastodon.production` when `RAILS_ENV` is `production`, `Mastodon.development` when it's `development`, etc.
## Limits {#limits}
### SMTP email delivery {#smtp}
#### `SINGLE_USER_MODE`
#### `SMTP_SERVER`
#### `SMTP_PORT`
#### `SMTP_LOGIN`
#### `SMTP_PASSWORD`
#### `SMTP_FROM_ADDRESS`
#### `SMTP_DOMAIN`
#### `SMTP_DELIVERY_METHOD`
#### `SMTP_AUTH_METHOD`
#### `SMTP_CA_FILE`
#### `SMTP_OPENSSL_VERIFY_MODE`
#### `SMTP_ENABLE_STARTTLS_AUTO`
#### `SMTP_ENABLE_STARTTLS`
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.
Set to `auto` (default), `always`, or `never`.
#### `EMAIL_DOMAIN_ALLOWLIST`
**Version history:**\
4.0.0 - added
If set, registrations will not be possible with any e-mails **except** those from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
#### `EMAIL_DOMAIN_DENYLIST`
If set, registrations will not be possible with any e-mails from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
{{<hintstyle="warning">}}
This option is deprecated. You can dynamically block e-mail domains from the admin interface or from the `tootctl` command-line interface.
{{</hint>}}
#### `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.
#### `SMTP_TLS`
#### `SMTP_SSL`
Example value: `de`
## File storage {#files}
Supported languages:
- `ar`
- `ast`
- `bg`
- `bn`
- `br`
- `ca`
- `co`
- `cs`
- `cy`
- `da`
- `de`
- `el`
- `en`
- `eo`
- `es`
- `es-AR`
- `et`
- `eu`
- `fa`
- `fi`
- `fr`
- `ga`
- `gl`
- `he`
- `hi`
- `hr`
- `hu`
- `hy`
- `id`
- `io`
- `is`
- `it`
- `ja`
- `ka`
- `kab`
- `kk`
- `kn`
- `ko`
- `lt`
- `lv`
- `mk`
- `ml`
- `mr`
- `ms`
- `nl`
- `nn`
- `no`
- `oc`
- `pl`
- `pt-BR`
- `pt-PT`
- `ro`
- `ru`
- `sk`
- `sl`
- `sq`
- `sr`
- `sr-Latn`
- `sv`
- `ta`
- `te`
- `th`
- `tr`
- `uk`
- `ur`
- `vi`
- `zh-CN`
- `zh-HK`
- `zh-TW`
#### `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.
#### `USER_ACTIVE_DAYS`
Mastodon stores home feeds in RAM (specifically, in the Redis database). This makes them very fast to access and update, but it also means that you don't want to keep them there if they're not used, and you don't want to spend resources on inserting new items into home feeds that will not be accessed. For this reason, Mastodon periodically clears out home feeds of users who haven't been online in a while, and if they re-appear, it regenerates those home feeds from database data. By default, users are considered active if they have been online in the past `7` days.
Regeneration of home feeds is computationally expensive, if your Sidekiq is constantly doing it because your users come online every 3 days but your `USER_ACTIVE_DAYS` is set to 2, then consider adjusting it up.
{{<hintstyle="info">}}
This setting has no relation to which users are considered active for the purposes of statistics, such as the Monthly Active Users number.
{{</hint>}}
#### `ALLOWED_PRIVATE_ADDRESSES`
Comma-separated specific addresses/subnets allowed in outgoing HTTP queries.
## E-mail {#email}
* `SMTP_SERVER`
* `SMTP_PORT`
* `SMTP_LOGIN`
* `SMTP_PASSWORD`
* `SMTP_FROM_ADDRESS`
* `SMTP_DOMAIN`
* `SMTP_DELIVERY_METHOD`
* `SMTP_AUTH_METHOD`
* `SMTP_CA_FILE`
* `SMTP_OPENSSL_VERIFY_MODE`
* `SMTP_ENABLE_STARTTLS_AUTO`
* `SMTP_TLS`
* `SMTP_SSL`
## File storage {#cdn}
### CDN {cdn}
#### `CDN_HOST`
@ -434,7 +433,7 @@ It is *extremely recommended* to use your own host instead, for a few reasons:
If set, registrations will not be possible with any e-mails **except** those from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
#### `EMAIL_DOMAIN_DENYLIST`
If set, registrations will not be possible with any e-mails from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
{{<hintstyle="warning">}}
This option is deprecated. You can dynamically block e-mail domains from the admin interface or from 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.
### Home feeds
#### `USER_ACTIVE_DAYS`
Mastodon stores home feeds in RAM (specifically, in the Redis database). This makes them very fast to access and update, but it also means that you don't want to keep them there if they're not used, and you don't want to spend resources on inserting new items into home feeds that will not be accessed. For this reason, Mastodon periodically clears out home feeds of users who haven't been online in a while, and if they re-appear, it regenerates those home feeds from database data. By default, users are considered active if they have been online in the past `7` days.
Regeneration of home feeds is computationally expensive, if your Sidekiq is constantly doing it because your users come online every 3 days but your `USER_ACTIVE_DAYS` is set to 2, then consider adjusting it up.
{{<hintstyle="info">}}
This setting has no relation to which users are considered active for the purposes of statistics, such as the Monthly Active Users number.
{{</hint>}}
## Other {#other}
### DB migrations {#migrations}
#### `SKIP_POST_DEPLOYMENT_MIGRATIONS`
This variable only has any effect when running `rake db:migrate` and it is extremely specific to the Mastodon upgrade process. There are two types of database migrations, those that run before new code is deployed and running, and those that run after. By default, both types of migrations are executed. If you shut down all Mastodon processes before running migrations, then there is no difference. The variable makes sense for zero-downtime upgrades. You will see in the upgrade instructions of a specific Mastodon version if you need to use it or not.
### Uncategorized or unsorted
#### `BUNDLE_GEMFILE`
#### `DEEPL_API_KEY`
#### `DEEPL_PLAN`
#### `LIBRE_TRANSLATE_ENDPOINT`
#### `LIBRE_TRANSLATE_API_KEY`
#### `CACHE_BUSTER_ENABLED`
#### `CACHE_BUSTER_SECRET_HEADER`
#### `CACHE_BUSTER_SECRET`
#### `GITHUB_REPOSITORY`
Defaults to `mastodon/mastodon`
#### `SOURCE_BASE_URL`
Defaults to `https://github.com/$GITHUB_REPOSITORY`
#### `FFMPEG_BINARY`
#### `LOCAL_HTTPS`
#### `PATH`
#### `MAX_FOLLOWS_THRESHOLD`
Defaults to `7500`
#### `MAX_FOLLOWS_RATIO`
Defaults to `1.1`
#### `IP_RETENTION_PERIOD`
Defaults to `31536000` (1 year)
#### `SESSION_RETENTION_PERIOD`
Defaults to `31536000` (1 year)
#### `BACKTRACE`
Set to `1` to allow backtracing to Rails framework code.
For optimal performance, you may use [pgTune](https://pgtune.leopard.in.ua/#/) to generate an appropriate configuration and edit values in `/etc/postgresql/14/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql`
@ -140,7 +140,7 @@ su - mastodon
Use git to download the latest stable release of Mastodon:
```bash
git clone https://github.com/tootsuite/mastodon.git live && cd live
git clone https://github.com/mastodon/mastodon.git live && cd live
The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration.]({{< relref "config.md" >}})
The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration.]({{< relref "config" >}})
You’re done with the mastodon user for now, so switch back to root:
@ -15,10 +15,10 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
## Basic steps {#basic-steps}
1. Set up a new Mastodon server using the [Production Guide]({{< relref "install.md" >}}) \(however, don’t run `mastodon:setup`\).
2. Stop Mastodon on the old server \(e.g. `systemctl stop 'mastodon-*.service'`\).
1. Set up a new Mastodon server using the [Production Guide]({{< relref "install" >}}) (however, don’t run `mastodon:setup`).
2. Stop Mastodon on the old server (e.g. `systemctl stop 'mastodon-*.service'`).
3. Dump and load the Postgres database using the instructions below.
4. Copy the `system/` files using the instructions below. \(Note: if you’re using S3, you can skip this step.\)
4. Copy the `system/` files using the instructions below. (Note: if you’re using S3, you can skip this step.)
5. Copy the `.env.production` file.
6. Run `RAILS_ENV=production bundle exec rails assets:precompile` to compile Mastodon
7. Run `RAILS_ENV=production ./bin/tootctl feeds build` to rebuild the home timelines for each user.
@ -33,19 +33,19 @@ This guide was written with Ubuntu Server in mind; your mileage may vary for oth
At a high level, you’ll need to copy over the following:
* The `~/live/public/system` directory, which contains user-uploaded images and videos \(if using S3, you don’t need this\)
* The Postgres database \(using [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html)\)
* The `~/live/public/system` directory, which contains user-uploaded images and videos (if using S3, you don’t need this)
* The Postgres database (using [pg\_dump](https://www.postgresql.org/docs/9.1/static/backup-dump.html))
* The `~/live/.env.production` file, which contains server config and secrets
Less crucially, you’ll probably also want to copy the following for convenience:
* The nginx config \(under `/etc/nginx/sites-available/default`\)
* The systemd config files \(`/etc/systemd/system/mastodon-*.service`\), which may contain your server tweaks and customizations
* The pgbouncer configuration under `/etc/pgbouncer`\(if you’re using it\)
* The nginx config (under `/etc/nginx/sites-available/default`)
* The systemd config files (`/etc/systemd/system/mastodon-*.service`), which may contain your server tweaks and customizations
* The pgbouncer configuration under `/etc/pgbouncer` (if you’re using it)
### Dump and load Postgres {#dump-and-load-postgres}
Instead of running `mastodon:setup`, we’re going to create an empty Postgres database using the `template0` database \(which is useful when restoring a Postgres dump, [as described in the pg\_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)\).
Instead of running `mastodon:setup`, we’re going to create an empty Postgres database using the `template0` database (which is useful when restoring a Postgres dump, [as described in the pg\_dump documentation](https://www.postgresql.org/docs/9.1/static/backup-dump.html#BACKUP-DUMP-RESTORE)).
Run this as the `mastodon` user on your old system:
\(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.\)
(Note that if the username is not `mastodon` on the new server, you should change the `-U` AND `--role` values above. It’s okay if the username is different between the two servers.)
### Copy files {#copy-files}
@ -86,7 +86,7 @@ Optionally, you may copy over the nginx, systemd, and pgbouncer config files, or
You can edit the `~/live/public/500.html` page on the old machine if you want to show a nice error message to let existing users know that a migration is in progress.
You’ll probably also want to set the DNS TTL to something small \(30-60 minutes\) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address.
You’ll probably also want to set the DNS TTL to something small (30-60 minutes) about a day in advance, so that DNS can propagate quickly once you point it to the new IP address.
Moderation in Mastodon is always applied locally, i.e. as seen from the particular server. An admin or moderator on one server cannot affect a user on another server, they can only affect the local copy on their own server.
As of v3.5.0, all default user moderation decisions will notify the affected user by email. The user can access an appeal page, where they can submit one appeal within 20 days of the decision. Moderators can approve or reject the appeal.
### 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).
@ -27,9 +29,9 @@ When the user's account is un-frozen, normal functionality resumes.
### Limit {#limit-user}
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 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.
At this moment, limit does not affect federation. A locally limited account is _not_ limited automatically on other servers. Account limitations are reversible.
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}
@ -37,9 +39,9 @@ A Mastodon suspension means the account is effectively deleted. The account no l
If the account is reinstated within the 30 day period, all data is once again accessible publicly without any adverse affects. 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 than be 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 (toots, profile information, avatar or header image) associated with it.
Once the data has been deleted, whether than be 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.
Because individually moderating a large volume of users from a misbehaving server can be exhausting, it is possible to pre-emptively moderate against all users from that particular server using a so-called **domain block**, which comes with several different levels of severity.
@ -47,13 +49,13 @@ Because individually moderating a large volume of users from a misbehaving serve
With this option active, no files from the server will be processed locally. That includes avatars, headers, emojis and media attachments.
### Silence {#silence-server}
### Limit {#limit-server}
Applies a silence to all past and future accounts from the server.
Equivalent to [limiting](#limit-user) all past and future accounts from the server. Previously known as "silencing".
### Suspend {#suspend-server}
Applies a suspension to all past and future accounts from the server. No content from the server will be stored locally except for usernames.
Equivalent to [suspending](#suspend-user) all past and future accounts from the server. No content from the server will be stored locally except for usernames.
Mastodon supports full-text search when ElasticSearch is available. Mastodon’s full-text search allows logged in users to find results from their own toots, their favourites, and their mentions. It deliberately does not allow searching for arbitrary strings in the entire database.
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.
If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running **Ubuntu 20.04**:
## Do not allow password-based SSH login \(keys only\)
## 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.
The web process serves short-lived HTTP requests for most of the application. The following environment variables control it:
@ -37,7 +37,7 @@ The streaming API handles long-lived HTTP and WebSockets connections, through wh
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.
### Background processing \(Sidekiq\) {#sidekiq}
### Background processing (Sidekiq) {#sidekiq}
Many tasks in Mastodon are delegated to background processing to ensure the HTTP requests are fast, and to prevent HTTP request aborts from affecting the execution of those tasks. Sidekiq is a single process, with a configurable number of threads.
@ -84,7 +84,7 @@ As a solution, it is possible to start different Sidekiq processes for the queue
### 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 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.
@ -108,7 +108,7 @@ Here’s how you might reset the password:
psql -p 5432 -U mastodon mastodon_production -w
```
Then \(obviously, use a different password than the word “password”\):
Then (obviously, use a different password than the word “password”):
```sql
ALTER USER mastodon WITH PASSWORD 'password';
@ -164,13 +164,13 @@ listen_addr = 127.0.0.1
listen_port = 6432
```
Put `md5` as the `auth_type`\(assuming you’re using the md5 format in `userlist.txt`\):
Put `md5` as the `auth_type` (assuming you’re using the md5 format in `userlist.txt`):
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`:
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.\)
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.)
The defaults are fine to start, and you can always increase them later:
@ -211,7 +211,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 (Postgres) and you should be good to go:
```bash
DB_HOST=localhost
@ -222,7 +222,7 @@ DB_PORT=6432
```
{{<hintstyle="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 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)
{{</hint>}}
#### Administering PgBouncer {#pgbouncer-admin}
@ -249,13 +249,13 @@ 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 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.
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)
## 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 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:
* 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.
@ -17,6 +17,10 @@ After signing up in the browser, you will need to use the command line to give y
RAILS_ENV=production bin/tootctl accounts modify alice --role Owner
```
{{<hintstyle="warning">}}
Prior to Mastodon 4.0, roles were hardcoded to be one of `user`, `moderator`, or `admin`. Since Mastodon 4.0, there is a customizable role system, with default roles created for `Moderator`, `Admin`, and `Owner`. Names of custom roles are case-sensitive.
{{</hint>}}
### From the command line {#admin-cli}
You can create a new account using the command-line interface.
@ -42,7 +46,7 @@ After logging in, navigate to the **Site settings** page. While there are no tec
| Instance description | Why did you start this server? Who is it for? What makes it different? |
| Custom extended information | You can put all sorts of information in here but a **code of conduct** is recommended |
After you fill these in, simply hit “Save changes”.
## **I see an error page that says something went wrong. How do I find out what’s wrong?**
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\).
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.
@ -11,7 +11,7 @@ A somewhat common configuration issue can lead to index corruption throughout th
## Locale data and collation {#explanation}
Textual values in the database, such as usernames, or toot identifiers, are compared using so-called collation rules defining how characters are ordered and how to change their case.
Textual values in the database, such as usernames, or status identifiers, are compared using so-called collation rules defining how characters are ordered and how to change their case.
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.
When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended.
When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended.
{{</hint>}}
Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**.
Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the [GitHub releases page](https://github.com/mastodon/mastodon/releases). The page will contain a **changelog** describing everything you need to know about what's different, as well as **specific upgrade instructions**.
description: Things to keep in mind when implementing a Mastodon app.
menu:
docs:
weight: 10
parent: api
---
## 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.
**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.**
With that said, because IDs are string representations of numbers, they can still be sorted chronologically very easily by doing the following:
1. Sort by size. Newer statuses will have longer IDs.
2. Sort lexically. Newer statuses will have at least one digit that is higher when compared positionally.
## Paginating through API responses {#pagination}
Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`. However, some of these 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:
```http
GET https://mastodon.social/api/v1/endpoint HTTP/1.1
In this case, you may retrieve the `Link` header and parse it for links to the older or newer page. Keep in mind the following rules:
- The links will be returned all via one `Link` header, separated by a comma and a space (`, `)
- Each link consists of a URL and a link relation, separated by a semicolon and a space (`; `)
- The URL will be surrounded by angle brackets (`<>`), and the link relation will be surrounded by double quotes (`""`) and prefixed with `rel=`.
- The value of the link relation will be either `prev` or `next`.
Following the `next` link should show you older results. Following the `prev` link should show you newer results.
## Formatting {#formatting}
Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. See [HTML Sanitization]({{< relref "spec/activitypub#sanitization" >}}) for more details. You may expect these tags to appear in the content:
* `<p>`
* `<br>`
* `<span>`
* `<a>`
{{<page-relrefref="spec/activitypub#sanitization"caption="ActivityPub > HTML Sanitization">}}
### 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.
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:
trwnh
2 months ago
committed by