Mastodon is an open source social networking application that utilizes the ActivityPub specification and federation to allow multiple independent servers to interact with each other, create one (or a few) big social networks without a centralized, controlling authority. While Mastodon isn’t new the recent upheaval at Twitter has caused a huge spike in interest in building an alternative to Twitter. But this post isn’t about all the nitty gritty details of why folks are using Mastodon but rather on how to setup an instance of Mastodon (for development purposes) using Visual Studio Code (VSC) and Dev Containers.
There are other ways to setup Mastodon for development, the preferred way according to the documentation appears to be Vagrant. I like Vagrant and have used it in the past but noticed that there was a .devcontainer folder in the repository indicating someone had setup VSC to work with Dev Containers and decided to go this route for a few reasons:
- I’m running Windows with Windows Subsystem for Linux (WSL) and Docker. Vagrant uses Virtualbox and WSL/Docker don’t seamlessly work together. I don’t believe it’s impossible to get them to work together, in fact I think I have on occasion…but it can be a lot of work.
- Running a VM is heavier than running Docker containers.
- Visual Studio Code makes it so easy to setup a dev environment using Dev Containers it’s just a superior experience compared to almost anything else out there (GitHub Codespaces is pretty slick too, but I believe that also uses Dev Containers under the hood).
Let Me Know
If you find this guide helpful, let me know. It’s a bit rough currently b/c I don’t want to invest a ton of time into something if it isn’t going to be utilized. But if it is proving helpful to others (e.g. other people actually want to use VSC Dev Containers to run Mastodon) I can spruce things up, maybe add some screen captures, etc. 🙂
Getting the Software
If you don’t already have it, you’ll need to download and install Visual Studio Code, Docker, and the Microsoft Dev Containers extension for VSC. If you are running Windows you’ll also need to install/enable WSL2. The easiest way to do this is actually by installing WSL through the Microsoft Store. I know, I know, I’m not the hugest on the Microsoft Store either, but in this case WSL2 is basically a part of Windows and the Store is the delivery mechanism. Doing so allows you to easily access WSLg (on Windows 10 and 11) but that’s a story for another day.
If using WSL you’ll also need to install a distribution of Linux into WSL. I recommend Ubuntu. For those on macOS or Linux all the instructions relating to WSL don’t apply.
Getting Mastodon
Windows Users: STOP! You may be tempted to put the Mastodon repository on a Windows drive. Don’t do it! Clone the repo into your WSL instance. Microsoft recommends doing this but understates the difference in performance one will experience. Imho, it is orders of magnitude faster to run from within WSL than to run from a Windows drive.
Whichever OS you are using, you’ll clone Mastodon into a folder on your local system. e.g., git clone https://github.com/mastodon/mastodon.git.
I usually fork the repository into my own account so that I can make changes and push them back to my own repo and, if appropriate, create pull requests (PRs) with the original repo, but I won’t cover that here.
Setting Up Mastodon in VSC with Dev Containers
The next step is to open the Mastodon repo in Visual Studio Code. This is seamless for those on macOS/Linux, for those on Windows you’ll want to navigate in your terminal to the repo directory and type, code .. This will launch an instance of VSC using that directory as it’s workspace. This makes editing fairly seamless.
Once open, if you’ve installed the Dev Containers extension, you should be prompted to reopen the workspace using Dev Containers. You should say yes. VSC will then follow the instructions in the .devcontainers folder to create the necessary Docker containers to run Mastodon.
The startup process may take a few minutes. VSC will likely offer to open in the browser the server ports that are spun up by Mastodon – e.g., localhost:3000 and localhost:4000 – but these won’t load Mastodon for you.
Getting Mastodon Really Loaded
In order to get to the UI of Mastodon, you’ll want to run within VSC’s Dev Container Terminal the following command: foreman start. Give it a minute and you should be able to access localhost:3000 with a full Mastodon instance. Tada!
Weird GitHub Error
You may run into an error when VSC is initially spinning up the Dev Container regarding some uncertainty about the ownership of the repo files. See the PR I’ve submitted to the main Mastodon repo for the small update you need to make to devcontainer.json to get past this.
Essentially, you need to change the line:
"postCreateCommand": "bundle install --path vendor/bundle && yarn install && git checkout -- Gemfile.lock && ./bin/rails db:setup",
To:
"postCreateCommand": "git config --global --add safe.directory /workspaces/mastodon && bundle install --path vendor/bundle && yarn install && git checkout -- Gemfile.lock && ./bin/rails db:setup",