What is Mastodon?

Mastodon is free, open-source server software for a microblogging social network. Each installation, called a server or instance, hosts its own accounts, posts, media and moderation rules. Servers communicate through the W3C ActivityPub standard, so users on one server can follow and reply to accounts on other Mastodon servers and on other software that implements the protocol. Eugen Rochko started the project in 2016, with the first public launch in October 2016. The about page describes Mastodon GmbH in Germany and Mastodon, Inc., a 501(c)(3) non-profit in the United States, and a move begun in 2025 toward a new foundation with community governance.

The server is distributed as source code on GitHub and as official container images, ghcr.io/mastodon/mastodon and ghcr.io/mastodon/mastodon-streaming. The repository includes a docker-compose file with PostgreSQL, Redis, web, streaming and Sidekiq services, plus configurations for Heroku and Scalingo. A separate Helm chart covers Kubernetes, and the installation guide describes a from-source setup on Ubuntu 24.04 or Debian 13 with nginx, certbot and three systemd services. Users reach a server through the web interface, the official iOS and Android apps or third-party clients.

The current stable release is v4.7.5, published November 3, 2026. It is a security release: it fixes a password authentication bypass for inactive accounts, a denial of service through JSON-LD compaction and a case where the Forwarded header took precedence over X-Forwarded-For. Maintenance releases 4.6.11, 4.5.21 and 4.4.28 shipped the same day. Version 4.7.0, from August 2026, reworked the internals: local private keys are encrypted at rest, outgoing RFC 9421 HTTP Message Signatures are added as a fallback, Object Integrity Proofs are verified and remote accounts can change handles. Version 4.6.0 added collections, email subscriptions, a redesigned profile and role-based two-factor requirements; 4.5.0 introduced quote posts. A 5.0.0 beta with a redesigned web interface was published on November 4, 2026 as a pre-release.

Ruby on Rails serves the REST API and web pages, PostgreSQL is the main database, Redis and Sidekiq handle caching and background jobs, Node.js runs the streaming API, and React with Redux drives the web interface. The 4.7 series needs Ruby 3.3 or newer, PostgreSQL 14+, Redis 7.0+, Node.js 22+, libvips 8.13+ and FFmpeg 5.1+, with Elasticsearch 7.x recommended for full-text search and LibreTranslate optional. The 5.0 beta raises this to Ruby 4.0, Node.js 24 and Redis 7.2.

The code is licensed under the GNU Affero General Public License version 3 or any later version. Mastodon is not an end-to-end encrypted messenger: the posting documentation states that private mentions can be read by server database administrators. Hosting, email delivery, object storage and moderation staff are the operator's responsibility; the project does not sell a hosted plan for running your own server.

Inside the application

Mastodon screenshots

Explore the interface. Open a screenshot to view it at full size.

View full size ↗

Mastodon screenshot 1

The redesigned profile editing view on the demo.joinmastodon.org server, running a 4.6.0 nightly build. Official screenshot from the Mastodon blog.

View full size ↗

Mastodon 5.0 web interface

The redesigned 5.0 web interface on a demo server running a 4.8.0 nightly build, with the composer opened at the bottom of the main column. Pre-release design, not the 4.7 stable interface.

View full size ↗

Overview landing page

The overview landing page added in 4.6.0, showing the latest 40 posts from accounts on the server to visitors who are not logged in. Official screenshot from the Mastodon blog.

View full size ↗

Mute, block and report controls

Official illustration of the user safety controls: mute, block and report actions, and media hidden behind a sensitive content warning.

View full size ↗

Post visibility and alt text

Official illustration of the composer with the per-post visibility menu and an alt text field for the attached image.

Source: official Mastodon project page.

Key capabilities

Self-host with Docker Compose The repository ships a docker-compose.yml that pins the official ghcr.io/mastodon/mastodon image for the web and Sidekiq services and ghcr.io/mastodon/mastodon-streaming for the streaming server, alongside PostgreSQL 14 and Redis 7 containers. Elasticsearch is present but optional. Upgrades follow the release notes, which list the pre-deployment and post-deployment migration commands for Docker.
Install from source on Linux The official guide targets Ubuntu 24.04 or Debian 13 with root access, a domain and an SMTP service. It installs Node.js, PostgreSQL, Redis, Ruby through rbenv, Yarn, nginx and certbot, then runs the mastodon:setup wizard, which writes .env.production. Three systemd units, mastodon-web, mastodon-sidekiq and mastodon-streaming, keep the processes running.
Kubernetes and platform deployments A Helm chart is maintained in the separate mastodon/chart repository. The main repository also contains configuration for Heroku and Scalingo. These options still require an external PostgreSQL database, Redis and SMTP delivery.
ActivityPub federation Accounts follow, reply to, boost and quote accounts on other servers, including software other than Mastodon that implements ActivityPub. Since 4.7.0, the ActivityPub actor id is the primary identifier, so a remote account that changes its handle is renamed instead of duplicated. Mastodon users cannot change their own handle yet.
Signatures and key handling Version 4.7.0 encrypts local private keys at rest and moves them to a dedicated table designed for future key rotation. It adds outgoing RFC 9421 HTTP Message Signatures as a fallback to the older draft, Ed25519 signatures and verification of FEP-8b32 Object Integrity Proofs. The mldsa44-jcs-2024 proof type needs OpenSSL 3.5 or newer.
Posts, media and polls The default post limit is 500 characters, with links counted as 23 characters. A post can carry up to four images of 16 MB each, or one video or audio file of up to 99 MB. Since 4.6.0, a post can combine media and a poll, and media alt text can reach 10,000 characters.
Visibility levels and quote policies Each post is public, quiet public, followers-only or a private mention. Quiet public posts stay out of public feeds, explore and search. Followers-only posts can only be boosted by their author, and private mentions cannot be boosted. Since 4.5.0, authors also set who may quote a post. Past public posts cannot be made private retroactively.
Timelines, lists and filters Home updates arrive in real time and in chronological order through the streaming API. Users keep lists, follow hashtags and filter phrases, and since 4.6.0 can import and export custom filters and filter notifications from bots. The 5.0 beta adds server-side filtering to the home feed endpoint.
Collections and profiles Version 4.6.0 adds collections of up to 25 accounts that can be shared, based on FEP-7aa9 for interoperability. The profile screen was redesigned so users edit display name, bio, custom fields and featured hashtags directly. Display names can now be 40 characters long, and profile pictures and headers accept alt text.
Moderation and safety tools Users can lock accounts, mute, block, filter phrases and report posts. Moderators handle reports, appeals, warnings, domain blocks, IP blocks and email domain blocks in the admin area. Version 4.7.0 adds audit logs for hashtags, and 4.6.0 lets administrators require two-factor authentication for specific roles, including everybody.
Registration control Servers can be open, approval-based or invite-only. Since 4.6.0, inviting without review is a separate role permission, invite_bypass_approval. Optional captcha and single sign-on are documented on the admin pages.
Landing page and email subscriptions Version 4.6.0 adds an overview landing page for anonymous visitors that combines the about page with recent local posts. Administrators can also let selected roles offer email subscriptions, so visitors without an account receive a profile's posts by email.
REST and streaming APIs with OAuth 2 Mastodon acts as an OAuth 2 provider. The API documentation covers OAuth scopes and tokens, rate limits, entities, admin methods and the streaming endpoints. Version 4.6.0 adds GET and PATCH /api/v1/profile; the 5.0 beta deprecates POST /api/v1/accounts in favour of sign-up through the OAuth flow.
Official and third-party apps The project publishes official apps for iOS and Android and a progressive web app that can be added to a home screen. Desktop clients come from third-party developers; the apps page lists them by platform and by free, paid or open-source status.
Full-text search and translation Elasticsearch 7.x is recommended for full-text search, and OpenSearch should also work according to the release notes. Since 4.7.0, Elasticsearch queries time out after 10 seconds unless ES_QUERY_TIMEOUT overrides it. LibreTranslate 1.3.3 or newer is an optional translation backend.
Media storage options Uploaded media sits on the local filesystem by default. The object storage guide enables S3-compatible backends with S3_ENABLED, S3_BUCKET, S3_ENDPOINT and related variables, and an alias host or CDN can serve files. Version 4.6.0 dropped ImageMagick, so libvips 8.13 or newer is required.
tootctl administration CLI The tootctl command handles accounts, media cleanup, preview cards, email domain blocks and other maintenance tasks. Since 4.6.0, tootctl media remove --keep-interacted keeps cached media that local users interacted with during cleanup. The admin documentation also covers backups, migrating to a new machine and scaling.
Mastodon 5.0 beta The v5.0.0-beta.1 pre-release brings a new web layout, a pop-out composer and five color themes. It adds a Server Health admin page, bloom filters that limit where account deletion notices are sent and an experimental domain block and allow list synchronization. Once installed, the beta cannot be downgraded safely to the 4.x stable releases.

Where Mastodon fits

Running a community server

Choose a domain carefully before the first account is created, because handles include the server domain. Provision PostgreSQL, Redis, an SMTP provider and storage, then deploy with Docker Compose or the source guide. After mastodon:setup, create the owner account, write server rules and a privacy policy, and decide between open, approval and invite-only registration. Check that confirmation emails arrive and that the streaming server delivers new posts without a page reload.

Giving an organization a verified presence

Institutions, newsrooms and companies run their own server so that handles under their domain identify official accounts. A small server with registration closed and a few staff accounts keeps the moderation load low. Use email subscriptions or the overview landing page from 4.6 for readers without an account, and add verified profile links back to the organization website. Confirm that posts federate to large servers such as mastodon.social before announcing the accounts.

Moderating and federating responsibly

Assign moderator roles, require two-factor authentication for staff and set up report handling before opening registrations. Domain blocks can limit or suspend a remote server; the 5.0 beta adds an experimental way to synchronize block and allow lists. Read the moderation documentation and test how a domain suspension, a domain limit and a report forwarded to a remote server behave on your instance.

Building clients, bots and integrations

Register an application, request the narrowest OAuth scopes the integration needs and respect the documented rate limits. Bots should mark their accounts as automated so that users can filter bot notifications. For live updates, use the streaming API instead of polling timelines. Track the deprecation of POST /api/v1/accounts and the new OAuth sign-up flow announced with 5.0 when an app creates accounts.

Upgrading and maintaining an instance

Back up the database before every upgrade; the release notes give a pg_dump example for Docker. Read every skipped release note, because releases such as 4.6.0 and 4.7.0 change dependencies or contain long migrations. Run pre-deployment migrations with SKIP_POST_DEPLOYMENT_MIGRATIONS=true, restart processes, then run post-deployment migrations. Zero-downtime upgrades to 5.0 require being on 4.7 first. Watch the security advisories and apply patch releases such as 4.7.5 promptly.

Scaling a growing server

Move media to S3-compatible object storage with a CDN or alias host, add Elasticsearch or OpenSearch for search and split Sidekiq queues across processes as load rises. The scaling guide covers process counts, database connection pooling and read replicas. Monitor queue latency, PostgreSQL size and media cache growth, and schedule tootctl media remove to prune cached remote media.