Moving over to docker-sync for Mac support.

Unison is written in OCaml. OCaml 4.02 changed the serialization format
over 4.01 so Unison binaries compiled with different versions of OCaml
are not compatible! The PHP-FPM container is based on Jessie where OCaml
4.01 is available. Using docker-sync allows a newer Linux container to
be used for Unison with OCaml 4.02. There are almost no working binaries
still available for Mac using OCaml 4.01. The Windows binary for OCaml
4.02 is now included. So finally managed to find a combination that
works across all platforms. Egad!

Author: Alan Kent

README.md

@@ -14,9 +14,10 @@ control.
 DevBox contains all the the software packages you need to develop a Magento
 site, except for IDEs and web browsers. A local development environment
 typically starts with a database container (holding MySQL) and a web server
-container (holding the Magento source code). Other containers can be added as
-required for Varnish (recommended), Redis, RabbitMQ, and ElasticSearch. All
-containers run Linux inside.
+container (holding the Magento source code). On Mac and Windows, another
+container is used for file sharing (discussed below).  Other containers can be
+added as required for Varnish (recommended), Redis, RabbitMQ, and
+ElasticSearch. All containers run Linux inside.
 
 Developers mainly interact with the web container. The other containers are
 relatively shrink wrap.
@@ -43,16 +44,30 @@ Mac and Windows cannot directly access the file system inside the web container
   works fine. By default the volume mounts are commented out in the
   `docker-compose.yml` file for improved performance.
 
+* Docker volume mounts for Mac and Windows are slow for large projects like
+  Magento.
+
 * Some frontend developer tools like Gulp and Grunt rely on file watching
   "iNotify" file system events. Docker Volume mounting on Windows does not
   support iNotify events at this time.
 
 Where volume mounts are not suitable (specifically, the Magento source code
 directory on Mac and Windows), DevBox syncs the local and container file
-systems using a program called Unison. Whenever a file in the watched local file
-system is changed, it is copied into the web container, and vice versa. This
-allows IDEs to be natively used on a laptop (or desktop) - Unison copies file
-changes as soon as they are written to disk into the web conatiner.
+systems using a program called Unison. Whenever a file in the watched local
+file system is changed, it is copied into the web container, and vice versa.
+This allows IDEs to be natively used on a laptop (or desktop) - Unison copies
+file changes as soon as they are written to disk into the web conatiner.
+
+DevBox uses the "Docker Sync" project (http://docker-sync.io/) for file
+sharing, but only uses the Unison mode of file sharing.
+
+(Insiders secret: Unison is written in a language called OCaml. OCaml 4.01 and
+4.02 changed a serialization algorithm in a backwards incompatible way. So you
+need to make sure you have Unison binaries on Windows, Mac, and Linux compiled
+with the same version of OCaml. Brew + Docker-Sync + the supplied Windows
+binary currently all match. If you try experimenting with other binaries,
+beware the pit of despair when things start going strange for no apparent
+reason!)
 
 # Installation
 
@@ -70,6 +85,7 @@ ready to get up and going with DevBox.
   (https://git-for-windows.github.io/). As well as Git, it includes SSH, an
   xterm terminal emulator, and a useful collection of commonly used Linux
   commands.
+* On Mac, install "Brew" (https://brew.sh/) if you have not done so already.
 
 ## Setting Up a New Environment
 
@@ -91,15 +107,19 @@ this GitHub repository to the project directory.
 Review the `docker-compose.yml` file in a text editor, making necessary
 adjustments as described by comments in the file. This includes:
 
-* To enable volume mounting for the Magento source code (e.g. for Linux
-  laptops), uncomment the volume mount line for `/var/www` in the provided
-  `docker-compose.yml` file. For Unison (e.g. for Mac and Windows), ensure the
-  line is commented out.
+* For Mac and Windows, make sure the `src:/var/www` volume is uncommented and
+  the `./shared/www:/var/www` line is commented out. Make sure the "unison"
+  service is also uncommented. This is required for Unison to access the
+  Magento source code.
+
+* For Linux, direct file sharing can be used. Make sure the
+  `./shared/www:/var/www` line is uncommented and the `src:/var/www` line is
+  commented out. Also comment out the "unison" service as it is not required.
 
 * Check the port numbers. By default Docker will allocate random free port
-  numbers. Change "80" to "8080:80" if you want the web server port to be
-  always 8080. You cannot run different containers at the same time using
-  the same port numbers.
+  numbers. Change ports such as "80" to "8080:80" if you want the web server
+  port to be always 8080. You cannot run different containers at the same time
+  using the same port numbers.
 
 * The recommended way to create and update projects is via Composer, a PHP
   package manager. Magento provides a Composer repository from which Magento
@@ -157,6 +177,11 @@ If you are running Docker in VirtualBox, you may need to edit the local `m2ssh`
 and `m2unison` scripts to replace "localhost" with the IP address allocated by
 VirtualBox.
 
+Note: If you destroy and recreate containers, SSH may report warnings about
+changes in identity and refuse to connect. Use a text editor to remove
+"localhost" lines from your `~/.ssh/known_hosts` file to overcome this issue
+(you will then be prompted to accept new fingerprints on restart).
+
 ### 4. Install Magento
 
 Next you need to install your Magento project inside the web container under
@@ -330,18 +355,17 @@ be added when the project was created above.
 
 **Loading Sample Data (Optional)**
 
-To *download* the Luma sample data, you may need to provide Composer
+To download the Luma sample data, you may need to provide Composer
 authentication details. If you already have a `~/.composer/auth.json` file you
 can run
 
     COMPOSER_AUTH=$(cat ~/.composer/auth.json) magento sampledata:deploy
 
-OTHERWISE run the following command and enter your public and private keys when
+If you don't have a `~/.composer/auth.json` file, just run
+`magento sampledata:deploy` and enter your public and private keys when
 prompted.
 
-    magento sampledata:deploy
-
-To *load* the downloaded sample data into the database, run
+To load the downloaded sample data into the database, run
 
     magento setup:upgrade
 
@@ -368,6 +392,9 @@ purposes, but makes all PHP scripts slower to execute.
     magento deploy:mode:set developer
     xdebug-on
 
+TODO: SEPARATE CLI AND WEB SERVER PHP CONFIGURATION, SO XDEBUG ON BY DEFAULT
+FOR WEB SERVER BUT OFF FOR CLI. THEN WE CAN DROP xdebug-on AND xdebug-off.
+
 ### 8. Connect with a Web Browser
 
 Run the following command to determine the web server port number to use when
@@ -399,25 +426,51 @@ If you are using Unison for file syncing, you also need to start up a Unison
 process (and keep it running). It is generally recommended to start this up
 after you have installed Magento above.
 
+Each time you log to your laptop, make sure you restart Unison, but be careful
+to not have multiple copies running in parallel. It is not recommended to do
+significant work on the project without Unison running to avoid merge conflicts
+(rare).
+
+**Mac**
+
+TODO: VERIFY WHEN TESTING FINISHED.
+
+On Mac, first install Unison using "brew". This installs the correct command
+line version of Unison. Also install "unox" for a companion file watching
+utility.
+
+    brew install unison
+    brew tap eugenmayer/dockersync
+    brew install eugenmayer/dockersync/unox
+
+For Mac, create a "profile" file in `~/.unison/m2devbox-{myproj}.prf` ({myproj}
+is the current directory name) by running the following command.
+
+    ./m2unison-profile   TODO: THIS SHOULD RUN SSH TO ACCEPT SSH FINGERPRINT
+
+To perform a "once off" file synchronization, run
+
+    unison m2devbox-{myproj}
+
+To continuously synchronize files (recommended), run
+
+    unison -repeat watch m2devbox-{myproj}
+
+It is recommended to run Unison in a separate Terminal window so you can refer
+to its output if you ever need to do troubleshooting.
+
+**Windows**
+
 On Windows, run the supplied BAT file to launch Unison in a separate window
 using the START command or by double clicking the BAT file via Windows file
 explorer. This will automatically retrieve a copy of the `unison.exe` binary
-from the web container. Close the window to kill Unison.
+from the web container. A profile is not required as the BAT file uses command
+line arguments. Close the window to kill Unison.
 
     START m2unison.bat
 
-Mac binaries and a shell script are also provided. It is recommended to run the
-sync shell script in a separate Terminal window so you can refer to its output
-if you ever need to do troubleshooting.
-
-    ./m2unison.sh
-
-This shell script cannot be used on Linux, only Mac OSX. Use volume mounting on
-Linux (not Unison).
-
-Each time you log in, make sure you restart Unison, but be careful to not have
-multiple copies running in parallel. It is not recommended to do significant
-work on the project without Unison running to avoid merge conflicts (rare).
+There is a setting at the top of the script to choose between SSH access and
+direct sockets. Using a plain socket has been reported to hang occasionally.
 
 ### 10. Configure PHP Storm (Optional)
 

docker-compose.yml

@@ -9,12 +9,13 @@ services:
         restart: always
         image: alankent/magento2devbox-web:latest
 
-        # Uncomment this line if you uncomment any of the following volumes.
-        #volumes:
+        volumes:
 
-          # LEAVE THIS LINE COMMENTED OUT IF YOU ARE USING UNISON.
-          # Uncomment to use Docker volume mounts to share files with
-          # local file system.
+          # Uncomment the first line for use with Unison and the "unison" service
+          # below (Mac, Windows). Uncomment the second line instead to mount
+          # the volume directly (Linux). Comment out both lines if file sharing
+          # is not required.
+          - "src:/var/www"
           #- "./shared/www:/var/www"
 
           # Uncomment to share your ~/.ssh directory with the container.
@@ -67,15 +68,30 @@ services:
           # Storm reconfiguration.)
           - "2222:22"
 
-          # Pick a random unused unison port.
-          # (Only needed if using Unison for file syncing.)
-          - "5000"
-
           # Expose the BrowserSync ports.
           # (Only needed if using BrowserSync for frontend development.)
           - "3000"
           - "3001"
 
+    # This container contains the Unison process.
+    # Remove this service if not using Unison.
+    unison:
+        restart: always
+        image: alankent/magento2devbox-unison:latest
+
+        # Mount the /var/www directory from the "web" container.
+        volumes_from:
+          - "web"
+
+        ports:
+          # Pick a random unused unison "socket" port.
+          # This can be commented out if "ssh" access is used instead.
+          - "5000"
+
+          # Pick a random port for ssh based Unison connections (developers
+          # normally do not log in to this container).
+          - "22"
+
     db:
         restart: always
         image: mysql:5.6

m2ssh

@@ -15,4 +15,7 @@ SSH_HOST=$(docker-compose port web 22 | awk -F: '{
 
 SSH_PORT=$(docker-compose port web 22 | awk -F: '{print $2}')
 
+exec ssh -p ${SSH_PORT} magento2@${SSH_HOST} $*
+
+# The following version quietens more messages due to recreating containers
 exec ssh -o LogLevel=error -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p ${SSH_PORT} magento2@${SSH_HOST} $*

m2ssh.bat

@@ -5,4 +5,7 @@ FOR /f "delims=" %%A IN ('docker-compose port web 22') DO SET "CMD_OUTPUT=%%A"
 FOR /f "tokens=1,* delims=:" %%A IN ("%CMD_OUTPUT%") DO SET "SSH_PORT=%%B"
 
 REM Run SSH
-ssh -o LogLevel=error -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p %SSH_PORT% magento2@localhost %*
+ssh -p %SSH_PORT% magento2@localhost %*
+
+REM This version avoids problems when containers are destroyed and recreated
+REM ssh -o LogLevel=error -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p %SSH_PORT% magento2@localhost %*