Mastodon is decentralised social media: thousands of independent servers (“instances”) that federate through ActivityPub, so users on any server can follow each other. Running your own instance, for yourself, your company or your community, gives you control over moderation, data and branding. It’s also a real operational commitment, so understand what’s involved first.

Before you start

  • Domain: usernames look like @[email protected]. The domain is permanent, and changing it later effectively means starting over. You can use a subdomain for the server while users get handles on your main domain (WEB_DOMAIN vs LOCAL_DOMAIN), but that must be decided before the first start.
  • Moderation: you’re responsible for your users’ content, reports, blocking problem servers, and legal requests. Read the moderation docs, and write server rules.
  • Costs grow with media: federation means your server caches images and videos from everyone your users follow. Storage and bandwidth grow over time.

Sizing

Instance VPS Notes
Single user / few users 2 vCPU, 4 GB RAM, 40+ GB SSD Use object storage for media
Small community (≤500 active) 4 vCPU, 8 GB RAM Separate Sidekiq queues as it grows
Larger Multiple servers: DB, Redis, web, Sidekiq Plan carefully

Lightweight alternatives for single-user instances: GoToSocial, Akkoma or Pleroma use far fewer resources.

Components

  • Puma (Rails web app) and the streaming server (Node.js), behind Nginx;
  • Sidekiq background workers (federation, media processing, emails);
  • PostgreSQL and Redis;
  • optional Elasticsearch/OpenSearch for full-text search;
  • object storage (S3-compatible) for media, strongly recommended.

Installation options

Docker Compose (from the Mastodon repository’s docker-compose.yml) is the quickest way to get the services running. Run the interactive setup:

git clone https://github.com/mastodon/mastodon /opt/mastodon && cd /opt/mastodon
git checkout v4.3.4          # latest release tag
cp .env.production.sample .env.production
docker compose run --rm web bundle exec rake mastodon:setup
docker compose up -d

The wizard asks for the domain, database and Redis settings, object storage, SMTP, and creates the admin account. It writes .env.production.

Native install (Ubuntu or Debian, following the official “Installing from source” guide) gives more control, and is common for production instances.

Nginx and HTTPS

Mastodon ships an Nginx config template (dist/nginx.conf). Adapt server_name, the paths, and certificates from Certbot. It handles static assets, the streaming WebSocket endpoint (/api/v1/streaming), and proxying to Puma (port 3000) and streaming (port 4000). See Nginx WebSocket proxy and Let’s Encrypt.

Media storage

Local disk fills up quickly with cached remote media. Use S3-compatible storage (a provider, or your own MinIO), set via S3_ENABLED=true and related variables. Optionally put a CDN or caching proxy in front. See MinIO.

Schedule cache cleanup:

# remove cached remote media older than 7 days (adjust)
docker compose run --rm web bin/tootctl media remove --days 7
docker compose run --rm web bin/tootctl preview_cards remove --days 30

Run these from cron or a systemd timer. See crontab.

Email

Mastodon needs SMTP for sign-up confirmations and notifications. Use a transactional provider. See transactional email services.

Registrations and moderation

  • Choose registration mode: closed (single-user), approval required, or open (only with active moderators).
  • Set server rules, and configure report handling.
  • Domain blocks: limit or suspend servers known for abuse. Many admins subscribe to shared blocklists.
  • Review reports promptly.

Maintenance

  • Backups: PostgreSQL dumps, .env.production (contains secrets), and Redis (optional). Media in object storage needs its own durability or backups. See database backup automation.
  • Upgrades: follow each release’s upgrade notes (migrations, sometimes extra steps), and back up first. See updating self-hosted apps.
  • Monitoring: Sidekiq queue sizes (in the admin dashboard), disk and storage usage, and server load. See uptime monitoring tools.
  • Security: keep the OS and Mastodon patched. Security releases happen. See patch management.

Quick reference

Item Value
Web (Puma) port 3000
Streaming port 4000, /api/v1/streaming
Setup wizard rake mastodon:setup
Admin CLI bin/tootctl
Clean remote media tootctl media remove --days N
Config .env.production

Related: Matrix Synapse and Discourse forum.

  • Self-Hosting
  • Fediverse
  • Docker