Installation

No matter if its OSX/Linux/Windows

gem install docker-sync

Depending on the OS, you might need more steps to setup. Continue reading below.

Installation as non-root

You may elect to install docker-sync as a non-root user. To install as the current user:

gem install --user-install docker-sync

Then set-up your shell to add the docker-sync command to the PATH. Edit .bashrc:

if which ruby >/dev/null && which gem >/dev/null; then
  PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin:$PATH"
fi

… then start a new shell and run docker-sync.


OSX

Dependencies

Docker4Mac If you use Docker4Mac, you can use the native_osx synching strategy and don’t have any host dependencies.

docker-machine If you’re using docker-machine, you need to pick one of the other sync strategies, because the native_osx strategy doesn’t work on docker-machine.

Advanced / optional

Optionally, if you do not want to use unison or want a better rsync or use unison (than the built-in OS X one)

if you use unison

brew install unison
brew install eugenmayer/dockersync/unox

if you use rsync

brew install rsync

Homebrew aka brew is a tool you need under OSX to install / easy compile other tools. You can use other tools/ways to install or compile fswatch, but those are out of scope for this docs. All we need is the binary in PATH.

Caution

Starting with docker-sync 0.7.0 if you’re using unison strategy, you can also install [an alternative](https://github.com/autozimu/unison-fsmonitor) to unox. It seems to be faster and more performant but it has not been fully battle-tested yet.


Linux

Caution

Linux support is still to be considered BETA - do not get too crazy if we have bugs!

Dependencies

Default sync strategy for linux (native) do not need any host dependencies.

Advanced / optional

Optionally, if you want to use unison, then you would need to install some more stuff.

The following instructions are written for Ubuntu; if you’re using another linux flavor, you might need to adjust some stuff like using a different package manager.

Using Unison Strategy

The Ubuntu package for unison doesn’t come with unison-fsmonitor, as such, we would need to build from source.

sudo apt-get install build-essential ocaml
wget https://github.com/bcpierce00/unison/archive/v2.51.3.tar.gz
tar xvf v2.51.3.tar.gz
cd unison-2.51.3
make UISTYLE=text
sudo cp src/unison /usr/local/bin/unison
sudo cp src/unison-fsmonitor /usr/local/bin/unison-fsmonitor

and that should be enough to get you up and running using unison.

Using rsync strategy

rsync strategy is not currently supported under linux, but it can be done. If you need this, please see #386, and send us some help.


Windows

Caution

Windows support is still to be considered BETA, - do not get too crazy if there are some bugs!

This guide provides detailed instructions on getting docker-sync running on Windows Subsystem for Linux.

As the time goes by these instructions may not be updated, so please also check out the repo’s issues if you have any ‘unknown’ problem that is not treated in this guide.

Still the procedure is pretty straightforward and should help set you up and running without too much hassle.

Benefits of Docker-sync on Windows

  • Inotify works on containers that support it. No more polling!
  • Performance might be a bit better or right on par with native Windows volumes. This needs more testing.

Possible Future Supported Environments

  • Cygwin
  • Native Windows (no posix)

My Setup (for reference)

Windows 10 Pro 1709

Pro version required for using Docker for Windows (Hyper-V), also update your system to the latest available version from MS

Docker for Windows CE 18.03.0-ce-rc3-win56 (16433) edge

(stable version should also work fine)

Let’s go!

1. Enable WSL Open the Windows Control Panel, Programs and Features, click on the left on Turn Windows features on or off and check Windows Subsystem for Linux near the bottom.

2. Install a distro Open the Microsoft Store and search for ‘linux’.

You will be then able to choose and install Debian, SUSE, openSUSE, Ubuntu, etc..

In this guide I am using Debian GNU/Linux. Direct link for Debian GNU/Linux

3. Launch and update The distro you choose is now an ‘app’ on your system.

Open the start menu and launch it, then follow the on screen instructions in order to complete the installation.

When you have a fully working shell, update the system.

sudo apt update

sudo apt upgrade

4. Install Docker Follow the official documentation for installing Docker on Linux: (the following is for Debian)

https://docs.docker.com/install/linux/docker-ce/debian/#install-docker-ce

Note that the Docker Server doesn’t work on the subsystem - we will then expose Docker for Windows to WSL later

with Windows 10 >= 1803 you can place a symlink to the Windows binary

sudo ln -s "/mnt/c/Program Files/Docker/Docker/resources/bin/docker.exe" /usr/local/bin/docker
  1. Install Docker Compose
sudo apt install docker-compose

Or if that does not work, follow the official documentation: https://docs.docker.com/compose/install/

with Windows 10 >= 1803 you can place a symlink to the Windows binary

sudo ln -s "/mnt/c/Program Files/Docker/Docker/resources/bin/docker-compose.exe" /usr/local/bin/docker-compose
  1. Install Ruby and Ruby-dev
sudo apt-get install ruby ruby-dev
  1. Install docker-sync

Install the gem

sudo gem install docker-sync
  1. Set your Docker for Windows host as an ENV variable

Open the Docker for Windows settings and check Expose daemon on tcp://localhost:2375 without TLS

Then type the following command in your WSL shell.

echo "export DOCKER_HOST=tcp://127.0.0.1:2375" >> ~/.bashrc
  1. Compile and install OCaml

Before doing this please check out first the eugenmayer/unison dockerfile and ensure that the OCaml version that you are going to install is the same. To find the required OCaml version, do a search for “ocaml” within the eugenmayer/unison’s dockerfile (https://github.com/EugenMayer/docker-image-unison/blob/master/Dockerfile)

Install build script

sudo apt-get install build-essential

As for now the procedure is as follows:

sudo apt-get install make
wget https://caml.inria.fr/pub/distrib/ocaml-4.12/ocaml-4.12.0.tar.gz
tar xvf ocaml-4.12.0.tar.gz
cd ocaml-4.12.0
./configure
make world
make opt
umask 022
sudo make install
sudo make clean
  1. Compile and install Unison

Look up the latest Unison release (https://github.com/bcpierce00/unison/releases), download the source code, compile and install.

As for now the procedure is as follows:

wget https://github.com/bcpierce00/unison/archive/v2.51.3.tar.gz
tar xvf v2.51.3.tar.gz
cd unison-2.51.3
# needed for < Unison 2.51.4_rc2 with OCAML 4.12 - see https://github.com/bcpierce00/unison/pull/480
# and https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/unison.rb#L13
curl https://github.com/bcpierce00/unison/commit/14b885316e0a4b41cb80fe3daef7950f88be5c8f.patch?full_index=1 -o patch.diff
git apply patch.diff
make UISTYLE=text
sudo cp src/unison /usr/local/bin/unison
sudo cp src/unison-fsmonitor /usr/local/bin/unison-fsmonitor
  1. Set Timezone if not done already

Check if /etc/localtime is a symlink. If not run dpkg-reconfigure tzdata and set your correct timezone.

  1. (bonus!) Bind custom mount points to fix Docker for Windows and WSL differences (thanks to @nickjanetakis)

You might encounter various strange problems with volumes while starting up Docker containers from WSL.

If so, as a workaround you have to set up a special mountpoint inside /etc/fstab and start your container from there.

sudo mkdir /c
sudo mount --bind /mnt/c /c
echo "sudo mount --bind /mnt/c /c" >> ~/.bashrc && source ~/.bashrc

In order to automatically mount the volume without asking any password you can add a rule into your sudoers file.

sudo visudo

Add the following at the bottom of the file, replacing “username” with your WSL username.

username ALL=(root) NOPASSWD: /bin/mount

with Windows 10 >= 1803 you can place a new file to /etc/wsl.conf instead

[automount]
root = /
options = "metadata"
  1. Laradock? No problem!

If, as an example, you are using Laradock, you just need to follow the official documentation changing the sync strategy to ‘unison’ and adding the docker-compose.sync.yml in your .env file.

...
COMPOSE_PATH_SEPARATOR=;
COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml:docker-compose.sync.yml
...
DOCKER_SYNC_STRATEGY=unison

Then you need to add the following ‘sync_args’ line in the laradock/docker-sync.yml file, as follows:

...
sync_strategy: '${DOCKER_SYNC_STRATEGY}' # for osx use 'native_osx', for windows use 'unison'

sync_args: ['-perms=0'] #required for two way sync ie generators, etc
...

This will allow proper synchronization between the Linux containers and your Windows host that manages permissions in a different way.

Now you can start syncing using sync.sh provided with Laradock.

./sync.sh up nginx mysql phpmyadmin

Done!

You should now have a working version of docker-sync via the Unison strategy.

In your home directory in WSL you can link your projects from Windows and run docker-sync or docker-sync-stack.

The rest of your workflow should be the same as before in either Command Prompt, PowerShell, or some other Windows terminal.

FYI - An example of a docker-sync.yml file

version: "2"
options:
    verbose: true
syncs:
    app-unison-sync: # tip: add -sync and you keep consistent names als a convention
        sync_args: ['-perms=0'] #required for two way sync ie generators, etc
        sync_strategy: 'unison'
        sync_host_ip: '127.0.0.1' #host ip isn't properly inferred
        sync_excludes: ['.gitignore', '.idea/*','.git/*', '*.coffee', '*.scss', '*.sass','*.log']
        src: './'

FreeBSD

Dependencies

Default sync strategy for FreeBSD is rsync, you need to install it first:

# pkg install rsync

Using rsync

To setup an rsync resource you need a docker-sync.yml similar to:

version: "2"

syncs:
  code-sync:
    sync_strategy: "rsync"
    src: "path/to/src"
    sync_host_port: 10871
    # sync_host_allow: "..."

sync_host_port is mandatory and it must be unique for this shared resource.

You might need to specify sync_host_allow, this will let the rsync daemon know from which IP to expect connections from, network format (10.0.0.0/8) or an specific IP (10.2.2.2) is supported. The value depends on your virtualization solution and network stack defined (NAT vs host-only). A quick way to determine the value is to run docker-sync start and let it fail, the error will show you the needed IP value.

Using unison

unison could be supported on FreeBSD, but it wasn’t tested yet.

Using native_osx

This strategy is not supported, its OSX only.