Setting up a dev environment
Instructions on how to start developing for Mastodon.
For convenience, the Mastodon repository includes a Vagrantfile for quickly setting up a development environment without manual configuration. To use this development environment, install Vagrant using a binary executable or through your package manager.
Once you have Vagrant installed, for convenience, it is recommended to install a plugin to automatically update your machine’s hosts file. This will allow you to access the dev environment at
http://mastodon.local without manually editing the hosts file yourself. To do so:
vagrant plugin install vagrant-hostsupdater
The virtual machine can then be started:
Once the virtual machine has been started, you may launch the Foreman task executor to launch the various Mastodon processes:
vagrant ssh -c "cd /vagrant && foreman start"
Once the Mastodon processes have fully started up, you can load
http://mastodon.local in your browser to access the Mastodon instance within the VM. You can log in as the default admin user with the username
firstname.lastname@example.org and the password
Any changes to the source code will be reflected after saving your files.
To reset the VM to a fresh state, you can destroy it and bring it up again:
vagrant destroy vagrant up
You can follow the pre-requisites instructions from the production guide, but do not create a
mastodon user. You also don’t have to install
python-certbot-nginx as the development environment brings its own webserver. Setting up and running a development environment has been proven successful over WSL2 as well if you are on Windows.
Run the following commands in the project directory:
bundle install yarn install
In the development environment, Mastodon will use PostgreSQL as the currently signed-in Linux user using the
ident method. Ensure that you have created a Postgres user and database for your current signed-in user:
sudo -u postgres createuser $YOUR_USERNAME_HERE --createdb
You can now create the databases
mastodon_test, load the schema into them, and create seed data defined in
You can now launch
http://localhost:3000 in your browser and log in with the default admin user (
There are multiple processes that need to be run for the full set of Mastodon’s functionality, although they can be selectively omitted. To run all of them with just one command, you can install and use Foreman:
gem install foreman --no-document foreman start
This will start processes defined in
Procfile.dev, which will give you: A Rails server, a Webpack server, a streaming API server, and Sidekiq. Of course, you can run any of those things stand-alone depending on your needs.
In development mode, Mastodon will use a gem called Letter Opener for “sending” emails, which allows you to debug emails in your browser, without actually having to send emails via an SMTP server.
In order to work with emails, you’ll need Sidekiq, Redis and PostgreSQL running, and then emails can be viewed by visiting:
If you’re developing in docker, you’ll need to set the
REMOTE_DEV=true environment variable.
- Run the Ruby test suite
yarn run test
- Check the Ruby code for conformance with our code style
- Update Ruby gems and install any new dependencies
RAILS_ENV=development rails db:migrate
- Run new database migrations for your development instance’s database
Last updated November 25, 2023 · Improve this page