Mutagen

To speed up filesystem performance on MacOS you can use a two-way-sync tool called Mutagen

It runs in the background and keeps syncing your files onto a volume inside your docker containers. It's pretty performant and the delay is minimal even if you change a lot of files at once.

To make use of mutagen on Mac OS you have two options:

1. Standalone installation in conjunction with Rancher Desktop (recommended)
2. Use Docker Desktop with Synchronized File Share (uses mutagen under the hood, Docker Desktop needs a licence)

Performance tip: The more files mutagen has to watch and keep it sync the longer it takes to sync the changes to the Docker containers. By limiting the number of sites to one or max two you'll keep this in check. Switching between different branches on one checkout rather than having mulitple sites up for different branches seems to be the better choice.

Standalone (classic)

This is the recommended method if you use Rancher Desktop or have an older Docker Desktop version (without Synchronized file share support).

This method installs mutagen as a service (daemon) and uses our own implementation of what the extension offers.

For mutagen to fully work together with Rancher Desktop make sure you create a symlink to the docker executable (try with sudo if you get a permission error):

ln -s ~/.rd/bin/docker /usr/local/bin/docker

To install either use homebrew (see below), or alternatively download the appropriate release file.

brew install havoc-io/mutagen/mutagen

Make sure you have at least version 0.10.0 runnning.

To have mutagen automatically start up with your machine

mutagen daemon register

Then start the daemon. This is a background process without the sync does not work. If you have registered the daemon with the command above you won't need to do this every time.

mutagen daemon start

To activate the use of mutagen, your .env file, set the USE_MUTAGEN variable to:

USE_MUTAGEN=1

If you then use the commands tup and tdown (see the Usage page), then the correct sync session is automatically created for you.

Monitoring

To find out if your sync is working you can use the following command:

mutagen sync list

which shows something like:

⇒  mutagen sync list
--------------------------------------------------------------------------------
Name: totara
Identifier: ddc06807-2554-47f4-ba8a-230f37c5e577
Labels: None
Alpha:
	URL: /your/local/path/to/totara/src
	Connection state: Connected
Beta:
	URL: docker://totara_sync/var/www/totara/src
		DOCKER_HOST=
		DOCKER_TLS_VERIFY=
		DOCKER_CERT_PATH=
	Connection state: Connected
Status: Watching for changes
--------------------------------------------------------------------------------

You can use the session id or any part of the paths to monitor the session, for example:

mutagen sync monitor totara

Docker Desktop extension

If you are using Docker Desktop then we recommend to use a Synchronized file share (powered by Mutagen).

Instructions:

1. Set up the docker dev as usual (using the regular mounts)
2. Set up a synchronized file share (choose same folder as LOCAL_SRC of your .env file)
3. Wait until the file share is fully setup
4. Start the docker containers with tup as usual
5. The file share should now be in use

Troubleshooting

I change a file, but I'm not seeing the changes applied on the site

Mutagen may be stuck on a conflict. Try running mutagen sync list -l and see if it lists anything under a "Conflicts:" heading. If there are conflicts, you need to delete the file inside the container so mutagen can resume syncing it.