Mastodon

Mastodon is a free, open-source social network, written in Ruby. A decentralized alternative to commercial platforms, it avoids the risks of a single company monopolizing your communication. Pick a server that you trust — whichever you choose, you can interact with everyone else. Anyone can run their own Mastodon instance and participate in the social network seamlessly.

Server

Installation

Install the mastodon^AUR package.

The package installs Mastodon in /var/lib/mastodon and provides the required systemd units. PostgreSQL and Valkey are installed as dependencies.

Note If you only want to join a Mastodon instance to post and read content, installing a client is enough. You do not need the mastodon^AUR package for that.

Configuration

PostgreSQL

Initialize PostgreSQL if it has not already been initialized. See PostgreSQL#Initial configuration.

Enable/start postgresql.service.

Create a PostgreSQL role for Mastodon:

[postgres]$ createuser --createdb mastodon

Using a PostgreSQL role with the same name as the Mastodon system user allows local peer authentication to be used without storing a database password.

Valkey

Mastodon requires a Redis-compatible key-value store. The mastodon^AUR package uses valkey for this purpose.

Enable/start valkey.service.

The default local Valkey instance listens on 127.0.0.1:6379. Mastodon retains the REDIS_* configuration variable names when Valkey is used.

Valkey Sentinel is not required for a normal single-server installation.

See Valkey for additional configuration.

Mastodon

Run the interactive Mastodon setup as the mastodon user:

# cd /var/lib/mastodon
[mastodon]$ RAILS_ENV=production bin/rails mastodon:setup

The setup wizard creates /var/lib/mastodon/.env.production and initializes the database schema.

Warning Keep a secure backup of .env.production. It contains secrets required by the Mastodon instance.

Production assets are provided by the Arch package and normally do not need to be built manually.

Web server and HTTPS

Mastodon provides an nginx configuration template in /var/lib/mastodon/dist/nginx.conf. The upstream template assumes a source installation under /home/mastodon/live; when using the Arch package, the document root must instead point to /var/lib/mastodon/public.

Install nginx, then create a Mastodon server configuration. The following is a shortened example based on the configuration shipped with Mastodon:

/etc/nginx/conf.d/mastodon.conf

map $http_upgrade $connection_upgrade {
    default upgrade;
     close;
}

upstream mastodon_backend {
    server 127.0.0.1:3000 fail_timeout=0;
}

upstream mastodon_streaming {
    least_conn;
    server 127.0.0.1:4000 fail_timeout=0;
}

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=MASTODON:10m inactive=7d max_size=1g;

server {
    listen 80;
    listen [::]:80;
    server_name mastodon.example.com;

    root /var/lib/mastodon/public;

    location /.well-known/acme-challenge/ {
        allow all;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name mastodon.example.com;

    root /var/lib/mastodon/public;

    ssl_certificate /etc/letsencrypt/live/mastodon.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mastodon.example.com/privkey.pem;

    client_max_body_size 99m;
    proxy_read_timeout 120;
    sendfile on;

    location / {
        add_header Strict-Transport-Security "max-age=63072000; includeSubDomains";
        try_files $uri @mastodon;
    }

    location ^~ /assets/ {
        add_header Cache-Control "public, max-age=2419200, must-revalidate";
    }

    location ^~ /system/ {
        add_header Cache-Control "public, max-age=2419200, immutable";
        add_header X-Content-Type-Options nosniff;
        add_header Content-Security-Policy "default-src 'none'; form-action 'none'";
    }

    location ^~ /api/v1/streaming {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Proxy "";

        proxy_pass http://mastodon_streaming;
        proxy_buffering off;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    location @mastodon {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Proxy "";

        proxy_pass http://mastodon_backend;
        proxy_buffering on;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_cache MASTODON;
        proxy_cache_valid 200 7d;
        proxy_cache_valid 410 24h;
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
    }

    error_page 404 500 501 502 503 504 /500.html;
}

Note This is intentionally a shortened example. Prefer the dist/nginx.conf shipped with the installed Mastodon version for the complete set of static-file locations, caching rules and security headers, while adapting its source-installation paths to /var/lib/mastodon.

Obtain the certificate before enabling the TLS server block shown above. During initial certificate issuance, use an HTTP server block for the domain.

For Let's Encrypt, install certbot and certbot-nginx. Once DNS points to the server and nginx has a server block for the domain, request a certificate with:

# certbot --nginx --agree-tos --redirect --email admin@example.com -d mastodon.example.com

Alternatively, obtain the certificate without asking Certbot to modify the nginx configuration:

# certbot certonly --nginx -d mastodon.example.com

Certbot stores the certificate and private key under /etc/letsencrypt/live/mastodon.example.com/.

Check the nginx configuration:

# nginx -t

Then reload nginx.service.

Test certificate renewal with:

# certbot renew --dry-run

See Certbot for automatic renewal and other ACME challenge methods.

Starting Mastodon

The package provides systemd services for the web application, Sidekiq workers and the streaming server.

Enable/start mastodon-web.service, mastodon-sidekiq.service and mastodon-streaming.service.

By default, mastodon-streaming.service starts mastodon-streaming@4000.service.

Note mastodon-streaming.service is a oneshot unit used to manage the streaming instances. Seeing it as active (exited) while mastodon-streaming@4000.service is running is expected.

The parent mastodon-streaming.service starts mastodon-streaming@4000.service by default. Check the status of these units when troubleshooting.

Creating the administrator account

After Mastodon is running, create the first administrator account:

# cd /var/lib/mastodon
[mastodon]$ RAILS_ENV=production bin/tootctl accounts create USERNAME --email USER@example.com --confirmed --role Owner

Approve the account:

[mastodon]$ RAILS_ENV=production bin/tootctl accounts modify USERNAME --approve

Command-line administration

Mastodon provides the tootctl administration utility. Unless otherwise specified, run the following commands from /var/lib/mastodon as the mastodon user with RAILS_ENV=production.

Display the available commands:

[mastodon]$ cd /var/lib/mastodon
[mastodon]$ RAILS_ENV=production bin/tootctl help

Some useful commands are:

[mastodon]$ RAILS_ENV=production bin/tootctl --version
[mastodon]$ RAILS_ENV=production bin/tootctl media usage
[mastodon]$ RAILS_ENV=production bin/tootctl cache clear

Remove cached remote media older than 7 days:

[mastodon]$ RAILS_ENV=production bin/tootctl media remove --days 7

Preview the removal of cached remote profile images older than 30 days:

[mastodon]$ RAILS_ENV=production bin/tootctl media remove --days 30 --prune-profiles --dry-run

Remove old preview-card thumbnails:

[mastodon]$ RAILS_ENV=production bin/tootctl preview_cards remove --days 180 --concurrency 4

Check for remote accounts which no longer exist without modifying the database:

[mastodon]$ RAILS_ENV=production bin/tootctl accounts cull --dry-run

Refresh remote media from the last day:

[mastodon]$ RAILS_ENV=production bin/tootctl media refresh --days 1

See the upstream Mastodon administration CLI documentation for the complete list of commands and their effects.

Moving media storage

The Mastodon systemd units use systemd filesystem sandboxing. If public/system is moved outside /var/lib/mastodon, the new location must be added to ReadWritePaths for services that need to write there.

For example, to allow an external mount:

# systemctl edit mastodon-web.service

Add:

[Service]
ReadWritePaths=/var/lib/mastodon /mnt/mastodon

Apply an equivalent override to mastodon-sidekiq.service if Sidekiq also needs access to the external media storage.

When using a symbolic link for /var/lib/mastodon/public/system, ensure that the target is writable by the mastodon user and permitted by the relevant systemd unit sandbox.

Upgrading

Before upgrading Mastodon, make a verified PostgreSQL backup and back up /var/lib/mastodon/.env.production and locally stored media.

The package does not automatically restart Mastodon services after an upgrade. Read the messages printed by pacman before restarting the services.

For upgrades where no manual database migration is required, restart mastodon-web.service, mastodon-sidekiq.service and mastodon-streaming.service, then verify their status.

Warning Some Mastodon upgrades require separate pre-deployment and post-deployment database migrations. Follow the instructions printed by the package and consult the upstream release notes before restarting the services.