Tidy up page organization

docs/advanced/native-osx-under-the-hood.rst → docs/advanced/how-it-works.rst

@@ -1,5 +1,27 @@
-native_osx Under the Hood
-=========================
+************
+How it works
+************
+
+Architecture
+============
+
+On the host, a thor based ruby task is started, this starts:
+
+    - Every sync will start an own docker-container with a rsync/unison-daemon watching for connections.
+    - The data gets pre-synced on sync-start
+    - A fswatch cli-task gets setup, to run rsync/unison on each file-change in the source-folder you defined
+
+Done. No magic. But its roadrunner fast! And it has no pre-conditions on your actual stack.
+
+----
+
+.. _native_osx in depth:
+
+native_osx in depth
+===================
+
+Under The Hood
+--------------
 
 First, take a look at this diagram:
 
@@ -32,3 +54,20 @@ Is this strategy absolutely bullet proof?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 No, it is not. But it has been pretty battle proven already - the main issue is https://github.com/EugenMayer/docker-sync/issues/410 - so sometimes OSXFS just stops triggering FS events in Hyperkit, thus in the sync-container. This leads to an issue with our sync, since the ``unison`` daemon inside the app-sync  container relies on those events to sync the changes (it does not have the ability to poll, which would be disastrous performance-wise, anyway).
+
+Advanced Monitoring for ``native_osx``
+--------------------------------------
+
+Background
+^^^^^^^^^^
+
+Monit_ is a utility which can be used to monitor the health of the ``unison`` process which runs in the container for the ``native_osx`` strategy. If it detects that ``unison`` is unhealthy, Monit automatically restarts ``unison``. This improves the stability of the ``native_osx`` container in cases where the ``unison`` process is misbehaving but does not necessarily crash. Currently, there is only one check for CPU usage implemented, but in the future more checks may be added, such as memory usage. It is currently turned off by default and can be turned on in the configuration:
+
+https://github.com/EugenMayer/docker-sync/blob/master/example/docker-sync.yml#L120-L126
+
+.. _Monit: https://mmonit.com/monit/
+
+Monitoring CPU usage
+^^^^^^^^^^^^^^^^^^^^
+
+One instance which ``unison`` has been seen to misbehave is when quickly creating and deleting a file while it is processing it. ``unison`` may hang, using a high amount of cpu time: https://github.com/EugenMayer/docker-sync/issues/497. ``monit`` detects this high cpu usage (>50%) and automatically restarts ``unison`` to recover it. By default this happens within 10 seconds, but the tolerance can be configured in case there are normal spikes in cpu usage during successful syncs.

docs/advanced/scripting.rst

@@ -1,23 +1,21 @@
-Scripting with docker-sync
-==========================
+Scripting
+=========
 
 We use docker-sync as a library in our own docker-stack startup script. It starts the docker-compose stack using a Ruby gem `EugenMayer/docker-compose`_ all this wrapped into a thor task. So:
 
  - Start docker-sync
  - Start a docker-compose stack based on some arguments like --dev and load the specific docker-compose files for that using `xeger/docker-compose`_
 
-.. _EugenMayer/docker-compose: https://github.com/EugenMayer/docker-compose
-.. _xeger/docker-compose: https://github.com/xeger/docker-compose
-
-Example
--------
-
 docker-sync-stack is actually an example already, just see here:
 
 1. You run the sync manager with run : https://github.com/EugenMayer/docker-sync/blob/master/tasks/stack/stack.thor#L37
 2. But you do not call .join_threads after that like her https://github.com/EugenMayer/docker-sync/blob/master/tasks/sync/sync.thor#L36
 3. Then you just continue doing what you want to script, in my case, i start a new blocking task - docker-compose. But you could do anything.
 
+.. _EugenMayer/docker-compose: https://github.com/EugenMayer/docker-compose
+.. _xeger/docker-compose: https://github.com/xeger/docker-compose
+
+
 Simple scripting example
 ------------------------
 
@@ -54,5 +52,3 @@ Simple scripting example
       puts "MESSAGE: #{e.message}"
 
     end
-
-That is basically it. Fairly easy, I would say.

docs/advanced/sync-strategies.rst

@@ -1,4 +1,4 @@
-Sync Strategies
+Sync strategies
 ===============
 
 The sync strategies depend on the OS, so not all strategies are available on all operating system
@@ -17,7 +17,7 @@ native_osx (OSX)
 .. image:: /_static/native_osx.png
   :alt: DockerSync native_osx strategy overview
 
-For advanced understanding, please read :doc:`../advanced/native-osx-under-the-hood`.
+For advanced understanding, please read :ref:`native_osx in depth`.
 
 Native-OSX is a combination of two concepts, `OSXFS only`_ and Unison together. We use OSX to sync the file-system into a sync-container to /host_sync. In that sync container we sync from /host_sync to /app_sync using Unison. /app_sync is exposed as a named volume mount and consumed in the app. You ask yourself, why? Its fairly simple.
 
@@ -45,7 +45,7 @@ Cons
 
 ----
 
-Unison (OSX/Windows/Linux)
+unison (OSX/Windows/Linux)
 --------------------------
 
 This strategy has the biggest drive to become the new default player out of the current technologies. It seems to work very well with huge codebases too. It generally is build to handle 2 way sync, so syncs back changes from the container to the host.
@@ -97,4 +97,4 @@ Native linux is actually no real implementation, it just wraps docker-sync aroun
 Sync Flags or Options
 ---------------------
 
-You find the available options for each strategy in :doc:`../configuration/index`.
+You find the available options for each strategy in :doc:`../getting-started/configuration`.

docs/miscellaneous/complimentary-projects.rst → docs/advanced/tips-and-tricks.rst

@@ -1,8 +1,9 @@
-Complimentary Projects and Tips
-===============================
+***************
+Tips and tricks
+***************
 
 HTTP Proxy and DNS
-------------------
+==================
 
 The HTTP Proxy and DNS used in dinghy_ is available as a standalone project dinghy-http-proxy_.  The proxy is based on jwilder's excellent
 nginx-proxy_ project, with modifications to make it more suitable for local development work. A DNS resolver is also added. By default it will resolve all ``*.docker`` domains to the Docker VM, but this can be changed.
@@ -12,14 +13,14 @@ nginx-proxy_ project, with modifications to make it more suitable for local deve
 .. _nginx-proxy: https://github.com/jwilder/nginx-proxy
 
 SSH-Agent Forwarding
---------------------
+====================
 
 If you need to access some private git repos or ssh servers, it could be useful to use have a ssh-agent accessible from your containers. `whilp/ssh-agent`_ helps you to do so easily.
 
 .. _whilp/ssh-agent: https://github.com/whilp/ssh-agent
 
 Running composer or other tools like if they were on the host
--------------------------------------------------------------
+=============================================================
 
 If you run composer and other tools directly in containers, you could use a combination of the autoenv_ zsh plugin and a simple wrapper script to run it easily directly from the host. In your project folder, create a ``.autoenv.zsh`` file with the name of your container:
 
@@ -43,12 +44,12 @@ then create a simple function in your ``.zshrc``:
 .. _autoenv: https://github.com/Tarrasch/zsh-autoenv
 
 Ignore files in your IDE
----------------------------
+========================
 
 It's a good idea to add the temporary sync files to your IDE's ignore list to prevent your IDE from indexing them all the time or showing up in search results. In case of unison and PHPStorm for example just go to Preferences -> File Types -> Ignore files and folders and add ``.unison`` to the pattern.
 
 Don't sync everything
----------------------
+=====================
 
 You should only sync files that you really need on both the host and client side. You will see that the sync performance will improve drastically when you ignore unnecessary files. How and which files to ignore depends on your syncing strategy (rsync/unison/...) and your project.