This post is part 2 of a 3-part series on adding the ability to show notes about users on Mastodon next to their display names. Here, I talk a bit about setting up a dev environment to make changes to the Mastodon UI.

Parts of this series:

• Part 1: Adding a field to the Mastodon API
• Part 2: Setting up the UI dev environment
• Part 3: Surfacing a new field in the Mastodon UI

When you modify the Ruby files making up the Mastodon server, those changes immediately impact the running server and no further manual intervention is needed for testing. To complete Part 1, I actually changed and tested on my production server; not best practice, but it worked.

The UI is trickier. Mastodon’s web UI is written in TypeScript and compiled (and “packed”) into JavaScript for client consumption. That requires infrastructure and would prove to be much harder to test live on my production server running on a Raspberry Pi (my Pi doesn’t even have the firepoewr to build the whole UI without clearing some memory and CPU capacity by bringing the server and its helper services down). To make actual UI changes, I need to be a bit more disciplined and set up a dev environment on my laptop.

The Mastodon project provides documentation on how to do local development; this post is a supplement to that information based on my experiences.

Tips on using Vagrant (don’t!)

According to the developer documentation, “For convenience, the Mastodon repository includes a Vagrantfile for quickly setting up a development environment without manual configuration.”

Here’s a sampling of the steps that were necessary to take advantage of this convenience on my Lenovo Thinkpad running Ubuntu:

• Resolving unable to resolve dependency: user requested 'vagrant-hostupdater (> 0)
  • It’s called vagrant-hostsupdater. Oops.
• Debug It appears your machine doesn't support NFS
  • Here’s a guide to setting up NFS on Ubuntu
• Out of disk. Vagrant wraps a full virtualization solution, so you need enough space to copy down an entire disk image and store the virtual machine’s storage image
  • Bought a new hard drive (for the laptop, so less mobile computing for me)
• Fixing “debug IP range disallowed”
  • Easiest thing to do was (as documented here change the configs in /etc/vbox/networks.conf to allow the Vagrantfile’s hard-coded IP range to work.
• Fixing VT-x is disabled in the BIOS for all CPU modes
  • Like it says: virtualization is disabled by default. Reboot, go into the BIOS settings, and switch it on.
• Requested NFS version or transport protocol is not supported
  • Around lines 164-168 in the Vagrantfile, comment out and replace with config.vm.synced_folder ".", "/vagrant"

… after all that was done, I finally got the dev env running and… It didn’t appear to see changes to the UI, nor could I see how to convince it to rebuild them. Well… Crap.

So I jettisoned that whole process and I don’t recommend the Vagrant configuration for web UI development. Not if you can avoid it.

Using Foreman but configuring correctly for development

The other path recommended by the development documentation is Manual install from source. This I found more fruitful, with one stumbling block: this documentation recommends “You can follow the pre-requisites instructions from the production guide, but do not create a mastodon user.” Follow that carefully: it’s telling us to do specifically the Prerequisites part and no other parts. If you go too far, you’ll start setting up a production environment and you do not want that.

In addition, the documentation is a bit stale; it’ll tell you to install Ruby version 3.0.6, but (as of this writing) the .ruby-version file indicates 3.2.2 is the current version.

For everything you do while developing Mastodon, you should use RAILS_ENV=development. That may seem like common sense, but I’ve used Rails apps that didn’t have a working / maintained development config. Mastodon isn’t one of them, and in fact you’ll find there are pieces missing (like the TypeScript build infrastructure) if you don’t use the development environment.

Once you’re set up, I recommend using foreman as the development guide describes. It was the easiest way to launch all the requisite components and use them. Most importantly, the foreman configuration will do a watch-and-rebuild on the TypeScript files, so you can edit the UI to your heart’s content without having to force a compile or down-up the server!

Creating test users

While the dev environment does shim in a solution for “sending email” when there’s no email server, I found the easiest thing to do for testing was just add users with the CLI database management tools.

You can use tootctl to create a new test account:

tootctl accounts create --skip-sign-in-token --confirmed fred --email something@yourdomain.com

Pay attention to the output scroll; it’ll include a default password string. And write down the email address you provided, as that’s the login name.

Now that I have a dev environment set up, I’m ready to close the loop and use the data I surfaced in Part 1.