Last updated on late November 2022.
First and foremost: do not waste your time with Vagrant (VirtualBox is not ready yet) or docker-compose (which runs a production environment)
My goal here is to run a Mastodon instance on a laptop, but using a virtual machine of some sort, so to not install a lot of dependencies on the real one. I have found out that the best solution is to use a virtual machine running (Ubuntu) Linux and follow the manual installation instructions from the official guide. The official guide assumes that you will be running the dev environment within a Linux box, but I have found that to be able to run Mastodon inside a virtual machine, several small tweaks are necessary, hence this guide.
My hardware configuration: MBP M1 Pro with 16GB
- Install VMWare Fusion Pro; I have installed the (30 days) Trial version instead of the Player - which you can get for free - because for some reason the account registration in VMWare doesn't work
- Note: with the M1 Pro you can only run ARM versions of Linux; if for some reason you want to still run an (emulated) Intel version, you need QEMU
- Install and run Linux inside VMWare; I used the Ubuntu Server 22.10 ARM iso. You definitely don't need the GUI
- Change the network configuration of your virtual machine; it should use the Bridged Networking in Autodetect; this way the virtual machine will be part of the same LAN of your laptop, sharing the same netmask
- Now that your machine is up, connect to it in ssh from a macOS terminal; I have found this way more friendly than using the linux terminal inside the virtual machine, because copy/paste works better and the mouse is not trapped
- Disable IPv6 (I used this guide); this sounds lame, but for some reason
gemandyarnwere not able to connect via IPv4 unless IPv6 was disabled - Now follow the steps in the official "production" guide until the "Setup" paragraph (excluded) and DO NOT create a
mastodonuser and do not setup the database; the additional user is not needed in development and the db will be setup later - Clone the code repository
git clone https://github.com/mastodon/mastodon.git && cd mastodon; this of course checks themainbranch out and moves you into its directory - Now you need to move your attention to the official manual installation guide;
- Follow the steps in its "Setup" paragraph; if
railsis not found, use./bin/rails; the command for the database setup is thenRAILS_ENV=development ./bin/rails db:setup - Install
foremanwithgem install foreman --no-document; from this point on you don't need the official guide anymore - I added an entry in my macOS
/etc/hoststo resolvemastodon.localwith the IP address of the virtual machine - You should now be ready to run the whole thing with
STREAMING_API_BASE_URL=/ LOCAL_DOMAIN=mastodon.local WEB_DOMAIN=mastodon.local:3000 RAILS_ENV=development BIND=0.0.0.0 foreman start; the BIND env variable is to tell rails to listen to all the network interfaces and not only localhost- Note: there should be a way to use a
.env.developmentfile here but I am not sure how. If you know, please add a comment
- Note: there should be a way to use a
- I had webpack complaining about a problem with
digital envelopebut this is probably because I installed node 18 instead of the suggested node 16. If this is your case too, you just need to add another env variable to the foreman line:NODE_OPTIONS=--openssl-legacy-provider - You can ignore websocket errors on port :3035, since those are (probably) related to the HMR Webpack support, which is disabled by default (see
webpacker.yml)
Now you should be able to reach http://mastodon.local:3000 from a browser in macOS! As specified in the guide, the default user is admin@localhost:3000 / mastodonadmin. Keep in mind that https is not supported with this installation.
Happy hacking!
As an alternative UTM can also be used: https://mac.getutm.app