Deploy Mastodon

Deploy and Host Mastodon on Railway

Mastodon is an open-source social network server that speaks ActivityPub, the protocol behind Threads, Pixelfed and PeerTube. Running your own instance means you own the moderation rules and the data, while members still follow and are followed by anyone on any other fediverse server. Communities, newsrooms and companies self-host it so their timeline is not somebody else's product.

Deploy Mastodon on Railway and you get the full production layout, not a single container: a Puma web service, a Node streaming service for live timelines, a Sidekiq worker tier, a dedicated scheduler, PostgreSQL, Redis, an object storage bucket, a signing gateway that serves that bucket publicly, and a Mailpit inbox so signup mail works immediately. To self-host Mastodon well you need all of that wired together, and this template does it for you.

Getting Started with Mastodon on Railway

Open the web service's public URL. An owner account is created on the first boot from MASTODON_ADMIN_USERNAME (default admin) and MASTODON_ADMIN_PASSWORD, so there is no setup wizard: sign in at /auth/sign_in with admin@ and that password, both readable in the web service's variables, then change it under Preferences → Account. Post from the composer first; if it appears in the timeline immediately, the web service, PostgreSQL and the streaming socket are healthy. Attach an image to a second post to exercise the rest — the upload goes to the bucket, Sidekiq makes the thumbnail and the media gateway serves it back, so a rendering image proves storage end to end. Then fill in the server name, description and rules under Administration → Server Settings: that text is what other servers show when someone discovers you.

New signups arrive as applications rather than instant accounts. Review them under Moderation → Accounts and switch to open or invite-only when you are ready.

About Hosting Mastodon

Each instance holds its own accounts and posts and exchanges signed ActivityPub messages with every server its members follow, so a small instance still reaches the whole network. Teams self-host to set their own moderation policy, keep member data in their own infrastructure, or run a members-only community that still federates.

Key features:

• Chronological home, local and federated timelines with no ranking algorithm
• 500-character posts, polls, content warnings, alt text and quote posts
• Moderation tooling: reports, appeals, account approvals, domain blocks
• A documented REST and streaming API dozens of mobile clients speak
• Web Push notifications, two-factor auth and single sign-on hooks

How the services fit together: web runs Puma and serves the interface, the API and inbound federation. streaming is a Node process pushing live timeline updates over WebSockets from its own domain. sidekiq runs the background queues — federation, thumbnails, e-mail — and scales to more replicas; sidekiq-scheduler runs the cron-shaped queue alone and stays at one replica. Postgres holds accounts and posts, Redis backs the cache, queues and pub/sub, and the bucket holds every avatar, header and attachment plus cached remote media. media is a signing gateway making those files publicly readable without exposing the bucket, and mailpit captures outgoing mail until you connect a real relay.

Why Deploy Mastodon on Railway

Railway removes the parts of a Mastodon install that usually take a weekend.

• Every service, database and bucket provisioned and wired in one click
• Private networking between web, workers, Postgres and Redis
• Managed PostgreSQL and Redis with backups and metrics
• Object storage for media, so no disk fills with attachments
• Health checks and restart policies per role
• Scale the worker tier from the dashboard

Common Use Cases

• A community server where a moderation team sets the rules, not a platform
• A newsroom or research group publishing to the fediverse from its own domain
• A private, invite-reviewed instance that still federates with public servers

Dependencies for Mastodon

• ghcr.io/mastodon/mastodon:v4.7.0 — Rails app, used by web and both Sidekiq services
• ghcr.io/mastodon/mastodon-streaming:v4.7.0 — streaming API, pinned to the same release
• PostgreSQL 18 — accounts, posts, relationships and moderation records
• Redis 8 — cache, Sidekiq queues and streaming pub/sub
• Railway object storage — avatars, headers, attachments, cached remote media
• axllent/mailpit:latest — capture-only SMTP server and web inbox
• Boot logic and media gateway: https://github.com/gridalpha/mastodon-railway

Environment Variables Reference

Deployment Dependencies

• Source and issues: https://github.com/mastodon/mastodon
• Self-hosting docs: https://docs.joinmastodon.org/admin/install/
• Images: https://github.com/mastodon/mastodon/pkgs/container/mastodon
• Ruby 4.0 and Node 24, supplied by the official images

Hardware Requirements for Self-Hosting Mastodon

A quiet instance fits the minimum column. Federation traffic grows the bill: every account your members follow means inbound deliveries and cached remote media. Add worker replicas before web replicas.

Self-Hosting Mastodon

Upstream ships a production docker-compose.yml:

git clone https://github.com/mastodon/mastodon.git
cd mastodon
cp .env.production.sample .env.production
docker compose run --rm web bundle exec rails mastodon:setup
docker compose up -d

That writes the generated secrets into .env.production. Web Push keys are a matched pair, so they are generated rather than invented:

docker compose run --rm web bundle exec rails mastodon:webpush:generate_vapid_key
docker compose run --rm web bin/rails db:encryption:init

You still need a reverse proxy with TLS, a mail relay and a bucket for uploads. The Railway template handles all of that and migrates on boot.

Is Mastodon Free to Self-Host?

Mastodon is free and open source under the AGPL-3.0 licence, with no paid tier, seat limits or feature gates. The only cost of self-hosting Mastodon is infrastructure: on Railway you pay for compute, the managed Postgres and Redis, and the object storage your instance uses. Costs rise with member count and cached remote media.

FAQ

What is Mastodon? An open-source, self-hostable social network server. It speaks ActivityPub, so accounts on your server follow and are followed by accounts on any other fediverse server, with no central company in the middle.

What does this Railway template deploy? A complete instance: the Puma web service, the streaming service, a Sidekiq worker tier, a dedicated scheduler, PostgreSQL, Redis, an object storage bucket with a signing gateway in front of it, and a Mailpit inbox.

Why does self-hosted Mastodon need Redis and object storage? Redis carries the Sidekiq queues, the Rails cache and the pub/sub channel the streaming service reads. Object storage holds every avatar, header and attachment plus cached media from servers your members follow — that grows fast and does not belong on a disk.

How do I change my Mastodon server's domain after deploying? You do not. LOCAL_DOMAIN goes into every ActivityPub identifier your server emits, so changing it breaks existing follows. Attach your custom domain to the web service and set LOCAL_DOMAIN to it before anyone signs up.

How do I send real e-mail from self-hosted Mastodon? Mailpit captures mail so confirmation and password-reset flows work immediately, but never delivers it. Point the SMTP_* variables at a real provider before inviting members. Any SMTP host works.

Can I scale Mastodon's background workers on Railway? Yes — raise the replica count on the sidekiq service as federation traffic grows. Leave sidekiq-scheduler at one replica: it runs the recurring jobs, and a second copy would run each of them twice.

How do I enable full-text search in self-hosted Mastodon? Search over your own posts needs Elasticsearch, left out to keep the footprint small. Add an Elasticsearch service, set ES_ENABLED, ES_HOST and ES_PORT on the web and Sidekiq services, then run tootctl search deploy.