Documentation: more detailed examples

.gitignore

@@ -82,6 +82,7 @@ docker-compose.override.yml
 # Ignore documentation sphinx build
 /docs/_build/
 /docs/make.bat
+/docs/linkcheck
 *.rst.todo
 
 # Keep folders

docs/Makefile

@@ -49,7 +49,13 @@ help:
 
 
 linkcheck2:
-	./linkcheck.sh -r 10 -t 10 -e rst _includes/
+ifeq ($(wildcard file1),)
+	bash -c 'curl -Ss -o linkcheck https://raw.githubusercontent.com/cytopia/linkcheck/master/linkcheck 2>/dev/null'
+else
+	bash -c 'curl -Ss -o linkcheck -z linkcheck https://raw.githubusercontent.com/cytopia/linkcheck/master/linkcheck 2>/dev/null'
+endif
+	chmod +x linkcheck
+	./linkcheck -r 30 -t 30 -e rst _includes/
 
 build:
 	sphinx-build -a -E -n -j auto -q -W . _build/html

docs/_includes/links/tools.rst

@@ -132,7 +132,7 @@
 .. |ext_lnk_tool_npm| raw:: html
 
    <a target="_blank" href="https://www.npmjs.com">
-     Node <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+     NPM <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
    </a>
 
 .. |ext_lnk_tool_phalcon| raw:: html
@@ -231,6 +231,12 @@
      Yarn <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
    </a>
 
+.. |ext_lnk_tool_github_issues| raw:: html
+
+   <a target="_blank" href="https://github.com/cytopia/devilbox/issues">
+     Github <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>
+
 
 ..
    ============================================================

docs/examples/setup-cakephp.rst

@@ -6,7 +6,10 @@
 Setup CakePHP
 *************
 
-This example will use ``composer`` to install CakePHP from within the PHP container.
+This example will use ``composer`` to install CakePHP from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working CakePHP setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_cakephp_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                 |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=============================================+
-| my-cake      | /shared/httpd/my-cake    | my_cake     | loc        | http://my-cake.loc    |
+| my-cake      | /shared/httpd/my-cake    | my_cake     | loc        | http://my-cake.loc |br| https://my-cake.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -43,43 +51,89 @@ It will be ready in eight simple steps:
 8. Visit http://my-cake.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-cake
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install CakePHP
 ------------------
 
+Navigate into your newly created vhost directory and install CakePHP with ``composer``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-cake
    devilbox@php-7.0.20 in /shared/httpd/my-cake $ composer create-project --prefer-dist cakephp/app cakephp
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-cake $ tree -L 1
+   .
+   └── cakephp
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-cake $ ln -s cakephp/webroot/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-cake $ tree -L 1
+   .
+   ├── cakephp
+   └── htdocs -> cakephp/webroot
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. Add MySQL Database
 ---------------------
@@ -126,9 +180,11 @@ It will be ready in eight simple steps:
 7. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -145,4 +201,6 @@ following line to your host operating systems ``/etc/hosts`` file
 8. Open your browser
 --------------------
 
-All set now, you can visit http://my-cake.loc in your browser.
+All set now, you can visit http://my-cake.loc or https://my-cake.loc in your browser.
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-codeigniter.rst

@@ -6,6 +6,11 @@
 Setup CodeIgniter
 *****************
 
+This example will use ``wget`` to install CodeIgniter from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working CodeIgniter setup ready to be
+served via http and https.
+
 .. seealso:: |ext_lnk_example_codeignitor_documentation|
 
 
@@ -19,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-----------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                             |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=========================================+
-| my-ci        | /shared/httpd/my-ci      | my_ci       | loc        | http://my-ci.loc      |
+| my-ci        | /shared/httpd/my-ci      | my_ci       | loc        | http://my-ci.loc |br| https://my-ci.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-----------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,48 +51,92 @@ It will be ready in eight simple steps:
 8. Visit http://my-ci.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-ci
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Download CodeIgniter
 -----------------------
 
+Navigate into your newly created vhost directory and install CodeIgniter.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-ci
    devilbox@php-7.0.20 in /shared/httpd/my-ci $ wget https://github.com/bcit-ci/CodeIgniter/archive/3.1.8.tar.gz
    devilbox@php-7.0.20 in /shared/httpd/my-ci $ tar xfvz 3.1.8.tar.gz
-   devilbox@php-7.0.20 in /shared/httpd/my-ci $ ls -l
+
-   total 7488
+How does the directory structure look after installation:
-   drwxr-xr-x 5 devilbox devilbox    4096 Mar 22 15:48 CodeIgniter-3.1.8/
+
-   -rw-r--r-- 1 devilbox devilbox 2205672 May 21 10:42 3.1.8.tar.gz
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-ci $ tree -L 1
+   .
+   ├── 3.1.8.tar.gz
+   └── CodeIgniter-3.1.8
+
+   1 directory, 1 file
 
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-ci $ ln -s CodeIgniter-3.1.8/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-ci $ tree -L 1
+   .
+   ├── 3.1.8.tar.gz
+   ├── CodeIgniter-3.1.8
+   └── htdocs -> CodeIgniter-3.1.8
+
+   2 directories, 1 file
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. Add MySQL Database
 ---------------------
@@ -130,9 +184,11 @@ It will be ready in eight simple steps:
 7. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -149,4 +205,6 @@ following line to your host operating systems ``/etc/hosts`` file
 8. Open your browser
 --------------------
 
-All set now, you can visit http://my-ci.loc in your browser.
+All set now, you can visit http://my-ci.loc or https://my-ci.loc in your browser.
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-drupal.rst

@@ -6,7 +6,10 @@
 Setup Drupal
 ************
 
-This example will use ``drush`` to install Drupal from within the PHP container.
+This example will use ``drush`` to install Drupal from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Drupal setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_drupal_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                     |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=================================================+
-| my-drupal    | /shared/httpd/my-drupal  | my_drupal   | loc        | http://my-drupal.loc  |
+| my-drupal    | /shared/httpd/my-drupal  | my_drupal   | loc        | http://my-drupal.loc |br| https://my-drupal.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,50 +49,98 @@ It will be ready in six simple steps:
 6. Visit http://my-drupal.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-drupal
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Drupal
 -----------------
 
+Navigate into your newly created vhost directory and install Drupal with ``drush``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-drupal
    devilbox@php-7.0.20 in /shared/httpd/my-drupal $ drush dl drupal
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-drupal $ tree -L 1
+   .
+   └── drupal-8.3.3
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-drupal $ ln -s drupal-8.3.3/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-drupal $ tree -L 1
+   .
+   ├── drupal-8.3.3
+   └── htdocs -> CodeIgniter-3.1.8
+
+   2 directories, 0 fils
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -101,7 +157,10 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-drupal.loc and follow the Drupal installation steps.
+Open your browser at http://my-drupal.loc or https://my-drupal.loc and follow the Drupal
+installation steps.
 
 .. note::
    When asked about MySQL hostname, choose ``127.0.0.1``.
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-joomla.rst

@@ -6,7 +6,10 @@
 Setup Joomla
 ************
 
-This example will install Joomla from within the PHP container.
+This example will use ``wget`` to install Joomla from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Joomla setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_joomla_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                     |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=================================================+
-| my-joomla    | /shared/httpd/my-joomla  | n.a.        | loc        | http://my-joomla.loc  |
+| my-joomla    | /shared/httpd/my-joomla  | n.a.        | loc        | http://my-joomla.loc |br| https://my-joomla.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,52 +49,101 @@ It will be ready in six simple steps:
 6. Visit http://my-joomla.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-joomla
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Download and extract Joomla
 ------------------------------
 
+Navigate into your newly created vhost directory and install Joomla.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-joomla
    devilbox@php-7.0.20 in /shared/httpd/my-joomla $ wget -O joomla.tar.gz https://downloads.joomla.org/cms/joomla3/3-8-0/joomla_3-8-0-stable-full_package-tar-gz?format=gz
-   devilbox@php-7.0.20 in /shared/httpd $ mkdir joomla
+   devilbox@php-7.0.20 in /shared/httpd/my-joomla $ mkdir joomla
-   devilbox@php-7.0.20 in /shared/httpd $ tar xvfz joomla.tar.gz -C joomla/
+   devilbox@php-7.0.20 in /shared/httpd/my-joomla $ tar xvfz joomla.tar.gz -C joomla/
+
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-joomla $ tree -L 1
+   .
+   ├── joomla.tar.gz
+   └── joomla
+
+   1 directory, 1 file
 
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-joomla $ ln -s joomla/ htdocs
 
+How does the directory structure look after symlinking it:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-joomla $ tree -L 1
+   .
+   ├── joomla.tar.gz
+   ├── joomla
+   └── htdocs -> joomla
+
+   2 directories, 1 file
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
+be available automatically by the bundled DNS server.
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **don't have** Auto DNS configured, you will need to add the following line to your
-following line to your host operating systems ``/etc/hosts`` file
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -103,4 +160,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-joomla.loc
+All set now, you can visit http://my-joomla.loc or https://my-joomla.loc in your browser.
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-laravel.rst

@@ -6,7 +6,10 @@
 Setup Laravel
 *************
 
-This example will use ``laravel`` to install Laravel from within the PHP container.
+This example will use ``laravel`` to install Laravel from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_laravel_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                       |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+===================================================+
-| my-laravel   | /shared/httpd/my-laravel | n.a.        | loc        | http://my-laravel.loc |
+| my-laravel   | /shared/httpd/my-laravel | n.a.        | loc        | http://my-laravel.loc |br| https://my-laravel.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,56 +49,109 @@ It will be ready in six simple steps:
 6. Visit http://my-laravel.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-laravel
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Laravel
 ------------------
 
+Navigate into your newly created vhost directory and install Laravel with ``laravel`` cli.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-laravel
    devilbox@php-7.0.20 in /shared/httpd/my-laravel $ laravel new laravel-project
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-laravel $ tree -L 1
+   .
+   └── laravel-project
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-laravel $ ln -s laravel-project/public/ htdocs
 
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-laravel $ tree -L 1
+   .
+   ├── laravel-project
+   └── htdocs -> laravel-project/public
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
+
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
 
    127.0.0.1 my-laravel.loc
 
+This will ensure that your host operating system's browser will direct any calls on
+``http://my-laravel.loc`` or ``https://my-laravel.loc`` to the Devilbox which is listening on
+``127.0.0.1``.
+
 .. seealso::
 
    * :ref:`howto_add_project_hosts_entry_on_mac`
@@ -101,4 +162,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-laravel.loc
+Open your browser at http://my-laravel.loc or https://my-laravel.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-phalcon.rst

@@ -6,7 +6,10 @@
 Setup Phalcon
 *************
 
-This example will use ``phalcon`` to install Phalcon from within the PHP container.
+This example will use ``phalcon`` to install Phalcon from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_phalcon_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                       |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+===================================================+
-| my-phalcon   | /shared/httpd/my-phalcon | n.a.        | loc        | http://my-phalcon.loc |
+| my-phalcon   | /shared/httpd/my-phalcon | n.a.        | loc        | http://my-phalcon.loc |br| https://my-phalcon.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,50 +49,98 @@ It will be ready in six simple steps:
 6. Visit http://my-phalcon.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-phalcon
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Phalcon
 ------------------
 
+Navigate into your newly created vhost directory and install Phalcon with ``phalcon`` cli.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-phalcon
    devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ phalcon project phalconphp
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ tree -L 1
+   .
+   └── phalconphp
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ ln -s phalconphp/public/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ tree -L 1
+   .
+   ├── phalconphp
+   └── htdocs -> phalconphp/public
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -101,4 +157,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-phalcon.loc
+Open your browser at http://my-phalcon.loc or https://my-phalcon.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-photon-cms.rst

@@ -6,7 +6,10 @@
 Setup Photon CMS
 ****************
 
-This example will use ``photon`` cli to install Photon CMS from within the PHP container.
+This example will use ``photon`` cli to install Photon CMS from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_photon_cms|
 
@@ -21,13 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                     |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=================================================+
-| my-photon    | /shared/httpd/my-photon  | blog        | loc        | http://my-photon.loc  |
+| my-photon    | /shared/httpd/my-photon  | blog        | loc        | http://my-photon.loc |br| https://my-photon.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------------+
 
-.. note:: The database is created automatically by ``photon`` cli.
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -43,34 +49,48 @@ It will be ready in six simple steps:
 6. Visit http://my-photon.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-photon
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Photon
 ------------------
 
-During the installation you will be asked for the MySQL hostname, username and password. Ensure
+Navigate into your newly created vhost directory and install Photom CMS with ``photon`` cli.
-not to specify ``localhost``, but instead use ``127.0.0.1`` for the hostname.
+
-Additionally, provide a pair of credentials that has permissions to create a database or create the database
+.. note::
-itself beforehand.
+   During the installation you will be asked for the MySQL hostname, username and password. Ensure
+   not to specify ``localhost``, but instead use ``127.0.0.1`` for the hostname.
+   Additionally, provide a pair of credentials that has permissions to create a database or create the database
+   itself beforehand.
 
 .. code-block:: bash
 
@@ -80,21 +100,56 @@ itself beforehand.
    ...What is your mysql username? [root]root
    ...What is your mysql password? []
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-photon $ tree -L 1
+   .
+   └── blog
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-photon $ ln -s blog/public/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-photon $ tree -L 1
+   .
+   ├── blog
+   └── htdocs -> blog/public
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -111,4 +166,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-photon.loc
+Open your browser at http://my-photon.loc or https://my-photon.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-shopware.rst

@@ -6,7 +6,10 @@
 Setup Shopware
 **************
 
-This example will use ``git`` to install Shopware from within the PHP container.
+This example will use ``git`` to install Shopware from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso::
    * |ext_lnk_example_shopware_documentation|
@@ -23,11 +26,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-----------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                             |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=========================================+
-| my-sw        | /shared/httpd/my-sw      | my_sw       | loc        | http://my-sw.loc      |
+| my-sw        | /shared/httpd/my-sw      | my_sw       | loc        | http://my-sw.loc |br| https://my-sw.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-----------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -44,43 +52,89 @@ It will be ready in seven simple steps:
 7. Follow installation steps in http://my-sw.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-sw
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Download Shopware
 --------------------
 
+Navigate into your newly created vhost directory and install Shopware with ``git``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-sw
    devilbox@php-7.0.20 in /shared/httpd/my-sw $ git clone https://github.com/shopware/shopware
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-sw $ tree -L 1
+   .
+   └── shopware
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-sw $ ln -s shopware/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-sw $ tree -L 1
+   .
+   ├── shopware
+   └── htdocs -> shopware
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. Add MySQL Database
 ---------------------
@@ -93,9 +147,11 @@ It will be ready in seven simple steps:
 6. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -112,8 +168,8 @@ following line to your host operating systems ``/etc/hosts`` file
 7. Follow install steps in your browser
 ---------------------------------------
 
-All set now, you can visit http://my-sw.loc in your browser and follow the installation steps as
+All set now, you can visit http://my-sw.loc or https://my-sw.loc in your browser and follow the
-described in the |ext_lnk_example_shopware_documentation|:
+installation steps as described in the |ext_lnk_example_shopware_documentation|:
 
 .. important::
    When setting up database connection use the following values:
@@ -123,6 +179,8 @@ described in the |ext_lnk_example_shopware_documentation|:
    * Database pass: by default the root password is empty
    * Database name: ``my_sw``
 
+.. seealso:: :ref:`setup_valid_https`
+
 
 Encountered problems
 ====================

docs/examples/setup-symfony.rst

@@ -6,7 +6,10 @@
 Setup Symfony
 *************
 
-This example will use ``symfony`` to install Symfony from within the PHP container.
+This example will use ``symfony`` to install Symfony from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_symfony_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                       |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+===================================================+
-| my-symfony   | /shared/httpd/my-symfony | n.a.        | loc        | http://my-symfony.loc |
+| my-symfony   | /shared/httpd/my-symfony | n.a.        | loc        | http://my-symfony.loc |br| https://my-symfony.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -42,43 +50,89 @@ It will be ready in seven simple steps:
 7. Visit http://my-symfony.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-symfony
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Symfony
 ------------------
 
+Navigate into your newly created vhost directory and install Symfony with ``symfony`` cli.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-symfony
    devilbox@php-7.0.20 in /shared/httpd/my-symfony $ symfony new symfony
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-symfony $ tree -L 1
+   .
+   └── symfony
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-symfony $ ln -s symfony/web/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-sw $ tree -L 1
+   .
+   ├── symfony
+   └── htdocs -> symfony/web
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. Enable Symfony prod (``app.php``)
 ------------------------------------
@@ -92,9 +146,11 @@ It will be ready in seven simple steps:
 6. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -111,4 +167,6 @@ following line to your host operating systems ``/etc/hosts`` file
 7. Open your browser
 --------------------
 
-Open your browser at http://my-symfony.loc
+Open your browser at http://my-symfony.loc or https://my-symfony.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-typo3.rst

@@ -6,7 +6,10 @@
 Setup Typo3
 ***********
 
-This example will use ``composer`` to install Typo3 from within the PHP container.
+This example will use ``composer`` to install Typo3 from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_typo3_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                 |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=============================================+
-| my-typo      | /shared/httpd/my-typo    | my_typo     | loc        | http://my-typo.loc    |
+| my-typo      | /shared/httpd/my-typo    | my_typo     | loc        | http://my-typo.loc |br| https://my-typo.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -43,50 +51,98 @@ It will be ready in eight simple steps:
 8. Step through guided web installation
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-typo
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Typo3
 ----------------
 
+Navigate into your newly created vhost directory and install Typo3 with ``composer``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-typo
    devilbox@php-7.0.20 in /shared/httpd/my-typo $ composer create-project typo3/cms-base-distribution typo3
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-typo $ tree -L 1
+   .
+   └── typo3
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-typo $ ln -s typo3/public htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-typo $ tree -L 1
+   .
+   ├── typo3
+   └── htdocs -> typo3/public
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -114,7 +170,9 @@ To continue installing via the guided web install, you need to create a file cal
 7. Open your browser
 --------------------
 
-Open your browser at http://my-typo.loc.
+Open your browser at http://my-typo.loc or https://my-typo.loc.
+
+.. seealso:: :ref:`setup_valid_https`
 
 
 8. Step through guided web installation

docs/examples/setup-wordpress.rst

@@ -6,7 +6,10 @@
 Setup Wordpress
 ***************
 
-This example will use ``git`` to install Wordpress from within the PHP container.
+This example will use ``git`` to install Wordpress from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_wordpress_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-----------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                             |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=========================================+
-| my-wp        | /shared/httpd/my-wp      | my_wp       | loc        | http://my-wp.loc      |
+| my-wp        | /shared/httpd/my-wp      | my_wp       | loc        | http://my-wp.loc |br| https://my-wp.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-----------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,50 +49,98 @@ It will be ready in six simple steps:
 6. Visit http://my-wp.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-wp
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Download Wordpress via ``git``
 ---------------------------------
 
+Navigate into your newly created vhost directory and install Wordpress with ``git``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-wp
    devilbox@php-7.0.20 in /shared/httpd/my-wp $ git clone https://github.com/WordPress/WordPress wordpress.git
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-wp $ tree -L 1
+   .
+   └── wordpress.git
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-wp $ ln -s wordpress.git/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-wp $ tree -L 1
+   .
+   ├── wordpress.git
+   └── htdocs -> wordpress.git
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -101,4 +157,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-wp.loc
+Open your browser at http://my-wp.loc or https://my-wp.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-yii.rst

@@ -6,7 +6,10 @@
 Setup Yii
 *********
 
-This example will use ``composer`` to install Yii from within the PHP container.
+This example will use ``composer`` to install Yii from within the Devilbox PHP container.
+
+After completing the below listed steps, you will have a working Laravel setup ready to be
+served via http and https.
 
 .. seealso:: |ext_lnk_example_yii_documentation|
 
@@ -21,11 +24,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                               |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+===========================================+
-| my-yii       | /shared/httpd/my-yii     | n.a.        | loc        | http://my-yii.loc     |
+| my-yii       | /shared/httpd/my-yii     | n.a.        | loc        | http://my-yii.loc |br| https://my-yii.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+-------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,50 +49,98 @@ It will be ready in six simple steps:
 6. Visit http://my-wp.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-yii
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Yii2 via ``composer``
 --------------------------------
 
+Navigate into your newly created vhost directory and install Yii2 with ``composer``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-yii
    devilbox@php-7.0.20 in /shared/httpd/my-yii $ composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic yii2-dev
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-yii $ tree -L 1
+   .
+   └── yii2-dev
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-yii $ ln -s yii2-dev/web/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-yii $ tree -L 1
+   .
+   ├── yii2-dev
+   └── htdocs -> yii2-dev/web
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -101,4 +157,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-yii.loc
+Open your browser at http://my-yii.loc or https://my-yii.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/examples/setup-zend.rst

@@ -21,11 +21,16 @@ Overview
 
 The following configuration will be used:
 
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
-| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL           |
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                 |
-+==============+==========================+=============+============+=======================+
++==============+==========================+=============+============+=============================================+
-| my-zend      | /shared/httpd/my-zend    | n.a.        | loc        | http://my-zend.loc    |
+| my-zend      | /shared/httpd/my-zend    | n.a.        | loc        | http://my-zend.loc |br| https://my-zend.loc |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
 
 
 Walk through
@@ -41,50 +46,98 @@ It will be ready in six simple steps:
 6. Visit http://my-wp.loc in your browser
 
 
-.. seealso:: :ref:`available_tools`
-
-
 1. Enter the PHP container
 --------------------------
 
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
 .. code-block:: bash
 
    host> ./shell.sh
 
-.. seealso:: :ref:`work_inside_the_php_container`
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
 
 
 2. Create new vhost directory
 -----------------------------
 
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ mkdir my-zend
 
+.. seealso:: :ref:`env_tld_suffix`
+
 
 3. Install Zend via ``composer``
 --------------------------------
 
+Navigate into your newly created vhost directory and install Zend with ``composer``.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd $ cd my-zend
    devilbox@php-7.0.20 in /shared/httpd/my-zend $ composer create-project --prefer-dist zendframework/skeleton-application zend
 
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-zend $ tree -L 1
+   .
+   └── zend
+
+   1 directory, 0 files
+
 
 4. Symlink webroot
 ------------------
 
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
 .. code-block:: bash
 
    devilbox@php-7.0.20 in /shared/httpd/my-zend $ ln -s zend/public/ htdocs
 
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-zend $ tree -L 1
+   .
+   ├── zend
+   └── htdocs -> zend/public
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
 
 5. DNS record
 -------------
 
-If you do not have :ref:`setup_auto_dns` configured, you will need to add the
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
-following line to your host operating systems ``/etc/hosts`` file
+be available automatically by the bundled DNS server.
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
 
 .. code-block:: bash
    :caption: /etc/hosts
@@ -101,4 +154,6 @@ following line to your host operating systems ``/etc/hosts`` file
 6. Open your browser
 --------------------
 
-Open your browser at http://my-zend.loc
+Open your browser at http://my-zend.loc or https://my-zend.loc
+
+.. seealso:: :ref:`setup_valid_https`

docs/getting-started/enter-the-php-container.rst

@@ -1,3 +1,5 @@
+.. _enter_the_php_container:
+
 ***********************
 Enter the PHP container
 ***********************

docs/linkcheck.sh

@@ -1,307 +0,0 @@
-#!/usr/bin/env bash
-
-# Bestrict
-set -e
-set -u
-set -o pipefail
-
-
-############################################################
-# Overwritable global variables
-############################################################
-
-
-###
-### In what path to look for files
-###
-SEARCH_PATH="."
-
-
-###
-### Comma separated list of file extensions to scan for urls
-###
-EXTENSIONS=""
-
-
-###
-### Regex to exclude URLs from being tested
-###
-URL_REGEX_EXCLUDE="^http(s)?:\/\/(127\.0\.0\.1)|(localhost)|(.+\.loc).*$"
-
-
-###
-### Timeout in seconds to see if a site is alive
-###
-TIMEOUT=10
-
-
-###
-### How many times to probe one URL to see if it is alive
-###
-RETRIES=3
-
-
-###
-### Comma separated list of acceptable http status codes
-### to define that the URL is alive
-###
-STATUS_CODES=200
-
-
-
-############################################################
-# Functions
-############################################################
-
-###
-### Usage
-###
-print_usage() {
-	echo "Usage: linkcheck [-e -i -t -r -c] [<path>]"
-	echo "       linkcheck --version"
-	echo "       linkcheck --help"
-	echo
-	echo
-	echo "Options:"
-	echo
-	echo "-e        Limit search to those file extensions."
-	echo "          Defaults to limiting on non-binary files."
-	echo "          Accepts comma separated string of extensions:"
-	echo "            -e txt"
-	echo "            -e txt,rst"
-	echo "            -e sh,py.c,h"
-	echo
-	echo "-i        Ignore all URLs matching the specified regex."
-	echo '          Defaults to: ^http(s)?:\/\/(127\.0\.0\.1)|(localhost)|(.+\.loc).*$'
-	echo "          Accepts a single regex string:"
-	echo "            -i '^http(?):\/\/my-comapny.com.*$'"
-	echo
-	echo "-t        Specify curl timeout in seconds, after which probing stops for one url."
-	echo "          Defaults to 10 seconds."
-	echo "          Accepts a positive integer:"
-	echo "            -t 5"
-	echo "            -t 10"
-	echo
-	echo "-r        Specify how many time to retry probing a single URL, before giving up."
-	echo "          Defaults to 3 times."
-	echo "          Accepts a positive integer:"
-	echo "            -r 5"
-	echo "            -r 10"
-	echo
-	echo "-c        Specify HTTP status codes that are valid for success."
-	echo "          Any code not specified in here will produce an error for the given URL."
-	echo "          Defaults to '200'."
-	echo "          Accepts comma separated string of http status codes:"
-	echo "            -c '200'"
-	echo "            -c '200,301'"
-	echo "            -c '200,301,302'"
-	echo
-	echo
-	echo "--version Show version and exit."
-	echo "--help    Show this help screen."
-	echo
-	echo
-	echo "Optional arguments:"
-	echo
-	echo "<path>    Specify what directory to scan files for URLs."
-	echo "          Defaults to current directory."
-	echo
-	echo
-}
-
-
-###
-### Version
-###
-print_version() {
-	echo "linkcheck v0.1 by cytopia"
-	echo "https://github.com/cytopia/linkcheck"
-}
-
-
-###
-### Set value (used to store stdout and stderr in two different variables)
-###
-setval() {
-	printf -v "$1" "%s" "$(cat)";
-	declare -p "$1";
-}
-
-
-###
-### Gather URLs from files
-###
-gather_urls() {
-	local path="${1}"
-	local extensions="${2}"
-	local reg_exclude="${3}"
-
-	local url_regex="http(s)?:\/\/[-=?:,._/#0-9a-zA-Z]+"
-	local find_ext=
-	local find_cmd=
-
-	if [ -n "${extensions}" ]; then
-		find_ext="\( -iname \*.${extensions//,/ -o -iname \\*.} \)"
-	fi
-
-	find_cmd="find ${path} ${find_ext} -type f -exec grep --binary-files=without-match -Eo '${url_regex}' '{}' \;"
-	>&2 echo "\$ ${find_cmd}"
-
-	# Loop through uniqued URLs
-	for url in $(eval "${find_cmd}" 2>/dev/null | sort -u); do
-		# Ignore any 'Binary file...' results
-		if echo "${url}" | grep -Eq '^htt'; then
-			# Remove any trailing: [,.]
-			url="$( echo "${url}" | sed 's/[,.]$//g')"
-
-			# Ignore URLs excluded by regex
-			if ! echo "${url}" | grep -qE "${reg_exclude}"; then
-				echo "${url}"
-			fi
-		fi
-	done
-}
-
-
-###
-### Probe URLs for availability
-###
-probe_urls() {
-	local urls="${1}"
-	local timeout="${2}"
-	local retries="${3}"
-	local status_codes="${4}"
-	local ret_code=0
-
-	status_codes="${status_codes//,/|}"          # comma to |
-	status_codes="${status_codes//[[:space:]]/}" # remove whitespace
-
-	for url in ${urls}; do
-
-		# Try to curl multiple times in case host is currently not reachable
-		i=0; fail=0
-		eval "$( curl -SsI --connect-timeout "${timeout}" "${url}" 2> >(setval errval) > >(setval header); <<<"$?" setval retval;  )"
-		while [ "${retval}" != "0" ] ; do
-			i=$(( i + 1 ))
-			sleep 2
-			if [ "${i}" -ge "${retries}" ]; then
-				fail=1
-				break;
-			fi
-		done
-
-		# Curl request failed
-		if [ "${fail}" = "1" ]; then
-			printf "\e[0;31m[FAIL]\e[0m %s %s\n" "${url}" "${errval}"
-
-		# Curl request succeeded
-		else
-			line="$( echo "${header}" | grep -E '^HTTP/(1|2)' )"
-			stat="$( echo "${line}" | awk '{print $2}' )"
-
-			#if [ "${stat}" != "200" ]; then
-			if ! echo "${stat}" | grep -qE "${status_codes}"; then
-				printf "\e[0;31m[ERR]\e[0m  %s %s\n" "${url}" "${line}"
-				ret_code=1
-			else
-				printf "\e[0;32m[OK]\e[0m   %s %s\n" "${url}" "${line}"
-			fi
-		fi
-	done
-	return ${ret_code}
-}
-
-
-############################################################
-# Entrypoint: arguments
-############################################################
-#-e -i -t -r -c
-while [ $# -gt 0  ]; do
-	case "${1}" in
-
-		# ----------------------------------------
-		-e)
-			shift
-			if [ "${#}" -gt "0" ]; then
-				EXTENSIONS="${1}"
-			else
-				>&2 echo "Error, -e requires an argument."
-				exit 1
-			fi
-			;;
-
-		# ----------------------------------------
-		-i)
-			shift
-			if [ "${#}" -gt "0" ]; then
-				URL_REGEX_EXCLUDE="${1}"
-			else
-				>&2 echo "Error, -i requires an argument."
-				exit 1
-			fi
-			;;
-
-		# ----------------------------------------
-		-t)
-			shift
-			if [ "${#}" -gt "0" ]; then
-				TIMEOUT="${1}"
-			else
-				>&2 echo "Error, -t requires an argument."
-				exit 1
-			fi
-			;;
-
-		# ----------------------------------------
-		-r)
-			shift
-			if [ "${#}" -gt "0" ]; then
-				RETRIES="${1}"
-			else
-				>&2 echo "Error, -r requires an argument."
-				exit 1
-			fi
-			;;
-		# ----------------------------------------
-		-c)
-			shift
-			if [ "${#}" -gt "0" ]; then
-				STATUS_CODES="${1}"
-			else
-				>&2 echo "Error, -c requires an argument."
-				exit 1
-			fi
-			;;
-
-		# ----------------------------------------
-		--help)
-			print_usage
-			exit 0
-			;;
-
-		# ----------------------------------------
-		--version)
-			print_version
-			exit 0
-			;;
-
-		# ----------------------------------------
-		*)
-			# If it is the last argument, its the path
-			if [ "${#}" = "1" ]; then
-				SEARCH_PATH="${1}"
-			else
-				echo "Invalid argument: ${1}"
-				echo "Type 'linkcheck --help' for available options."
-				exit 1
-			fi
-			;;
-	esac
-	shift
-done
-
-
-
-MY_URLS="$( gather_urls "${SEARCH_PATH}" "${EXTENSIONS}" "${URL_REGEX_EXCLUDE}" )"
-
-probe_urls "${MY_URLS}" "${TIMEOUT}" "${RETRIES}" "${STATUS_CODES}"

docs/readings/available-tools.rst

@@ -16,10 +16,10 @@ The PHP container is your workhorse and these are your tools:
 +----------------------+---------------------------------------+
 | Binary               | Tool                                  |
 +======================+=======================================+
-| various binaries     | |ext_lnk_tool_awesome_ci|             |
-+----------------------+---------------------------------------+
 | ``ansible``          | |ext_lnk_tool_ansible|                |
 +----------------------+---------------------------------------+
+| various binaries     | |ext_lnk_tool_awesome_ci|             |
++----------------------+---------------------------------------+
 | ``brew``             | |ext_lnk_tool_linuxbrew|              |
 +----------------------+---------------------------------------+
 | ``codecept``         | |ext_lnk_tool_codecept|               |
@@ -92,9 +92,8 @@ The PHP container is your workhorse and these are your tools:
 +----------------------+---------------------------------------+
 
 .. note::
-   If you are in need of other tools, open up an issue at
+   If you are in need of other tools, open up an issue at |ext_lnk_tool_github_issues|
-   `Github <https://github.com/cytopia/devilbox/issues>`_ and ask for it,
+   and ask for it, this can usually be implemented very quickly.
-   this can usually be implemented very quickly.
 
 .. seealso::
    If you ever feel those tools are out-dated, simply update your Docker images.