First, install the latest versions of Vagrant and VirtualBox for your operating system.
vagrant plugin install vagrant-hostsupdater
To create and provision a new virtual machine for Mastodon development run:
git clone https://github.com/tootsuite/mastodon.git cd mastodon vagrant up --provider virtualbox
Note: On Linux hosts, you will need to enable NFS support.
vagrant up --provider virtualbox for the first time will run provisioning, which will:
- Download the Ubuntu 16.04 base image, if there isn't already a copy on your machine
- Create a new VirtualBox virtual machine from that image
- Run the provisioning script (located inside the Vagrantfile), which installs the system packages, Ruby gems, and JS modules required for Mastodon
Starting the server
The Vagrant box will automatically start after provisioning. It can be started in future with
vagrant up --provider virtualbox from the mastodon directory.
To start the application:
vagrant ssh -c "cd /vagrant && foreman start"
The rails server, streaming server and webpack-dev-server will start up. You can then access your development site at http://mastodon.local (or at http://localhost:3000 if you haven't installed vagrants-hostupdater). By default, your development environment will have an admin account created for you to use - the email address will be
firstname.lastname@example.org and the password will be
To stop the server, simply run
Using the server
You should now have a working Mastodon instance, although it will not federate, as it is not publicly accessible. Should you need temporary federation for development and testing, see the Ngrok information in the Development Guide.
By default, your instance's ActionMailer will use "Letter Opener Web" for email. This means that any email that would normally be sent, will instead be stored, and accessible at http://mastodon.dev/letter_opener - you can use this to verify a registered user account.
You are able to set environment variables, which are used for Mastodon configuration, by editing the
.env.vagrant is loaded when you run
Vagrant has mounted your mastodon folder inside the virtual machine. This means that any change to the files in the folder(e.g. the Rails controllers or the React components in /app) should immediately take effect on the live server. This allows you to make and test changes, and create new commits, without ever needing to access the virtual machine.
Should you need to access the virtual machine (for example, to manually restart the Rails process without restarting the box), run
vagrant ssh from the mastodon folder. You will now be logged in as the
vagrant user on the VirtualBox Ubuntu VM. You will want to
cd /vagrant to see the app folder.
You can find the Rails server logs in in the
log folder, which will often have the information you need.
If your Mastodon instance or Vagrant box are really not behaving, you can re-run the provisioning process. Stop the box with
vagrant halt, and then run
vagrant destroy - this will delete the virtual machine. You may then run
vagrant up to create a new box, and re-run provisioning.
To run the
rspec tests and
rubocop style checker, you may either:
- Install the relevant gems locally, or
- SSH into the virtual machine,
cd /vagrant, and then run the commands
If you are confused, or having any issues with the above, the Mastodon IRC channel ( irc.freenode.net #mastodon ) is a good place to find assistance.