Setting up a dev environment
Instructions on how to start developing for Mastodon.
Quick start with Vagrant
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:
vagrant up
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 admin@mastodon.local
and the password mastodonadmin
.
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
Manual install from source
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 nginx
, certbot
and 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.
Setup
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_development
and mastodon_test
, load the schema into them, and create seed data defined in db/seeds/
into mastodon_development
.
rails db:setup
You can now launch http://localhost:3000
in your browser and log in with the default admin user (admin@localhost:3000
/ mastodonadmin
).
Running
There are multiple processes that need to be run for the full set of Mastodon鈥檚 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.
Useful commands for testing
rspec
- Run the Ruby test suite
yarn run test
- Run the JavaScript test suite
rubocop
- Check the Ruby code for conformance with our code style
Updating your development instance
bundle install
- Update Ruby gems and install any new dependencies
yarn install
- Update Javascript packages and install any new dependencies
RAILS_ENV=development rails db:migrate
- Run new database migrations for your development instance’s database
Last updated November 20, 2022 路 Improve this page