Skip to content

Instantly share code, notes, and snippets.

Last active February 1, 2023 04:38
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
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


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