Extend env file documentation

docs/configuration-files/env-file.rst

@@ -11,13 +11,13 @@ variables parsed to docker-compose.yml.
    what is the `.env <https://docs.docker.com/compose/env-file/>`_ file?
 
 
-**Content**
+**Table of Contents**
 
 .. contents:: :local:
 
 
-General settings
+Core settings
-================
+=============
 
 DEBUG_COMPOSE_ENTRYPOINT
 ------------------------
@@ -39,6 +39,9 @@ DEVILBOX_PATH
 This specifies a relative or absolute path to the Devilbox git directory and will be used as a
 prefix for all Docker mount paths.
 
+* Relative path: relative to the devilbox git directory (Must start with ``.``)
+* Absolute path: Full path (Must start with ``/``)
+
 The only reason you would ever want change this variable is when you are on MacOS and relocate
 your project files onto an NFS volume due to performance issues.
 
@@ -82,15 +85,52 @@ colon (``:``).
 |                  | listen on all host computer interfaces / IP addresses                         |
 +------------------+-------------------------------------------------------------------------------+
 
+.. note::
+   When using ``Docker Toolbox``, you must leave this variable empty, in order to have the exposed
+   ports available on the external interface of the virtual machine.
+
 
 TLD_SUFFIX
 ----------
 
+This variable controls all of your projects domain suffix.
 
++----------------+------------------+---------------+
+| Name           | Allowed values   | Default value |
++================+==================+===============+
+| ``TLD_SUFFIX`` | alpha-num string | ``loc``       |
++----------------+------------------+---------------+
+
+Your project domains are built together out of the project directory name and the ``TLD_SUFFIX``.
+The formula is like this: ``http://<project-dir>.<TLD_SUFFIX>``.
+
+You can even use official tld's and have your nameserver point to an internal LAN id, to make
+this project visible to everyone in your corporate LAN.
+
+**How does it look?**
+
++-------------+----------------+---------------------------+
+| Project dir | ``TLD_SUFFIX`` | Project URL               |
++=============+================+===========================+
+| my-test     | ``loc``        | ``http://my-test.loc``    |
++-------------+----------------+---------------------------+
+| example     | ``loc``        | ``http://example.loc``    |
++-------------+----------------+---------------------------+
+| www.test    | ``loc``        | ``http://www.test.loc``   |
++-------------+----------------+---------------------------+
+| my-test     | ``local``      | ``http://my-test.local``  |
++-------------+----------------+---------------------------+
+| example     | ``local``      | ``http://example.local``  |
++-------------+----------------+---------------------------+
+| www.test    | ``local``      | ``http://www.test.local`` |
++-------------+----------------+---------------------------+
+| my-test     | ``net``        | ``http://my-test.net``    |
++-------------+----------------+---------------------------+
+| example     | ``com``        | ``http://example.com``    |
++-------------+----------------+---------------------------+
+| www.test    | ``org``        | ``http://www.test.org``   |
++-------------+----------------+---------------------------+
 
-.. note::
-   When using ``Docker Toolbox``, you must leave this variable empty, in order to have the exposed
-   ports available on the external interface of the virtual machine.
 
 .. _env_new_uid:
 
@@ -173,3 +213,382 @@ Have a look at Wikipedia to get a list of valid timezones: https://en.wikipedia.
 .. note::
    It is always a good practice not to assume a specific timezone anyway and store all values
    in UTC (such as time types in MySQL).
+
+
+Intranet settings
+=================
+
+
+DNS_CHECK_TIMEOUT
+-----------------
+
+The Devilbox intranet validates if every project has a corresponding DNS record (either an official
+DNS record, one that came from its own Auto-DNS or an ``/etc/hosts`` entry). By doing so it queries
+the DNS record based on ``<project-dir>.<TLD_SUFFIX>``. In case it does not exist, the query itself
+might take a while and the intranet page will be unresponsive during that time. In order to avoid
+long waiting times, you can set the DNS query time-out in seconds after which the query should stop
+and report as unsuccessful. The default is ``1`` second, wich should be fairly sane for all use-cases.
+
++-----------------------+----------------+-------------------+
+| Name                  | Allowed values | Default value     |
++=======================+================+===================+
+| ``DNS_CHECK_TIMEOUT`` | integers       | ``1``             |
++-----------------------+----------------+-------------------+
+
+
+
+
+DEVILBOX_UI_PROTECT
+-------------------
+
+By setting this variable to ``1``, the Devilbox intranet will be password protected.
+This might be useful, if you share your running Devilbox instance accross a LAN, but do not want
+everybody to have access to the intranet itself, just to the projects you actually provide.
+
++-------------------------+----------------+-------------------+
+| Name                    | Allowed values | Default value     |
++=========================+================+===================+
+| ``DEVILBOX_UI_PROTECT`` | ``0`` or ``1`` | ``0``             |
++-------------------------+----------------+-------------------+
+
+.. note::
+   Also pay attention to the next env var, which will control the password for the login:
+   ``DEVILBOX_UI_PASSWORD``.
+
+
+DEVILBOX_UI_PASSWORD
+--------------------
+
+When the devilbox intranet is password-protected via ``DEVILBOX_UI_PROTECT``, this is the actual
+password by which it will be protected.
+
++--------------------------+----------------+-------------------+
+| Name                     | Allowed values | Default value     |
++==========================+================+===================+
+| ``DEVILBOX_UI_PASSWORD`` | any string     | ``password``      |
++--------------------------+----------------+-------------------+
+
+
+DEVILBOX_UI_DISABLE
+-------------------
+
+In case you want to completely disable the Devilbox intranet, such as when running it on production,
+you need to set this variable to ``1``.
+
+By disabling the intranet, the webserver will simply remove the default virtual host and redirect
+all IP-based requests to the first available virtual host, which will be you first project when
+ordering their names alphabetically.
+
++-------------------------+----------------+-------------------+
+| Name                    | Allowed values | Default value     |
++=========================+================+===================+
+| ``DEVILBOX_UI_DISABLE`` | ``0`` or ``1`` | ``0``             |
++-------------------------+----------------+-------------------+
+
+
+Docker image versions
+=====================
+
+The following settings reflect one of the main goals of the Devilbox: being able to run any
+combination of all container versions.
+
+.. note::
+   Any change for those settings requires a restart of the devilbox.
+
+
+PHP_SERVER
+----------
+
+This variable choses your desired PHP-FPM version to be started.
+
++-------------------------+--------------------------------------------------------------------------------------------------------------------------+-----------------+
+| Name                    | Allowed values                                                                                                           | Default value   |
++=========================+==========================================================================================================================+=================+
+| ``PHP_SERVER``          | ``php-fpm-5.4`` |br| ``php-fpm-5.5`` |br| ``php-fpm-5.6`` |br| ``php-fpm-7.0`` |br| ``php-fpm-7.1`` |br| ``php-fpm-7.2`` | ``php-fpm-7.1`` |
++-------------------------+--------------------------------------------------------------------------------------------------------------------------+-----------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 7
+
+   host> grep PHP_SERVER .env
+
+   #PHP_SERVER=php-fpm-5.4
+   #PHP_SERVER=php-fpm-5.5
+   #PHP_SERVER=php-fpm-5.6
+   #PHP_SERVER=php-fpm-7.0
+   PHP_SERVER=php-fpm-7.1
+   #PHP_SERVER=php-fpm-7.2
+   #PHP_SERVER=php-fpm-7.3
+   #PHP_SERVER=hhvm-latest
+
+
+HTTPD_SERVER
+------------
+
+This variable choses your desired web server version to be started.
+
++-------------------------+----------------------------------------------------------------------------------+------------------+
+| Name                    | Allowed values                                                                   | Default value    |
++=========================+==================================================================================+==================+
+| ``HTTPD_SERVER``        | ``apache-2.2`` |br| ``apache-2.4`` |br| ``nginx-stable`` |br| ``nginx-mainline`` | ``nginx-stable`` |
++-------------------------+----------------------------------------------------------------------------------+------------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 5
+
+   host> grep HTTPD_SERVER .env
+
+   #HTTPD_SERVER=apache-2.2
+   #HTTPD_SERVER=apache-2.4
+   HTTPD_SERVER=nginx-stable
+   #HTTPD_SERVER=nginx-mainline
+
+
+MYSQL_SERVER
+------------
+
+This variable choses your desired MySQL server version to be started.
+
++-------------------------+------------------------------------------------------------------------------------------------+------------------+
+| Name                    | Allowed values                                                                                 | Default value    |
++=========================+================================================================================================+==================+
+| ``MYSQL_SERVER``        | ``mysql-5.5`` |br| ``mysql-5.6`` |br| ``mariadb-10.2`` |br| ``percona-5.7`` |br| and many more | ``mariadb-10.1`` |
++-------------------------+------------------------------------------------------------------------------------------------+------------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 9
+
+   host> grep MYSQL_SERVER .env
+
+   #MYSQL_SERVER=mysql-5.5
+   #MYSQL_SERVER=mysql-5.6
+   #MYSQL_SERVER=mysql-5.7
+   #MYSQL_SERVER=mysql-8.0
+   #MYSQL_SERVER=mariadb-5.5
+   #MYSQL_SERVER=mariadb-10.0
+   MYSQL_SERVER=mariadb-10.1
+   #MYSQL_SERVER=mariadb-10.2
+   #MYSQL_SERVER=mariadb-10.3
+   #MYSQL_SERVER=percona-5.5
+   #MYSQL_SERVER=percona-5.6
+   #MYSQL_SERVER=percona-5.7
+
+
+PGSQL_SERVER
+------------
+
+This variable choses your desired PostgreSQL server version to be started.
+
++-------------------------+-------------------------------------------------------------------+------------------+
+| Name                    | Allowed values                                                    | Default value    |
++=========================+===================================================================+==================+
+| ``PGSQL_SERVER``        | ``9.1`` |br| ``9.2`` |br| ``9.3`` |br| ``9.4`` |br| and many more | ``9.6``          |
++-------------------------+-------------------------------------------------------------------+------------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 8
+
+   host> grep PGSQL_SERVER .env
+
+   #PGSQL_SERVER=9.1
+   #PGSQL_SERVER=9.2
+   #PGSQL_SERVER=9.3
+   #PGSQL_SERVER=9.4
+   #PGSQL_SERVER=9.5
+   PGSQL_SERVER=9.6
+   #PGSQL_SERVER=10.0
+
+.. note::
+   This is the official PostgreSQL server which might already have other tags available,
+   check their official website for even more versions.
+   https://hub.docker.com/_/postgres/
+
+
+REDIS_SERVER
+------------
+
+This variable choses your desired Redis server version to be started.
+
++-------------------------+-------------------------------------------------------------------+------------------+
+| Name                    | Allowed values                                                    | Default value    |
++=========================+===================================================================+==================+
+| ``REDIS_SERVER``        | ``2.8`` |br| ``3.0`` |br| ``3.2`` |br| ``4.0`` |br| and many more | ``4.0``          |
++-------------------------+-------------------------------------------------------------------+------------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 6
+
+   host> grep REDIS_SERVER .env
+
+   #REDIS_SERVER=2.8
+   #REDIS_SERVER=3.0
+   #REDIS_SERVER=3.2
+   REDIS_SERVER=4.0
+
+.. note::
+   This is the official Redis server which might already have other tags available,
+   check their official website for even more versions.
+   https://hub.docker.com/_/redis/
+
+
+MEMCD_SERVER
+------------
+
+This variable choses your desired Memcached server version to be started.
+
++-------------------------+-------------------------------------------------------------------------------+------------------+
+| Name                    | Allowed values                                                                | Default value    |
++=========================+===============================================================================+==================+
+| ``MEMCD_SERVER``        | ``1.4.21`` |br| ``1.4.22`` |br| ``1.4.23`` |br| ``1.4.24`` |br| and many more | ``1.5.2``        |
++-------------------------+-------------------------------------------------------------------------------+------------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 24
+
+   host> grep MEMCD_SERVER .env
+
+   #MEMCD_SERVER=1.4.21
+   #MEMCD_SERVER=1.4.22
+   #MEMCD_SERVER=1.4.23
+   #MEMCD_SERVER=1.4.24
+   #MEMCD_SERVER=1.4.25
+   #MEMCD_SERVER=1.4.26
+   #MEMCD_SERVER=1.4.27
+   #MEMCD_SERVER=1.4.28
+   #MEMCD_SERVER=1.4.29
+   #MEMCD_SERVER=1.4.30
+   #MEMCD_SERVER=1.4.31
+   #MEMCD_SERVER=1.4.32
+   #MEMCD_SERVER=1.4.33
+   #MEMCD_SERVER=1.4.34
+   #MEMCD_SERVER=1.4.35
+   #MEMCD_SERVER=1.4.36
+   #MEMCD_SERVER=1.4.37
+   #MEMCD_SERVER=1.4.38
+   #MEMCD_SERVER=1.4.39
+   #MEMCD_SERVER=1.5.0
+   #MEMCD_SERVER=1.5.1
+   MEMCD_SERVER=1.5.2
+   #MEMCD_SERVER=latest
+
+.. note::
+   This is the official Memcached server which might already have other tags available,
+   check their official website for even more versions.
+   https://hub.docker.com/_/memcached/
+
+
+MONGO_SERVER
+------------
+
+This variable choses your desired MongoDB server version to be started.
+
++-------------------------+-------------------------------------------------------------------+------------------+
+| Name                    | Allowed values                                                    | Default value    |
++=========================+===================================================================+==================+
+| ``MONGO_SERVER``        | ``2.8`` |br| ``3.0`` |br| ``3.2`` |br| ``3.4`` |br| and many more | ``3.4``          |
++-------------------------+-------------------------------------------------------------------+------------------+
+
+All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+   :emphasize-lines: 6
+
+   host> grep MONGO_SERVER .env
+
+   #MONGO_SERVER=2.8
+   #MONGO_SERVER=3.0
+   #MONGO_SERVER=3.2
+   MONGO_SERVER=3.4
+   #MONGO_SERVER=3.5
+
+.. note::
+   This is the official MongoDB server which might already have other tags available,
+   check their official website for even more versions.
+   https://hub.docker.com/_/mongo/
+
+
+Docker host mounts
+==================
+
+The Docker host mounts are directory paths on your host operating system that will be mounted into
+the running Docker container. This makes data persistent accross restarts and let them be available
+on both sides: Your host operating system as well as inside the container.
+
+This also gives you the choice to edit data on your host operating system, such as with your
+favourite IDE/editor and also inside the container, by using the bundled tools, such as
+downloading libraries with ``composer`` and others.
+
+Being able to do that on both sides, removes the need to install any development tools (except your
+IDE/editor) on your host and have everything fully encapsulated into the containers itself.
+
+
+HOST_PATH_HTTPD_DATADIR
+-----------------------
+
+This is an absolute or relative path (relative to Devilbox git directory) to your data directory.
+
+.. seealso::
+   :ref:`getting_started_directory_overview_datadir`
+
+By default, all of your websites/projects will be stored in that directory. If however you want
+to separate your data from the Devilbox git directory, do change the path to a place where you
+want to store all of your projects on your host computer.
+
+* 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_HTTPD_DATADIR``  | valid path     | ``./data/www`` |
++------------------------------+----------------+----------------+
+
+Example
+^^^^^^^
+
+If you want to move all your projects to ``/home/myuser/workspace/web/`` for example, just set it
+like this:
+
+.. code-block:: bash
+   :caption: .env
+   :name: .env
+
+    HOST_PATH_HTTPD_DATADIR=/home/myuser/workspace/web
+
+Mapping
+^^^^^^^
+
+No matter what path you assign, inside the PHP and the web server container your data dir will
+always be ``/shared/httpd/``.
+
+
+
+.. |br| raw:: html
+
+   <br />

docs/getting-started/create-your-first-project.rst

@@ -1,3 +1,5 @@
+.. _getting_started_create_your_first_project:
+
 *************************
 Create your first project
 *************************
@@ -7,132 +9,14 @@ Create your first project
      This section not only applies for one project, it applied for as many projects as you need.
      **There is no limit in the number of projects.**
 
-.. _prerequisites:
 
-Prerequisites
+**Table of Contents**
-=============
 
-.. important::
+.. contents:: :local:
-     The prerequisites section only provides you some theoretical, but useful insights about how
-     it all works together. You should at least read it once to be able to debug any problems you
-     might encounter.
 
-If you have read it already, jump directly to :ref:`project_creation_workflow`
-
-
-Data directory
---------------
-
-By default all your projects must be created in the ``./data/www/`` directory which is inside in
-your Devilbox git directory. This can be changed as well, but is outside the scope of this
-*getting started tutorial*.
-
-You can verifiy that the path is actually ``./data/www/`` by checking your ``.env`` file:
-
-.. code-block:: bash
-
-   host> grep HTTPD_DATADIR .env
-
-   HOST_PATH_HTTPD_DATADIR=./data/www
-
-
-Project directory
------------------
-
-The project directory is a directory directly within the data directory.
-
-**This represents one project.**
-
-By creating this directory, the web server will create a new virtual host for you. This
-happens fully automated and there is nothing else required to do except just to create a directory.
-
-The name of this directory will also be used to build up the final project url together with the
-domain suffix: ``http://<project directory>.<domain suffix>``
-
-Create as many project directories as you require.
-
-
-Docroot directory
------------------
-
-The docroot directory is a directory within each project directory from which the webserver will serve the files.
-
-By default this directory must be named ``htdocs``. This can be changed as well, but is outside
-the scope of this *getting started tutorial*.
-
-You can verifiy that the docroot directory is actually ``htdocs`` by checking your ``.env`` file:
-
-.. code-block:: bash
-
-   host> grep DOCROOT_DIR .env
-
-
-   HTTPD_DOCROOT_DIR=htdocs
-
-
-Domain suffix
--------------
-
-The default domain suffix (``TLD_SUFFIX`` variable in ``.env`` file) is ``loc``. That means that
-all your projects will be available under the following address: ``http://<project-directory>.loc``.
-This can be changed as well, but is outside the scope of this *getting started tutorial*.
-
-You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` file:
-
-.. code-block:: bash
-
-   host> grep ^TLD_SUFFIX .env
-
-   TLD_SUFFIX=loc
-
-
-Making sense of it
-------------------
-
-Ok, let's sum it up and make sense of the previously provided information. To better illustrate
-the behaviour we are going to use ``project-1`` as our project directory name.
-
-+---------------+---------------------------------+-------------------------------------------------------------+
-| Item          | Example                         | Description                                                 |
-+===============+=================================+=============================================================+
-| data dir      | ``./data/www``                  | Where all of your projects reside.                          |
-+---------------+---------------------------------+-------------------------------------------------------------+
-| project dir   | ``./data/www/project-1``        | A single project. It's name will be used to create the url. |
-+---------------+---------------------------------+-------------------------------------------------------------+
-| docroot dir   | ``./data/www/project-1/htdocs`` | Where the webserver looks for files within your project.    |
-+---------------+---------------------------------+-------------------------------------------------------------+
-| domain suffix | ``loc``                         | Suffix to build up your project url.                        |
-+---------------+---------------------------------+-------------------------------------------------------------+
-| project url   | ``http://project-1.loc``        | Final resulting project url.                                |
-+---------------+---------------------------------+-------------------------------------------------------------+
-
-**data dir**
-
-This directory is mounted into the ``httpd`` and ``php`` container, so that both know where all projects can be found. This is also the place where you create ``project directories`` for each of your projects.
-
-**project dir**
-
-Is your project and used to generate the virtual host together with the domain suffix.
-
-**docroot dir**
-
-A directory inside your ``project dir`` from where the webserver will actually serve your files.
-
-**domain suffix**
-
-Used as part of the project url.
-
-.. note::
-     The projcet directory will be discussed in more detail in :ref:`project_creation_workflow` below.
-
-
-.. _project_creation_workflow:
-
-Project creation workflow
-=========================
 
 Step 1: visit Intranet vhost page
----------------------------------
+=================================
 
 Before starting, have a look at the vhost page at http://localhost/vhosts.php
 
@@ -142,7 +26,7 @@ It should look like the screenshot below and will actually already provide the i
 
 
 Step 2: create a project directory
-----------------------------------
+==================================
 
 In your Devilbox git directory, navigate to ``./data/www`` and create a new directory.
 
@@ -169,11 +53,12 @@ Vist the vhost page again and see what has changed: http://localhost/vhosts.php
 
 By having created a project directory, the web server container has created a new virtual host. However it has noticed, that the actual document root directory does not yet exist and therefore it cannot serve any files yet.
 
+
 Step 3: create a docroot directory
-----------------------------------
+==================================
 
 .. note::
-     As desribed in :ref:`prerequisites` the docroot directory name must be ``htdocs`` for now.
+     As desribed in :ref:`getting_started_directory_overview_docroot` the docroot directory name must be ``htdocs`` for now.
 
 Navigate to your newly created project directory and create a directory named `htdocs` inside it.
 
@@ -201,8 +86,9 @@ The intranet already gives you the exact string that you can simply copy into yo
 .. important::
      This will only work on **native Docker** for Linux or MacOS. Read up on the next section to also find out how to do that on **Docker Toolbox** and Windows.
 
+
 Step 4: create a DNS entry
---------------------------
+==========================
 
 .. note::
      This step can also be automated via the bundled DNS server to automatically provide catch-all
@@ -210,7 +96,7 @@ Step 4: create a DNS entry
      *getting started tutorial*.
 
 Add DNS for Linux and MacOS (native Docker)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------------
 
 On Linux and MacOS (when using the native Docker), this step is fairly simple. The intranet provides
 you the exact string you need to paste into your ``/etc/hosts`` file on your host operating system.
@@ -224,7 +110,7 @@ you the exact string you need to paste into your ``/etc/hosts`` file on your hos
     127.0.0.1 project-1.loc
 
 Add DNS for Windows (native Docker)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------
 
 On Windows (when using the native Docker), you can also copy paste the command provided by the intranet,
 however the destination file is different. You have to add this string into: ``C:\Windows\System32\drivers\etc``.
@@ -236,7 +122,7 @@ Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add th
     127.0.0.1 project-1.loc
 
 Add DNS for Docker Toolbox
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
 
 When using ``Docker Toolbox`` the Devilbox runs inside a virtual machine and therefore the Webserver port (``80``)
 is not exposed to your host operating system. So your DNS record must point to the virtual machine instead of your
@@ -264,9 +150,8 @@ Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add th
 
     192.16.0.1 project-1.loc
 
-
 Back to intranet
-^^^^^^^^^^^^^^^^
+----------------
 
 Vist the vhost page again and see what has changed: http://localhost/vhosts.php
 
@@ -277,8 +162,9 @@ Vist the vhost page again and see what has changed: http://localhost/vhosts.php
 By having created the DNS record, the Devilbox intranet is aware that everything is setup now and
 gives you a link to your new project.
 
+
 Step 5: Visit your project
---------------------------
+==========================
 
 On the intranet, click on your project link. This will open your project in a new Browser tab or
 visit http://project-1.loc
@@ -291,8 +177,9 @@ Everything is setup now, however the webserver is trying to find a ``index.php``
 
 So all is left for you to do is to add your HTML or PHP files.
 
+
 Step 6: Create a hello world
-----------------------------
+============================
 
 Navigate to your docroot directory within your project and create a ``index.php`` file with some output.
 
@@ -321,8 +208,7 @@ Vist your project url again and see what has changed: http://project-1.loc
 Checklist
 =========
 
-1. :ref:`prerequisites` are read and understood
+1. Project directory is created
-2. Project directory is created
+2. Docroot directory is created
-3. Docroot directory is created
+3. DNS entry is added to the host operating system
-4. DNS entry is added to the host operating system
+4. PHP files are added to your docroot directory
-5. PHP files are added to your docroot directory

docs/getting-started/directory-overview.rst

@@ -0,0 +1,133 @@
+.. _getting_started_directory_overview:
+
+******************
+Directory overview
+******************
+
+.. important::
+     The directory overview only provides you some theoretical, but useful insights about how
+     it all works together. You should at least read it once to be able to debug any problems you
+     might encounter.
+
+If you have read it already, jump directly to :ref:`getting_started_create_your_first_project`
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+.. _getting_started_directory_overview_datadir:
+
+Data directory
+==============
+
+By default all your projects must be created in the ``./data/www/`` directory which is inside in
+your Devilbox git directory. This can be changed as well, but is outside the scope of this
+*getting started tutorial*.
+
+You can verifiy that the path is actually ``./data/www/`` by checking your ``.env`` file:
+
+.. code-block:: bash
+
+   host> grep HTTPD_DATADIR .env
+
+   HOST_PATH_HTTPD_DATADIR=./data/www
+
+
+Project directory
+=================
+
+The project directory is a directory directly within the data directory.
+
+**This represents one project.**
+
+By creating this directory, the web server will create a new virtual host for you. This
+happens fully automated and there is nothing else required to do except just to create a directory.
+
+The name of this directory will also be used to build up the final project url together with the
+domain suffix: ``http://<project directory>.<domain suffix>``
+
+Create as many project directories as you require.
+
+.. _getting_started_directory_overview_docroot:
+
+Docroot directory
+=================
+
+The docroot directory is a directory within each project directory from which the webserver will serve the files.
+
+By default this directory must be named ``htdocs``. This can be changed as well, but is outside
+the scope of this *getting started tutorial*.
+
+You can verifiy that the docroot directory is actually ``htdocs`` by checking your ``.env`` file:
+
+.. code-block:: bash
+
+   host> grep DOCROOT_DIR .env
+
+
+   HTTPD_DOCROOT_DIR=htdocs
+
+
+Domain suffix
+=============
+
+The default domain suffix (``TLD_SUFFIX`` variable in ``.env`` file) is ``loc``. That means that
+all your projects will be available under the following address: ``http://<project-directory>.loc``.
+This can be changed as well, but is outside the scope of this *getting started tutorial*.
+
+You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` file:
+
+.. code-block:: bash
+
+   host> grep ^TLD_SUFFIX .env
+
+   TLD_SUFFIX=loc
+
+
+Making sense of it
+==================
+
+Ok, let's sum it up and make sense of the previously provided information. To better illustrate
+the behaviour we are going to use ``project-1`` as our project directory name.
+
++---------------+---------------------------------+-------------------------------------------------------------+
+| Item          | Example                         | Description                                                 |
++===============+=================================+=============================================================+
+| data dir      | ``./data/www``                  | Where all of your projects reside.                          |
++---------------+---------------------------------+-------------------------------------------------------------+
+| project dir   | ``./data/www/project-1``        | A single project. It's name will be used to create the url. |
++---------------+---------------------------------+-------------------------------------------------------------+
+| docroot dir   | ``./data/www/project-1/htdocs`` | Where the webserver looks for files within your project.    |
++---------------+---------------------------------+-------------------------------------------------------------+
+| domain suffix | ``loc``                         | Suffix to build up your project url.                        |
++---------------+---------------------------------+-------------------------------------------------------------+
+| project url   | ``http://project-1.loc``        | Final resulting project url.                                |
++---------------+---------------------------------+-------------------------------------------------------------+
+
+**data dir**
+
+This directory is mounted into the ``httpd`` and ``php`` container, so that both know where all projects can be found. This is also the place where you create ``project directories`` for each of your projects.
+
+**project dir**
+
+Is your project and used to generate the virtual host together with the domain suffix.
+
+**docroot dir**
+
+A directory inside your ``project dir`` from where the webserver will actually serve your files.
+
+**domain suffix**
+
+Used as part of the project url.
+
+
+Checklist
+=========
+
+1. You know what the data directory is
+2. You know what the project directory is
+3. You know what the docroot directory is
+4. You know what the domain suffix is
+5. You know how domains are constructed

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

@@ -7,6 +7,11 @@ Install the Devilbox
      Ensure you have read this document to understand how this documentation works.
 
 
+**Table of Contents**
+
+.. contents:: :local:
+
+
 Supported OS
 ============
 

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

@@ -16,6 +16,11 @@ hands dirty.
      `stop <https://docs.docker.com/compose/reference/stop/>`_ commands.
 
 
+**Table of Contents**
+
+.. contents:: :local:
+
+
 Start all container
 ===================
 

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

@@ -5,6 +5,12 @@ Update the Devilbox
 If you are in the initial install process, you can safely skip this section and come back once
 you actually want to update the Devilbox.
 
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
 Update git repository
 =====================
 

docs/index.rst

@@ -23,6 +23,7 @@ devilbox documentation
    getting-started/install-the-devilbox
    getting-started/update-the-devilbox
    getting-started/start-the-devilbox
+   getting-started/directory-overview
    getting-started/create-your-first-project