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

15 KiB
Raw Blame History

title description menu
Configuring your environment Setting environment variables for your Mastodon installation.
docs
weight parent
30 admin

{{< hint style="warning" >}} This page is under construction. {{< /hint >}}

Mastodon uses environment variables as its configuration.

For convenience, it can read them from a flat file called .env.production in the Mastodon directory, 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.

Basic

Federation

LOCAL_DOMAIN

This is the unique identifier of your server in the network. It cannot be safely changed later. It has to be the domain name you are running the server under (without the protocol part, e.g. just example.com).

WEB_DOMAIN

It is possible to run the Mastodon interface 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/shorter. This requires additional nginx configuration.

ALTERNATE_DOMAINS

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

When set to true, Mastodon will stop inline-signing activities, and will require remote servers to authenticate when fetching public and unlisted toots.

This prevents blocked domains from fetching your public toots, at the cost of possibly increased computations, and broken compatibility with software that does not sign fetch requests (such as Mastodon prior to version 3.0).

Note that this mode cannot guarantee that bad actors do not access your public and unlisted toots, it merely makes it a bit more difficult.

LIMITED_FEDERATION_MODE

{{< hint style="info" >}} This setting was known as WHITELIST_MODE prior to 3.1.5. {{</ hint >}}

{{< hint style="warning" >}} WHITELIST_MODE is broken on Mastodon 3.0.0 and 3.0.1. {{</ hint >}}

When set to true, Mastodon will restrict federation to specific servers only, as well as disable public pages and some client APIs. Limited federation mode mode implies authorized fetch mode.

When switching an existing instance to limited federation mode, the following command should be used to remove any already existent data on non-allowed domains:

tootctl domain purge --limited-federation-mode

Secrets

SECRET_KEY_BASE

Generate with rake secret. Changing it will break all active browser sessions.

OTP_SECRET

Generate with rake secret. Changing it will break two-factor authentication.

VAPID_PRIVATE_KEY

Generate with rake mastodon:webpush:generate_vapid_key. Changing it will break push notifications.

VAPID_PUBLIC_KEY

Generate with rake mastodon:webpush:generate_vapid_key. Changing it will break push notifications.

Deployment

RAILS_ENV

Environment. Can be production, development, or test. If you are running Mastodon on your personal computer for development purposes, use development. That is also the default. If you are running Mastodon online, use production. Mastodon will load different configuration defaults based on the environment.

{{< hint style="warning" >}} This variable cannot be defined in dotenv (.env) files as it's used before they are loaded. In fact, this variable may decide which dotenv file is loaded if different variants exist (e.g. .env.production or .env.test) {{</ hint >}}

RAILS_SERVE_STATIC_FILES

If set to true, Mastodon will answer requests for files in its public directory. This may be necessary if the reverse proxy (e.g. nginx) has no file system access to the public directory itself, such as in a containerized environment. It is a suboptimal setting because serving static files directly from the file system will always be much faster than serving them through the Ruby on Rails process.

RAILS_LOG_LEVEL

Determines the amount of logs generated by Mastodon. Defaults to info, which generates a log entry about every request served by Mastodon and every background job processed by Mastodon. This can be useful but can get quite noisy and strain the I/O of your machine if there is a lot of traffic/activity. In that case, warning is recommended, which will only output information about things that are going wrong, and otherwise stay quiet. Possible values are debug, info, warning, error, fatal and unknown.

TRUSTED_PROXY_IP

If your Mastodon web process is on the same machine as your reverse proxy (e.g. nginx), then you don't need this setting. Otherwise, you need to set it to the IP from which your reverse proxy sends requests to Mastodon's web process, otherwise Mastodon will record the reverse proxy's own IP as the IP of all requests, which would be bad because IP addresses are used for important rate limits and security functions.

SOCKET

Instead of binding to an IP address like 127.0.0.1, you may bind to a Unix socket. This variable is process-specific, e.g. you need different values for every process, and it works for both web (Puma) processes and streaming API (Node.js) processes.

{{< hint style="warning" >}} This variable cannot be defined in dotenv (.env) files as it's used before they are loaded and cannot be shared between different processes. {{</ hint >}}

PORT

If you are not using Unix sockets, this defines which port the process will listen on. This variable is process-specific, e.g. you need different values for every process, and it works for both web (Puma) processes and streaming API (Node.js) processes. By default, web listens on 3000 and streaming API on 4000.

{{< hint style="warning" >}} This variable cannot be defined in dotenv (.env) files as it's used before they are loaded and cannot be shared between different processes. {{</ hint >}}

NODE_ENV

Equivalent to RAILS_ENV, but for the streaming API (Node.js).

{{< hint style="warning" >}} This variable cannot be defined in dotenv (.env) files as it's used before they are loaded. In fact, this variable may decide which dotenv file is loaded if different variants exist (e.g. .env.production or .env.test) {{</ hint >}}

BIND

If you are not using Unix sockets, this defines the IP to which the process will bind. Multiple processes can bind to the same IP as long as they listen on different ports. Defaults to 127.0.0.1.

{{< hint style="warning" >}} This variable cannot be defined in dotenv (.env) files as it's used before they are loaded. {{</ hint >}}

Scaling options

{{< page-ref page="admin/scaling.md" >}}

WEB_CONCURRENCY

Specific to Puma, this variable determines how many different processes Puma forks into. Defaults to 2.

MAX_THREADS

Specific to Puma, this variable determines how many threads each Puma process maintains. Defaults to 5.

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.

STREAMING_API_BASE_URL

The streaming API can be deployed to a different domain/subdomain. This may improve the performance of the streaming API as in the default configuration long-lived streaming API requests are proxied through nginx, while serving the streaming API from a different domain/subdomain would allow one to skip nginx entirely.

Example: wss://streaming.example.com

STREAMING_CLUSTER_NUM

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

PostgreSQL

  • DB_HOST
  • DB_USER
  • DB_NAME
  • DB_PASS
  • DB_PORT
  • DB_POOL
  • DATABASE_URL

Redis

  • REDIS_HOST
  • REDIS_PORT
  • REDIS_URL
  • REDIS_NAMESPACE
  • CACHE_REDIS_HOST
  • CACHE_REDIS_PORT
  • CACHE_REDIS_URL
  • CACHE_REDIS_NAMESPACE

ElasticSearch

  • ES_ENABLED
  • ES_HOST
  • ES_PORT
  • ES_PREFIX

StatsD

  • STATSD_ADDR
  • STATSD_NAMESPACE

Limits

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.

EMAIL_DOMAIN_ALLOWLIST

EMAIL_DOMAIN_DENYLIST

{{< 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. {{</ 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.

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

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.

{{< hint style="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 >}}

E-mail

  • 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_HOST

You can serve static assets (logos, emojis, CSS, JS, etc) from a separate host, like a CDN (Content Delivery Network) as it can decrease loading times for your users.

Example value: https://assets.example.com

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.

It is extremely recommended to use your own host instead, for a few reasons:

  1. Bandwidth on external storage providers is metered and expensive
  2. You may want to switch to a different provider later without breaking old links

Example value: files.example.com

Local file storage

  • PAPERCLIP_ROOT_PATH
  • PAPERCLIP_ROOT_URL

Amazon S3 and compatible

  • S3_ENABLED
  • S3_BUCKET
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • S3_REGION
  • S3_PROTOCOL
  • S3_HOSTNAME
  • S3_ENDPOINT
  • S3_SIGNATURE_VERSION
  • S3_OVERRIDE_PATH_STYLE
  • S3_OPEN_TIMEOUT

Swift

  • SWIFT_ENABLED
  • SWIFT_USERNAME
  • SWIFT_TENANT
  • SWIFT_PASSWORD
  • SWIFT_PROJECT_ID
  • SWIFT_AUTH_URL
  • SWIFT_CONTAINER
  • SWIFT_OBJECT_URL
  • SWIFT_REGION
  • SWIFT_DOMAIN_NAME
  • SWIFT_CACHE_TTL

External authentication

  • OAUTH_REDIRECT_AT_SIGN_IN

LDAP

  • LDAP_ENABLED
  • LDAP_HOST
  • LDAP_PORT
  • LDAP_METHOD
  • LDAP_BASE
  • LDAP_BIND_DN
  • LDAP_PASSWORD
  • LDAP_UID
  • LDAP_SEARCH_FILTER
  • LDAP_MAIL
  • LDAP_UID_CONVERSTION_ENABLED

PAM

  • PAM_ENABLED
  • PAM_EMAIL_DOMAIN
  • PAM_DEFAULT_SERVICE
  • PAM_CONTROLLED_SERVICE

CAS

  • CAS_ENABLED
  • CAS_URL
  • CAS_HOST
  • CAS_PORT
  • CAS_SSL
  • CAS_VALIDATE_URL
  • CAS_CALLBACK_URL
  • CAS_LOGOUT_URL
  • CAS_LOGIN_URL
  • CAS_UID_FIELD
  • CAS_CA_PATH
  • CAS_DISABLE_SSL_VERIFICATION
  • CAS_UID_KEY
  • CAS_NAME_KEY
  • CAS_EMAIL_KEY
  • CAS_NICKNAME_KEY
  • CAS_FIRST_NAME_KEY
  • CAS_LAST_NAME_KEY
  • CAS_LOCATION_KEY
  • CAS_IMAGE_KEY
  • CAS_PHONE_KEY

SAML

  • SAML_ENABLED
  • SAML_ACS_URL
  • SAML_ISSUER
  • SAML_IDP_SSO_TARGET_URL
  • SAML_IDP_CERT
  • SAML_IDP_CERT_FINGERPRINT
  • SAML_NAME_IDENTIFIER_FORMAT
  • SAML_CERT
  • SAML_PRIVATE_KEY
  • SAML_SECURITY_WANT_ASSERTION_SIGNED
  • SAML_SECURITY_WANT_ASSERTION_ENCRYPTED
  • SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED
  • SAML_ATTRIBUTES_STATEMENTS_UID
  • SAML_ATTRIBUTES_STATEMENTS_EMAIL
  • SAML_ATTRIBUTES_STATEMENTS_FULL_NAME
  • SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME
  • SAML_ATTRIBUTES_STATEMENTS_LAST_NAME
  • SAML_UID_ATTRIBUTE
  • SAML_ATTRIBUTES_STATEMENTS_VERIFIED
  • SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL

Hidden services

  • http_proxy
  • ALLOW_ACCESS_TO_HIDDEN_SERVICE

Other

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.