About Tokaido

Tokaido Sync Services

Getting content from your local system into the Tokaido Docker environment and vice-versa is a much more difficult process than it should be. When designing a tool like Tokaido, there are many issues that we need to contend with:

• On Linux, Docker runs natively and the owner id of files in your Drupal project probably won't be the same as the owner inside Tokaido. This means that files changed on one side can't be easily seen or edited on the other side.
• On Mac, Docker runs in a HyperKit Virtual Machine. The owner id problems don't exist in this platform, but the trade-off is that Docker for Mac suffers from problems relating to virtual filesystem performance that are well known and documented.

To work around these trade-offs, Tokaido bundles in two different options for synchronisation on Mac, and a single option on Linux.

Unison

For about the first year of its existence, Tokaido provided sync between the local machine and Tokaido environment using a Unix program called unison . If you're familiar with rsync , then you can think of Unison as a bi-directional rsync

Unison provides near-native disk performance by copying file changes over the local network between your system and the Docker/Tokaido environment.

While incredibly fast, in practice some Tokaido users experienced reliability issues with Unison. For example, Unison has a tendency to get a little too intimate with the CPU, to the point where Docker becomes unresponsive and needs to be restarted.

Unison also has the drawback of duplicating every copy of every file in your project. On very large projects, or systems with a large number of projects, this can lead you to exhaust the disk space in your Docker installation.

While these issues aren't common, we did move towards using Docker Volume mounts on MacOS to help uses enjoy greater stability, at the trade off of a little stability.

MacOS users can revert to using Unison on their system by setting syncservice: unison in their ~/.tok/global.yml file.

Docker Volume Mounts

The 'docker' Sync Strategy mounts local paths as Docker Volumes directly. It is only available on macOS and is the default option.

Because of the earlier mentioned Docker Volume performance issues, disk operations on Docker Volumes tend to be about 3-5x slower than on local systems. A composer install that takes 1 minute with Unison will take about 4 minutes with Docker Volumes.

While this performance drop is unfortunate, you really only notice it when doing disk-heavy operations like composer install

On the other hand, Docker Volumes are incredibly reliable and so far we've had no complaints about Docker Volumes not working, whereas we have had several of these with Unison. As such, Docker Volumes are our default and recommended choice on macOS.

Docker Volumes aren't possible on Linux because of the owner and group settings being inconsistent between the Tokaido containers and your host system.