Documentation: more detailed examples

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           |
-+==============+==========================+=============+============+=======================+
-| my-cake      | /shared/httpd/my-cake    | my_cake     | loc        | http://my-cake.loc    |
-+--------------+--------------------------+-------------+------------+-----------------------+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                 |
++==============+==========================+=============+============+=============================================+
+| 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
-following line to your host operating systems ``/etc/hosts`` file
-(or ``C:\Windows\System32\drivers\etc`` on Windows):
+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 **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`