Address permission problem

docs/getting-started/start-the-devilbox.rst

@@ -1,3 +1,5 @@
+.. _start_the_devilbox:
+
 ******************
 Start the Devilbox
 ******************

docs/readings/available-container.rst

@@ -3,3 +3,30 @@
 *******************
 Available container
 *******************
+
+.. note::
+   :ref:`start_the_devilbox`
+       Find out how to start some or all container.
+
+The following table gives you an overview about all container that can be started.
+When doing a selective start, use the ``Name`` value to specify the container to start up.
+
++---------------------------+-------+----------+----------------+
+| Container                 | Name  | Hostname | IP Address     |
++===========================+=======+==========+================+
+| DNS                       | bind  | bind     | 172.16.238.100 |
++---------------------------+-------+----------+----------------+
+| PHP, HHVM                 | php   | php      | 172.16.238.10  |
++---------------------------+-------+----------+----------------+
+| Apache, Nginx             | httpd | httpd    | 172.16.238.11  |
++---------------------------+-------+----------+----------------+
+| MySQL, MariaDB, PerconaDB | mysql | mysql    | 172.16.238.12  |
++---------------------------+-------+----------+----------------+
+| PostgreSQL                | pgsql | pgsql    | 172.16.238.13  |
++---------------------------+-------+----------+----------------+
+| Redis                     | redis | redis    | 172.16.238.14  |
++---------------------------+-------+----------+----------------+
+| Memcached                 | memcd | memcd    | 172.16.238.15  |
++---------------------------+-------+----------+----------------+
+| MongoDB                   | mongo | mongo    | 172.16.238.16  |
++---------------------------+-------+----------+----------------+

docs/readings/syncronize-container-permissions.rst

@@ -3,3 +3,88 @@
 ********************************
 Syncronize container permissions
 ********************************
+
+One main problem with a running Docker container is to **synchronize the ownership of files in a
+mounted volume** in order to preserve security (Not having to use ``chmod 0777`` or root user).
+
+This problem will be addressed below by using a PHP-FPM docker image as an example.
+
+Unsyncronized permissions
+=========================
+
+Consider the following directory structure of a mounted volume. Your hosts computer uid/gid are
+``1000`` which does not have a corresponding user/group within the container. Fortunately the
+``tmp/`` directory allows everybody to create new files in it, because its permissions are
+``0777``.
+
+.. code-block:: bash
+
+                     [Host]                   |             [Container]
+   ------------------------------------------------------------------------------------------
+    $ ls -l                                   | $ ls -l
+    -rw-r--r-- user group index.php           | -rw-r--r-- 1000 1000 index.php
+    drwxrwxrwx user group tmp/                | drwxrwxrwx 1000 1000 tmp/
+
+Your web application might now have created some temporary files (via the PHP-FPM process) inside
+the ``tmp/`` directory:
+
+.. code-block:: bash
+
+                     [Host]                   |             [Container]
+   ------------------------------------------------------------------------------------------
+    $ ls -l tmp/                              | $ ls -l tmp/
+    -rw-r--r-- 96 96 _tmp_cache01.php         | -rw-r--r-- www www _tmp_cache01.php
+    -rw-r--r-- 96 96 _tmp_cache02.php         | -rw-r--r-- www www _tmp_cache01.php
+
+On the Docker container side everything is still fine, but on your host computers side, those
+files now show a user id and group id of ``96``, which is in fact the uid/gid of the PHP-FPM
+process running inside the container. On the host side you have just lost write/delete access to
+those files and will now have to use ``sudo`` in order to delete/edit those files.
+
+
+It gets even worse
+==================
+
+Consider your had created the ``tmp/`` directory on your host only with ``0775`` permissions:
+
+.. code-block:: bash
+
+                     [Host]                   |             [Container]
+   ------------------------------------------------------------------------------------------
+    $ ls -l                                   | $ ls -l
+    -rw-r--r-- user group index.php           | -rw-r--r-- 1000 1000 index.php
+    drwxrwxr-x user group tmp/                | drwxrwxr-x 1000 1000 tmp/
+
+If your web application now wants to create some temporary files (via the PHP-FPM process) inside
+the ``tmp/`` directory, it will fail due to lack of permissions.
+
+
+The solution
+============
+
+To overcome this problem, it must be made sure that the PHP-FPM process inside the container runs
+under the same uid/gid as your local user that mouns the volumes and also wants to work on those
+files locally. However, you never know during Image build time what user id this would be.
+Therefore it must be something that can be changed during startup of the container.
+
+This is achieved in the Devilbox's containers by two environment variables that can be provided
+during startup in order to change the uid/gid of the PHP-FPM user prior starting up PHP-FPM process.
+
+.. code-block:: bash
+
+   $ docker run -e NEW_UID=1000 -e NEW_GID=1000 -it devilbox/php-fpm:7.2-work
+   [INFO] Changing user 'devilbox' uid to: 1000
+   root $ usermod -u 1000 devilbox
+   [INFO] Changing group 'devilbox' gid to: 1000
+   root $ groupmod -g 1000 devilbox
+   [INFO] Starting PHP 7.2.0 (fpm-fcgi) (built: Oct 30 2017 12:05:19)
+
+
+When ``NEW_UID`` and ``NEW_GID`` are provided to the startup command, the container will do a
+``usermod`` and ``groupmod`` prior starting up in order to assign new uid/gid to the PHP-FPM user.
+When the PHP-FPM process finally starts up it actually runs with your local system user and making
+sure permissions will be in sync from now on.
+
+.. note::
+    To tackle this on the PHP-FPM side is only half a solution to the problem. The same applies to a web server Docker container when you offer **file uploads**. They will be uploaded and created by the web servers uid/gid. Therefore the web server itself must also provide the same kind of solution.
+