### Configure and Enable Systemd Services Source: https://docs.joinmastodon.org/admin/install Copies Mastodon systemd service templates, allows for manual editing of configurations, and enables the services to start automatically on system boot. ```bash cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/ $EDITOR /etc/systemd/system/mastodon-*.service systemctl daemon-reload systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming ``` -------------------------------- ### Install Tor on Debian Source: https://docs.joinmastodon.org/admin/optional/tor Commands to add the Tor project repository, import the GPG key, and install the necessary Tor packages on a Debian-based system. ```bash deb https://deb.torproject.org/torproject.org stretch main deb-src https://deb.torproject.org/torproject.org stretch main curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --import gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | apt-key add - apt install tor deb.torproject.org-keyring ``` -------------------------------- ### Install PgBouncer Source: https://docs.joinmastodon.org/admin/scaling Installs the PgBouncer connection pooler on Debian-based systems. PgBouncer helps manage PostgreSQL connection limits, preventing the database from becoming overloaded. ```bash sudo apt install pgbouncer ``` -------------------------------- ### Obtain SSL Certificate with Certbot Source: https://docs.joinmastodon.org/admin/optional/object-storage-proxy Instructions to obtain and install an SSL certificate for the configured domain using Certbot, followed by reloading Nginx. ```bash certbot --nginx -d files.example.com systemctl reload nginx ``` -------------------------------- ### Nginx Redirect for Webfinger with CORS Source: https://docs.joinmastodon.org/admin/config This Nginx configuration snippet demonstrates how to redirect /.well-known/webfinger requests to a different domain while including necessary CORS headers. This is crucial for Mastodon's multi-domain setup where the user-facing domain differs from the Mastodon installation domain. ```nginx location /.well-known/webfinger { add_header Access-Control-Allow-Origin '*'; return 301 https://mastodon.example.com$request_uri; } ``` -------------------------------- ### Custom Webhook Payload Template Source: https://docs.joinmastodon.org/admin/webhooks An example of a custom JSON template for webhooks. It demonstrates how to use the double-braces syntax to dynamically insert the username from the event object into the payload. ```json { "content": "Hello {{object.username}}" } ``` -------------------------------- ### Post-Migration Service and Asset Initialization Source: https://docs.joinmastodon.org/admin/migrating Commands to compile assets as the mastodon user and restart system services as the root user to ensure the instance is operational after a migration. ```bash RAILS_ENV=production bundle exec rails assets:precompile systemctl daemon-reload systemctl start redis-server systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming systemctl restart nginx ``` -------------------------------- ### CLI: tootctl accounts create Source: https://docs.joinmastodon.org/admin/tootctl Create a new local user account. ```APIDOC ## CLI tootctl accounts create ### Description Creates a new local user account with a specified username and email. ### Method CLI Command ### Parameters #### Positional Arguments - **USERNAME** (string) - Required - Local username for the new account. #### Options - **--email** (string) - Required - Email address to be attached to the user. - **--confirmed** (flag) - Optional - Skip sending the confirmation email and activate immediately. - **--role** (string) - Optional - Assign a custom role (e.g., Owner, Admin, Moderator). - **--reattach** (flag) - Optional - Reuse an old username after deletion. - **--force** (flag) - Optional - Forcefully delete existing account with same username. ``` -------------------------------- ### Manage Nginx Service and Configuration Source: https://docs.joinmastodon.org/admin/optional/tor Commands to restart the Nginx service and instructions for adjusting the server_names_hash_bucket_size if errors occur during startup. ```bash service nginx restart # If bucket size error occurs, uncomment in nginx.conf: # server_names_hash_bucket_size 64; ``` -------------------------------- ### Configure Nginx for Mastodon Source: https://docs.joinmastodon.org/admin/install Copies the Mastodon Nginx template, creates a symbolic link to enable the site, and removes the default configuration. This prepares the server to handle incoming web requests for the Mastodon instance. ```bash cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon rm /etc/nginx/sites-enabled/default ``` -------------------------------- ### Manage MinIO via Command Line Client Source: https://docs.joinmastodon.org/admin/optional/object-storage Common commands for the MinIO Client (mc) to create buckets, set policies, and manage users for Mastodon integration. ```bash mc mb myminio/mastodata mc anonymous set-json anonymous-readonly-policy.json myminio/mastodata mc admin policy add myminio mastodon-readwrite mastodon-readwrite.json mc admin user add myminio mastodon SECRET_PASSWORD mc admin policy set myminio mastodon-readwrite user=mastodon ``` -------------------------------- ### Configure Separate Redis Instance for Sidekiq Source: https://docs.joinmastodon.org/admin/scaling Steps to create a dedicated Redis systemd service and configuration file for Sidekiq. This helps isolate Sidekiq's workload from the main Redis instance. ```bash cp /etc/systemd/system/redis.service /etc/systemd/system/redis-sidekiq.service # Edit redis-sidekiq.service to update ExecStart, PIDFile, ReadWritePaths, and Alias cp /etc/redis/redis.conf /etc/redis/redis-sidekiq.conf # Edit redis-sidekiq.conf to update port, pidfile, logfile, and dir mkdir /var/lib/redis-sidekiq chown redis /var/lib/redis-sidekiq systemctl enable --now redis-sidekiq ``` -------------------------------- ### Example Report Created Payload Source: https://docs.joinmastodon.org/admin/webhooks This JSON payload represents a 'report.created' event, detailing a violation report. It includes information about the reporting account, the target account, and associated statuses. The structure is crucial for understanding moderation actions and user data within the Mastodon admin interface. ```json { "event": "report.created", "created_at": "2023-10-26T13:34:00.351Z", "object": { "id": "8437", "action_taken": false, "action_taken_at": null, "category": "violation", "comment": "", "forwarded": true, "created_at": "2023-10-26T13:34:00.348Z", "updated_at": "2023-10-26T13:34:00.348Z", "account": { "id": "123456789", "username": "bobisaburger", "domain": null, "created_at": "2023-07-13T04:39:22.493Z", "email": "bobisaburger@emailservice.com", "ip": "12.34.56.78", "confirmed": true, "suspended": false, "silenced": false, "sensitized": false, "disabled": false, "approved": true, "locale": "en", "invite_request": "I would love to be a member of your instance!", "ips": [ { "ip": "12.34.56.78", "used_at": "2023-07-13T04:45:31.835Z" }, { "ip": "98.76.54.32", "used_at": "2023-07-13T04:39:22.722Z" } ], "account": { "id": "123456789", "username": "bobisaburger", "acct": "bobisaburger", "display_name": "bobisaburger", "locked": false, "bot": false, "discoverable": null, "group": false, "created_at": "2023-07-13T00:00:00.000Z", "note": "", "url": "https://mastodonwebsite/@bobisaburger", "uri": "https://mastodonwebsite/users/bobisaburger", "avatar": "https://locationofavatar.com/image.jpg", "avatar_static": "https://locationofavatar.com/image.jpg", "header": "locationofheader.com/image.jpg", "header_static": "locationofheader.com/image.jpg", "followers_count": 100, "following_count": 200, "statuses_count": 9, "last_status_at": "2023-08-05", "noindex": true, "emojis": [], "roles": [], "fields": [] }, "role": { "id": "-99", "name": "", "permissions": "65536", "color": "", "highlighted": false } }, "target_account": { "id": "123454321", "username": "cheeseperson", "domain": "someothermastodonsite.com", "created_at": "2023-08-20T00:00:00.000Z", "email": null, "ip": null, "confirmed": null, "suspended": false, "silenced": false, "sensitized": false, "disabled": null, "approved": null, "locale": null, "invite_request": null, "ips": null, "account": { "id": "123454321", "username": "cheeseperson", "acct": "cheeseperson@someothermastodonsite.com", "display_name": "cheeseperson", "locked": false, "bot": false, "discoverable": false, "group": false, "created_at": "2023-08-20T00:00:00.000Z", "note": "", "url": "https://someothermastodonsite.com/@cheeseperson", "uri": "https://someothermastodonsite.com/users/cheeseperson", "avatar": "https://someothermastadonsite.com/avatars/original/missing.png", "avatar_static": "https://someothermastadonsite.com/avatars/original/missing.png", "header": "locationofheader.com/image.jpg", "header_static": "locationofheader.com/image.jpg", "followers_count": 2, "following_count": 2, "statuses_count": 95, "last_status_at": "2023-10-26", "emojis": [], "fields": [] }, "role": null }, "assigned_account": null, "action_taken_by_account": null, "statuses": [ { "id": "12345678987654321", "created_at": "2023-10-26T11:29:13.000Z", "in_reply_to_id": "1918282746465", "in_reply_to_account_id": "101010101010", "sensitive": false, "spoiler_text": "", "visibility": "public", "language": "de", "uri": "https://someothermastodonsite.com/users/cheeseperson/statuses/111301083360371621", "url": "https://someothermastodonsite.com/@cheeseperson/111301083360371621", "replies_count": 0, "reblogs_count": 0, "favourites_count": 0, "edited_at": "2023-10-26T11:30:31.000Z", "content": "

Here is some content

", "reblog": null, "account": { "id": "123454321", "username": "cheeseperson", "acct": "cheeseperson@someothermastodonsite.com", "display_name": "cheeseperson", "locked": false, "bot": false, "discoverable": false, "group": false, "created_at": "2023-08-20T00:00:00.000Z", "note": "", "url": "https://someothermastodonsite.com/@cheeseperson", "uri": "https://someothermastodonsite.com/users/cheeseperson", "avatar": "https://someothermastadonsite.com/avatars/original/missing.png", "avatar_static": "https://someothermastadonsite.com/avatars/original/missing.png" } } ] } } ``` -------------------------------- ### Configure Mastodon environment variables Source: https://docs.joinmastodon.org/admin/scaling Settings for the .env.production file to point Mastodon to the PgBouncer port and disable prepared statements. ```text PREPARED_STATEMENTS=false DB_HOST=localhost DB_USER=mastodon DB_NAME=mastodon_production DB_PASS=password DB_PORT=6432 ``` -------------------------------- ### tootctl self-destruct command Source: https://docs.joinmastodon.org/admin/tootctl The `tootctl self-destruct` command is used to erase a Mastodon server from the federation by broadcasting account deletion activities. This command is interactive and requires confirmation. Since Mastodon 4.3.0, it guides the user to switch the server to a self-destruct mode instead of enqueuing jobs immediately. This operation is irreversible and can leave the server in a broken state. ```bash RAILS_ENV=production bin/tootctl self-destruct ``` -------------------------------- ### Enable Nginx Site Configuration Source: https://docs.joinmastodon.org/admin/optional/object-storage-proxy Commands to enable the Nginx configuration file and reload the Nginx service to apply the changes. ```bash ln -s /etc/nginx/sites-available/files.example.com /etc/nginx/sites-enabled/ systemctl reload nginx ``` -------------------------------- ### Copy Mastodon System Files (Rsync) Source: https://docs.joinmastodon.org/admin/migrating Copies the Mastodon system files, typically user-uploaded images and videos, from the old server to the new server using rsync. This ensures that all media content is transferred. ```bash rsync -avz ~/live/public/system/ mastodon@example.com:~/live/public/system/ ``` -------------------------------- ### Configure PgBouncer Userlist Source: https://docs.joinmastodon.org/admin/scaling Adds user credentials to PgBouncer's userlist.txt file. This file maps users to their authentication details, allowing PgBouncer to manage connections to PostgreSQL. ```bash "mastodon" "md5d75bb2be2d7086c6148944261a00f605" "pgbouncer" "md5a45753afaca0db833a6f7c7b2864b9d9" ``` -------------------------------- ### Media CLI Source: https://docs.joinmastodon.org/admin/tootctl Commands for managing locally cached media attachments, avatars, and headers. ```APIDOC ## tootctl media remove ### Description Removes locally cached copies of media attachments, avatars, or profile headers from other servers. ### Method CLI Command ### Endpoint tootctl media remove ### Parameters #### Query Parameters - **--days N** (integer) - Optional - Age in days for media attachments to be removed. For avatars and headers, it's the age of the last webfinger request/update. Defaults to 7. - **--concurrency N** (integer) - Optional - The number of workers to use for this task. Defaults to 5. - **--prune-profiles** (boolean) - Optional - Remove locally cached copies of avatars and headers instead of media attachments. Cannot be combined with `--remove-headers`. - **--remove-headers** (boolean) - Optional - Remove locally cached copies of headers instead of media attachments. Cannot be combined with `--prune-profiles`. - **--include-follows** (boolean) - Optional - When used with `--prune-profiles` or `--remove-headers`, removes cached copies regardless of follow status. By default, only removes from accounts not followed locally. - **--verbose** (boolean) - Optional - Print additional information while the task is processing. - **--dry-run** (boolean) - Optional - Print expected results only, without performing any actions. ### Request Example ```bash tootctl media remove --days 30 --prune-profiles --include-follows --verbose ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message indicating the media removal process status and amount of space freed. #### Response Example ```json { "message": "Removed 15.2 GB of old media attachments. Processed 5000 files." } ``` ``` -------------------------------- ### Create Mastodon Admin Account Source: https://docs.joinmastodon.org/admin/setup Creates a new user account with administrative privileges using the Mastodon command-line tool. This is necessary because registrations are disabled by default. It requires specifying the username, email, and role, and outputs a randomly generated password. ```bash RAILS_ENV=production bin/tootctl accounts create \ alice \ --email alice@example.com \ --confirmed \ --role Owner ``` -------------------------------- ### tootctl --version command Source: https://docs.joinmastodon.org/admin/tootctl Displays the version of the currently running Mastodon instance. This command is useful for checking compatibility and understanding feature availability. ```bash RAILS_ENV=production bin/tootctl --version ``` -------------------------------- ### Populate Elasticsearch Indices (Bash) Source: https://docs.joinmastodon.org/admin/elasticsearch This command initiates the process of creating and populating Elasticsearch indices with data for Mastodon's search functionality. It is executed as the 'mastodon' user within the Mastodon live directory. ```bash su - mastodon cd live RAILS_ENV=production bin/tootctl search deploy ``` -------------------------------- ### Save and Copy Redis Database (Redis & Rsync) Source: https://docs.joinmastodon.org/admin/migrating Saves the current Redis database to disk and then copies the database file from the old server to the new server using rsync. This preserves unprocessed Sidekiq jobs. ```bash redis-cli SAVE systemctl stop redis-server.service rsync -avz /var/lib/redis/ root@example.com:/var/lib/redis ``` -------------------------------- ### Precompile Mastodon Assets (Rails) Source: https://docs.joinmastodon.org/admin/migrating Compiles Mastodon's front-end assets using the Rails asset pipeline. This command should be run on the new server after migrating files and the database. ```bash RAILS_ENV=production bundle exec rails assets:precompile ``` -------------------------------- ### Add Extra Media Hosts in Mastodon Source: https://docs.joinmastodon.org/admin/optional/object-storage-proxy Optional configuration for Mastodon to include additional media hosts, particularly if the S3_ALIAS_HOST uses redirection. ```bash EXTRA_MEDIA_HOSTS=https://data.example1.com,https://data.example2.com ``` -------------------------------- ### Verify PgBouncer connectivity and logs Source: https://docs.joinmastodon.org/admin/scaling Commands to test the connection to the PgBouncer instance and monitor its operational logs. ```bash psql -p 6432 -U mastodon mastodon_production tail -f /var/log/postgresql/pgbouncer.log ``` -------------------------------- ### Configure PostgreSQL Read-Replica Environment Variables Source: https://docs.joinmastodon.org/admin/scaling Environment variables required to enable read-replica support in Mastodon 4.2+. These variables allow the application to offload read-only queries to a secondary database instance. ```text REPLICA_DB_HOST REPLICA_DB_PORT REPLICA_DB_NAME REPLICA_DB_USER REPLICA_DB_PASS REPLICA_PREPARED_STATEMENTS REPLICA_DB_TASKS ``` -------------------------------- ### Restart Mastodon Services Source: https://docs.joinmastodon.org/admin/scaling Command to restart the web and Sidekiq services to apply configuration changes. ```bash systemctl restart mastodon-web.service systemctl restart redis-sidekiq.service ``` -------------------------------- ### Restart Mastodon Services (Systemd) Source: https://docs.joinmastodon.org/admin/elasticsearch These systemd commands are used to restart and reload Mastodon services after configuration changes. 'mastodon-sidekiq' is restarted to apply changes related to background job processing, and 'mastodon-web' is reloaded to refresh the web interface. ```bash systemctl restart mastodon-sidekiq systemctl reload mastodon-web ``` -------------------------------- ### Importing and Exporting Server Blocklists Source: https://docs.joinmastodon.org/admin/moderation This describes the process of importing a server blocklist file (.csv) to block problematic servers and exporting your server's blocklist for backup or sharing. It involves navigating to Preferences > Moderation > Federation. -------------------------------- ### Set Directory Permissions and Restart Nginx Source: https://docs.joinmastodon.org/admin/install Grants execute permissions to the Mastodon home directory to allow the Nginx user access to assets, followed by a service restart to apply configuration changes. ```bash chmod o+x /home/mastodon systemctl restart nginx ``` -------------------------------- ### Configure Elasticsearch JVM Heap Size (Java Properties) Source: https://docs.joinmastodon.org/admin/elasticsearch This configuration snippet is used to set the initial and maximum heap size for the Elasticsearch Java Virtual Machine (JVM). It is placed in a file within `/etc/elasticsearch/jvm.options.d/` and helps prevent Elasticsearch crashes during index creation by allocating sufficient memory. ```properties # Xms represents the initial size of total heap space # Xmx represents the maximum size of total heap space # Both values should be the same -Xms2048m -Xmx2048m ``` -------------------------------- ### Configure pgbouncer.ini settings Source: https://docs.joinmastodon.org/admin/scaling Defines the database connection strings, listening address, authentication type, and pooling mode required for Mastodon to operate with PgBouncer. ```ini [databases] mastodon_production = host=127.0.0.1 port=5432 dbname=mastodon_production user=mastodon password=password listen_addr = 127.0.0.1 listen_port = 6432 auth_type = md5 admin_users = pgbouncer pool_mode = transaction max_client_conn = 100 default_pool_size = 20 ``` -------------------------------- ### Acquire SSL Certificate with Certbot Source: https://docs.joinmastodon.org/admin/install Uses Certbot to automatically obtain an SSL certificate from Let's Encrypt for a specified domain using the Nginx plugin. The resulting certificates are stored in the /etc/letsencrypt/live directory. ```bash certbot certonly --nginx -d example.com ``` -------------------------------- ### Configure Mastodon to Use S3 Alias Host Source: https://docs.joinmastodon.org/admin/optional/object-storage-proxy Update Mastodon's environment variables to use the new Nginx proxy as the S3 alias host for media files. ```bash S3_ALIAS_HOST=files.example.com ``` -------------------------------- ### Nginx Configuration for Object Storage Proxy Source: https://docs.joinmastodon.org/admin/optional/object-storage-proxy This Nginx configuration sets up a reverse proxy to serve files from an object storage provider. It includes SSL, caching, cache locking, and custom headers for optimal performance and integration with Mastodon. Ensure you replace placeholders like `files.example.com`, `YOUR_BUCKET_NAME`, and `YOUR_S3_HOSTNAME` with your actual values. ```nginx server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name files.example.com; root /var/www/html; ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key; keepalive_timeout 30; location = / { index index.html; } location / { try_files $uri @s3; } set $s3_backend 'https://YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME'; location @s3 { limit_except GET { deny all; } resolver 8.8.8.8; proxy_set_header Host YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME; proxy_set_header Connection ''; proxy_set_header Authorization ''; proxy_hide_header Set-Cookie; proxy_hide_header 'Access-Control-Allow-Origin'; proxy_hide_header 'Access-Control-Allow-Methods'; proxy_hide_header 'Access-Control-Allow-Headers'; proxy_hide_header x-amz-id-2; proxy_hide_header x-amz-request-id; proxy_hide_header x-amz-meta-server-side-encryption; proxy_hide_header x-amz-server-side-encryption; proxy_hide_header x-amz-bucket-region; proxy_hide_header x-amzn-requestid; proxy_ignore_headers Set-Cookie; proxy_pass $s3_backend$uri; proxy_intercept_errors off; proxy_cache CACHE; proxy_cache_valid 200 48h; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; proxy_cache_lock on; expires 1y; add_header Cache-Control public; add_header 'Access-Control-Allow-Origin' '*'; add_header X-Cache-Status $upstream_cache_status; add_header X-Content-Type-Options nosniff; add_header Content-Security-Policy "default-src 'none'; form-action 'none'"; } } ``` -------------------------------- ### Restore PostgreSQL Database (PostgreSQL) Source: https://docs.joinmastodon.org/admin/migrating Restores a PostgreSQL database from a custom-format archive file. This command is used on the new server to import the backed-up database, with options to parallelize the restore process. ```bash createdb -T template0 mastodon_production pg_restore -Fc -j# -U mastodon -n public --no-owner --role=mastodon \ -d mastodon_production backup.dump ``` -------------------------------- ### Run Specific Sidekiq Queue Source: https://docs.joinmastodon.org/admin/scaling Initiates a Sidekiq process to exclusively handle tasks from a specified queue. This is useful for isolating or prioritizing certain types of background jobs. ```bash bundle exec sidekiq -q default ``` -------------------------------- ### Maintenance CLI Source: https://docs.joinmastodon.org/admin/tootctl Commands for performing maintenance tasks on the Mastodon instance. ```APIDOC ## tootctl maintenance fix-duplicates ### Description Fixes corrupted database indexes by deleting or merging duplicate accounts, statuses, emojis, etc. Requires Mastodon to be stopped and can be a lengthy and destructive process. ### Method CLI Command ### Endpoint tootctl maintenance fix-duplicates ### Parameters None ### Request Example ```bash tootctl maintenance fix-duplicates ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message indicating the duplicate fixing process has completed. #### Response Example ```json { "message": "Database indexes have been fixed and duplicates resolved." } ``` ``` -------------------------------- ### Create Mastodon Elasticsearch User (Bash) Source: https://docs.joinmastodon.org/admin/elasticsearch This command creates a new Elasticsearch user named 'mastodon' and assigns it the 'mastodon_full_access' role. You need to provide the Elasticsearch admin credentials and a strong password for the new user. This user will be used by the Mastodon server to connect to Elasticsearch. ```bash curl -X POST -u elastic:admin_password "localhost:9200/_security/user/mastodon?pretty" -H 'Content-Type: application/json' -d' { "password" : "l0ng-r4nd0m-p@ssw0rd", "roles" : ["mastodon_full_access"] } ' ```