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
- 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
- Install Ruby and Ruby-dev
sudo apt-get install ruby ruby-dev
- Install docker-sync
Install the gem
sudo gem install docker-sync
- 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
- Compile and install OCaml
Before doing this please check out first the ghcr.io/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
- 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
- Set Timezone if not done already
Check if /etc/localtime is a symlink. If not run dpkg-reconfigure tzdata and set your correct timezone.
- (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"
- 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.