Unofficial Snap for Mastodon (decentralized social media server)
- About
- Quickstart
- Installation
- Setup your instance
- Configuration
- Features
- Maintenance
- Troubleshooting
- Resources
Mastodon is a free, open-source social network server based on ActivityPub where users can follow friends and discover new ones. On Mastodon, users can publish anything they want: links, pictures, text, video. All Mastodon servers are interoperable as a federated network (users on one server can seamlessly communicate with users from another one, including non-Mastodon software that implements ActivityPub!)
The goal of this project is to simplify the setup of a Mastodon instance without requiring any prior knowledge of the technology behind it. This enables anyone to host their own fully functional (micro)instance with minimal future maintenance required. The all-in-one Snap package also offers support for ACME to automatically obtain SSL certificates for HTTPS.
Supported architectures:
- amd64
For more information, see the latest release readme or the FAQs.
Important
This is a community developed snap and is not officially supported or released by Mastodon GmbH.
If you're not running Ubuntu, start by installing the Snap daemon. Then run these commands:
sudo snap install mastodon-server
sudo mastodon-server.setup
🥳 Congratulations! You now have your very own Mastodon instance! 🎉
Tip
If you're looking for accounts to follow, check out the Mastodon Starter Packs Directory.
Important
An administrator account with a randomly generated password is created during setup. Some usernames such as admin and administrator are reserved by Mastodon. See the FAQs for a full list.
You can also install the Snap directly from the command line:
sudo snap install mastodon-server
If you don't want to use the Snap store, you can also download a Snap file from the releases page and install it using:
sudo snap install mastodon-server_VERSION_ARCH.snap --dangerous
Tip
In this context dangerous only means that the Snap file is not signed. This is normal for Snaps built and distributed outside the Snap store.
Note
A common criticism of Snaps is their dependence on Canonical. However, it is possible to install Snaps offline and also build them locally directly from source. See the build instructions for how to do this.
A Snap Store installation is automatically updated when new versions are released.
Note
Be aware that there will always be a short downtime due to the way Snaps are updated.
To update your local installation, you can simply repeat the steps above with a newer version of the Snap file. This will update your Mastodon instance in-place by creating a new Snap revision.
If you have installed a Snap file locally and still want to benefit from automatic updates, you can switch to the Snap Store installation using:
snap refresh --amend mastodon-server
After the Snap has updated itself, a new unpublished announcement will be created. You can view, publish or delete this announcement in Preferences/Administration/Announcements.
Note
By default, announcements.pre-refresh is enabled (see the configuration docs), which will display an update announcement 5 minutes before the Snap is updated. This will prolong the time the Snap is on hold during a refresh.
If you want to control the times at which Snaps are updated, you need to change the refresh.timer:
snap set system refresh.timer=03:00
You can check the current settings with:
snap refresh --time
If a snap update fails, you can always use the snap revert command to revert to an earlier revision.
Tip
Use the command snap revert mastodon-server --revision=<rev> to select a specific revision. Note that the revision is not the version number of the snap.
An initial setup command is required to initialize the database and configuration files for Mastodon:
sudo mastodon-server.setup
Note
Be patient if you have changed the status.length as it takes some time to recompile the assets, especially if there is a small amount of RAM available. Ideally these values should be changed before setup. Otherwise you may want to increase swap space.
Tip
If you're restoring your instance from a backup, use the mastodon-server.restore command directly. See the backups guide for more information.
SSL certificates can be obtained via ACME from either Let's Encrypt, ZeroSSL or BuyPass. This is done either during mastodon-server.setup or by using:
mastodon-server.get-certificate
Use the acme.server setting to select the CA (see the configuration docs).
Note
get-certificate will automatically enable HTTPS on port ports.https.
Important
HTTP is no longer supported in production. Mastodon will always serve https:// links.
See the certificates docs for advanced certificate topics.
Read the backups guide to learn how to export and restore your Mastodon server.
Coming from Twitter X and wanting a familiar look? Then the included Mastodon Bird UI theme might be for you. You can change the theme in Preferences/Appearance.
Important
If you have a severe visual impairment, an accessible version of the Bird UI theme is included by default with high contrast and an increased font size. This theme is indicated by the phrase Accessability++, which contains two plus signs and is translated into your selected language. In addition, this theme is marked with the ♿ emoji representing a person in a wheelchair as the International Symbol of Access.
Refer to the migration guide to migrate an existing account or instance to your mastodon-server Snap. The guide also contains instructions on how to migrate away from it, should you wish to do so.
You can tune services to fit your system by adapting the settings system.cpu, system.ram and system.ssd. On modern systems, the value of system.ssd can almost always be set to true and ignored.
By default, it is assumed that system.cpu=2 and system.ram=2 (GB). This does not necessarily mean that your server only has two CPU cores and two GB of RAM. Rather, this means that Mastodon will scale its services, such as PostgreSQL, Sidekiq and Nginx, to use roughly that amount of system resources. If your system is more powerful, or if mastodon-server is the only application running on your system, you can increase these values. See the configuration docs for an overview of these settings.
You can use the mastodon-server.tune command to tune the settings. This will also display a preview of the resulting service settings, which is of interest primarily to experts.
Tip
There is also the option to set system.cpu=auto and system.ram=auto, which will determine the maximum available resources for the Snap. This should usually correspond to the actual number of CPU cores and amount of RAM.
The command
mastodon-server.tootctl
replaces the sudo -u mastodon RAILS_ENV=production bin/tootctl command often found in guides and documentations.
See the configuration docs for a complete overview of the configuration variables and other commands.
The feature list provides an overview of some additional features that may enhance your user experience.
Read the maintenance guide to learn how to access the database shell and perform other maintenance tasks on your instance.
The mastodon-server.announce command can be used to create automated server notifications in Mastodon.
If you encounter a problem, check if it has already been solved in the troubleshooting guide. Otherwise, open a new issue on GitHub.
- Fedi.Tips is a valuable resource for Mastodon and the Fediverse.
- Fedi.Directory can help you find interesting accounts to follow.
- FediDB provides statistics on the Fediverse.
- FediBuzz Relay can be used to follow hashtags on other instances.
- Mastodon Starter Pack Directory provides community starter packs for Mastodon and the Fediverse.
- The People Directory helps you to find people across the Fediverse by topic.
- Academics on Mastodon contains a collection of various lists of academics on Mastodon.
- delightful activitypub development provides a curated list of software for the Fediverse.
- Mastodon - Simplified Federation! is a Firefox add-on that simplifies the process of following or interacting with users on other Mastodon instances.