Improved running Shopsys Framework in Docker on MacOS using Mutagen

At the end of 2017, we started using Docker as the default installation method of Shopsys Framework. Docker installation came with many benefits like the same development environment for all developers or fast installation on new machines. On Windows and MacOS it was necessary to use docker-sync to overcome Docker performance issues. Sadly, docker-sync brought some issues on its own. The main problem is that with a bigger load of changes (e.g. during git checkout) it can happen that synchronization can stop altogether.

We were looking to overcome this issue and recently we updated our installation guide for Windows that is using WSL2 now and does not need docker-sync anymore. That left us with finding a better solution for developers with MacOS and hopefully we found some.

Recently we have started testing Mutagen as a replacement for docker-sync. Mutagen comes with almost identical performance as docker-sync, but from our testing, it seems to be much more stable. We want to test it more before adding it to Shopsys Framework directly, but we are pretty happy with the results so far. We want to share this small installation guide with you, so you can test it on your own. Any feedback would be greatly appreciated.

Installation guide (~10 minutes)

• install Mutagen in beta version

• brew install mutagen-io/mutagen/mutagen-beta (beta is only version with mutagen compose for now)
  • if error occurs saying something like “formulae is incorrect” run:
  • brew untap havoc-io/mutagen
  • brew install mutagen-beta
• copy docker-compose.yml to your project and update it appropriately
• run mutagen compose up -d
• then run docker-compose exec -u root php-fpm chown -R www-data:www-data /var/www/html
  • this is necessary to run every time after mutagen-compose up because of known bug with permissions in root folder

Note:
mutagen compose is just a wrapper above docker-compose that ensures that mutagen synchronization is started up before running docker-compose commands. Commands are all the same, you just replace docker-compose for mutagen compose like mutagen compose exec php-fpm bash.

Debugging with Mutagen

Another strong benefit of having running on Mutagen is that Mutagen comes with few ways to debug, if some problem occurs:

• mutagen sync list shows list of currently running synchronization and displays potential problems that might occur
• mutagen sync monitor displays in real-time what Mutagen does and in case of problem displays Error or Problem. In such a case you have to run mutagen sync list command to get detailed information about the problem.