wctaiwan

Nov 12, 2021

Setting up a MediaWiki development environment on M1 Macs using Multipass

Over the past week, I spent some time figuring out how to set up a MediaWiki development environment on my laptop. Here were some things I learned:

  1. MediaWiki-Docker (using the included docker-compose.yaml) doesn't work, as the images specified in docker-compose.yaml are built for x86, not ARM.
  2. Podman works surprisingly well on macOS (installed from Homebrew, and using the built-in podman machine). I was even able to get docker-compose to work by following the instructions in this HN comment, but ultimately there were two blockers:
    1. The issue with image architectures above
    2. Bind mounts are unsupported as of the time of writing, which prevents using a checkout of MediawWiki on the host in the VM/container

In the end, I ended up using Multipass, which provides a quick way to spin up a headless Ubuntu VM across multiple platforms. Unlike with Podman, bind mounts are supported, and so I was able to clone MediaWiki on the host and map the checkout into the VM, which makes it much easier to develop on the host, and use the VM purely as a web server.

One thing to note with this process is that I ran into errors caused by file permission issues when I tried to run Composer from inside the VM to install dependencies, likely due to the interaction between sshfs and file ownership on the host and in the VM (since this would be run from inside the bind mount). The workaround was to install PHP (using Homebrew) on the host system, and manage dependencies from the host as well.

Below are the high-level steps I took:

  1. Install Multipass using brew install --cask multipass.
  2. Create an Ubuntu VM using multipass launch.
  3. Use multipass shell to open an SSH session into the VM, and install Apache, PHP, MariaDB, php-fpm and php-mysql using apt. Note that you might also need to manually install some of the PHP extensions listed here when prompted by the install script later.
  4. Run sudo mysql_secure_installation inside the VM to configure MariaDB, and set up a database and user for MediaWiki.
  5. Sanity check that the web server works at this point: Run multipass ls and go to the IP of the VM in a web browser. It should show the default page for Apache.
  6. Install PHP on the host using brew install php.
  7. Clone MediaWiki on the host by following the instructions here.
  8. On the host, run Composer inside the MediaWiki checkout by following the instructions here.
  9. Mount the MediaWiki checkout in the VM at /var/www/html/w using multipass mount.
  10. Navigate to http://<VM_IP>/w/ and follow the instructions.

With this setup, the bind mount essentially allows Apache in the VM to use the MediaWiki checkout, but all of the actual development would take place on the host.