Skip to content

Instantly share code, notes, and snippets.

Last active February 1, 2023 04:38
Show Gist options
  • Save claudioc/5b245d15677f27db36d07fc089ad0945 to your computer and use it in GitHub Desktop.
Save claudioc/5b245d15677f27db36d07fc089ad0945 to your computer and use it in GitHub Desktop.
How to run Mastodon for development on an Apple M1 Pro device

How to run Mastodon on a (early 2022) MacBookPro M1 Pro

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 gem and yarn were 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 mastodon user 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 && cd mastodon; this of course checks the main branch 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 rails is not found, use ./bin/rails; the command for the database setup is then RAILS_ENV=development ./bin/rails db:setup
  • Install foreman with gem install foreman --no-document; from this point on you don't need the official guide anymore
  • I added an entry in my macOS /etc/hosts to resolve mastodon.local with 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= 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.development file here but I am not sure how. If you know, please add a comment
  • I had webpack complaining about a problem with digital envelope but 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!

Copy link

Thanks for the howto! Looking into Multipass right now:

Copy link

As an alternative UTM can also be used:

Copy link

@nodomain I didn't know about Multipass, but sharing the linux volume with my real disk is not ideal for me (I want to have everything well separated).

But I also totally forgot about utm! I will check that out today, thanks!

Copy link


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment