Extend env file documentation

docs/configuration-files/env-file.rst

@@ -46,8 +46,10 @@ The only reason you would ever want change this variable is when you are on MacO
 your project files onto an NFS volume due to performance issues.
 
 .. warning::
-   Whenever you change this value you have to stop the Devilbox and re-create your volumes via
-   ``docker-compose rm -f``.
+   :ref:`remove_stopped_container`
+     Whenever you change this value you have to stop the Devilbox and also remove the stopped
+     container via
+     ``docker-compose rm``.
 
 +-------------------+----------------+---------------+
 | Name              | Allowed values | Default value |
@@ -131,6 +133,12 @@ this project visible to everyone in your corporate LAN.
 | www.test    | ``org``        | ``http://www.test.org``   |
 +-------------+----------------+---------------------------+
 
+.. warning::
+   Do not use ``dev`` (I know, it's tempting) as a domain suffix, as it has been registered by
+   `Google <https://icannwiki.org/.dev>`_ and they advertise the
+   `HSTS header <https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security>`_
+   which makes your browser redirect every http request to https.
+
 
 .. _env_new_uid:
 
@@ -587,6 +595,107 @@ Mapping
 No matter what path you assign, inside the PHP and the web server container your data dir will
 always be ``/shared/httpd/``.
 
+.. warning::
+   Do not create any symlinks inside your project directories that go outside the data dir.
+   Anything which is outside this directory is not mounted into the container.
+
+.. warning::
+   :ref:`remove_stopped_container`
+     Whenever you change this value you have to stop the Devilbox and also remove the stopped
+     container via
+     ``docker-compose rm``.
+
+
+HOST_PATH_MYSQL_DATADIR
+-----------------------
+
+This is an absolute or relative path (relative to Devilbox git directory) to your MySQL data directory.
+
+* Relative path: relative to the devilbox git directory (Must start with ``.``)
+* Absolute path: Full path (Must start with ``/``)
+
++------------------------------+----------------+------------------+
+| Name                         | Allowed values | Default value    |
++==============================+================+==================+
+| ``HOST_PATH_MYSQL_DATADIR``  | valid path     | ``./data/mysql`` |
++------------------------------+----------------+------------------+
+
+Each MySQL, MariaDB or PerconaDB version will have its own subdirectory, so when first running MySQL 5.5
+and then starting MySQL 5.6, you will have a different database with different data.
+
+Having each version separated from each other makes sure that you don't accidently upgrade
+from a lower to a higher version which might not be reversable. (MySQL auto-upgrade certain older
+data files to newer, but this process does not necessarily work the other way round and could result in failues).
+
+The directory structure will look something like this:
+
+.. code-block:: bash
+
+    host> ls -l ./data/mysql/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.0/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.1/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.2/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.3/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.5/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.6/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.7/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-8.0/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.5/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.6/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.7/
+
+.. warning::
+   :ref:`remove_stopped_container`
+     Whenever you change this value you have to stop the Devilbox and also remove the stopped
+     container via
+     ``docker-compose rm``.
+
+
+HOST_PATH_PGSQL_DATADIR
+-----------------------
+
+This is an absolute or relative path (relative to Devilbox git directory) to your PostgreSQL data directory.
+
+* Relative path: relative to the devilbox git directory (Must start with ``.``)
+* Absolute path: Full path (Must start with ``/``)
+
++------------------------------+----------------+------------------+
+| Name                         | Allowed values | Default value    |
++==============================+================+==================+
+| ``HOST_PATH_PGSQL_DATADIR``  | valid path     | ``./data/pgsql`` |
++------------------------------+----------------+------------------+
+
+Each PostgreSQL version will have its own subdirectory, so when first running PostgreSQL 9.1
+and then starting PostgreSQL 10.0, you will have a different database with different data.
+
+Having each version separated from each other makes sure that you don't accidently upgrade
+from a lower to a higher version which might not be reversable.
+
+The directory structure will look something like this:
+
+.. code-block:: bash
+
+    host> ls -l ./data/pgsql/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.1/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.2/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.3/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.4/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.5/
+    drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.6/
+
+.. warning::
+   :ref:`remove_stopped_container`
+     Whenever you change this value you have to stop the Devilbox and also remove the stopped
+     container via
+     ``docker-compose rm``.
+
+
+
+
+
+
+
+
 
 
 .. |br| raw:: html

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

@@ -78,6 +78,23 @@ your favorite diff editor:
    host> meld .env env-example
 
 
+Recreate container
+------------------
+
+Whenever the path of a volume changes (either due to upstream changes in git or due to you changing
+it manually in the ``.env`` file) you need to remove the stopped container and have them fully
+recreated during the next start.
+
+.. code-block:: bash
+
+   # Remove anonymous volumes
+   host> cd path/to/devilbox
+   host> docker-compose rm
+
+.. seealso::
+   :ref:`remove_stopped_container`
+
+
 Update Docker container
 =======================
 
@@ -100,30 +117,15 @@ which will update all available Docker images at once.
      latest security patches and tool versions are applied.
 
 
-Remove anonymous volumes
-========================
-
-The devilbox is not yet at a feature-ready stable release and volumes mounts might change from release to release until version 1.0 will be released. This can cause errors during startup. To solve those issues after updating, you should remove all anonymouse volumes with the following command:
-
-.. code-block:: bash
-
-   # Remove anonymous volumes
-   host> cd path/to/devilbox
-   host> docker-compose rm
-
-
 Checklist git repository
 ========================
 
-1. Ensure containers are stopped
+1. Ensure containers are stopped and removed/recreated
 2. Ensure desired branch, tag or commit is checked out or latest changes are pulled
 3. Ensure ``.env`` file is in sync with ``env-example`` file
-4. Ensure anonymous volumes are removed
 
 
 Checklist Docker images
 =======================
 
 1. Ensure ``./update-docker.sh`` is executed
-2. Ensure anonymous volumes are removed
-

docs/index.rst

@@ -104,6 +104,7 @@ devilbox documentation
    installation/docker-installation
    installation/docker-toolbox
    readings/available-container
+   readings/remove-stopped-container
    readings/syncronize-container-permissions
 
 

docs/readings/remove-stopped-container.rst

@@ -0,0 +1,31 @@
+.. _remove_stopped_container:
+
+************************
+Remove stopped container
+************************
+
+Why should I?
+=============
+
+If you simply ``docker-compose stop`` in order to stop all containers, they are still preserved
+in the ``docker ps -a`` process list and still have state.
+
+In case you change any path variables inside the ``.env`` file (or silently due to git updates),
+you need to completely re-create the state.
+
+This is done by first fully removing the container and then simply starting it again.
+
+
+How to do it?
+=============
+
+.. code-block:: bash
+
+   host> docker-compose stop
+   host> docker-compose rm
+
+
+When to do it?
+==============
+
+Whenever path values inside the ``.env`` file change.