Finalize getting-started-guide

docs/about/read-first.rst

@@ -0,0 +1,21 @@
+.. _read_first:
+
+**********
+Read first
+**********
+
+.. important::
+
+   All shell commands in this documentation use two different formats:
+
+   1. This one indicates that the command should be executed on your host operating system. (When copying commands, do not copy the ``host>`` part).
+
+   .. code-block:: bash
+
+       host> command
+
+   2. This one indicates that the command should be executed inside the currently selected PHP container.  (When copying commands, do not copy the ``php>`` part).
+
+   .. code-block:: bash
+
+       php> command

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

@@ -1,3 +1,310 @@
 *************************
 Create your first project
 *************************
+
+.. note::
+
+     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
+=============
+
+.. important::
+     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
+
+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
+
+
+Make sense of it
+----------------
+
+Ok, let's sum it up and make sense of the previously provided information:
+
++---------------+---------------------------------+
+| Item          | Example                         |
++===============+=================================+
+| data dir      | ``./data/www``                  |
++---------------+---------------------------------+
+| project dir   | ``./data/www/project-1``        |
++---------------+---------------------------------+
+| docroot dir   | ``./data/www/project-1/htdocs`` |
++---------------+---------------------------------+
+| domain suffix | ``loc``                         |
++---------------+---------------------------------+
+| project url   | ``http://project-1.loc``        |
++---------------+---------------------------------+
+
+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`` in for each of your projects.
+
+project dir
+^^^^^^^^^^^
+
+A directory created in ``data dir``. This represents one project. By creating this directory, the `httpd` container automatically create a new VirtualHost that is ready to serve.
+
+The `httpd` container also uses the name of the ``data dir`` and the ``domain suffix`` to create the final url for the project.
+
+.. note::
+     The projcet directory will be discussed in more detail in :ref:`project_creation_workflow` below.
+
+
+docroot dir
+^^^^^^^^^^^
+
+A directory inside your ``project dir`` from where the webserver will actually serve your files.
+
+.. _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
+
+It should look like the screenshot below and will actually already provide the information needed to create a new project.
+
+.. image:: /_static/img/devilbox-vhosts-empty.png
+
+
+Step 2: create a project directory
+----------------------------------
+
+In your Devilbox git directory, navigate to ``./data/www`` and create a new directory.
+
+.. note::
+     Choose the directory name wisely, as it will be part of the domain for that project.
+     For this example we will use ``project-1`` as our project name.
+
+.. code-block:: bash
+
+   # navigate to your Devilbox git directory
+   host> cd path/to devilbox
+
+   # navigate to the data directory
+   host> cd data/www
+
+   # create a new project directory named: project-1
+   host> mkdir project-1
+
+Vist the vhost page again and see what has changed: http://localhost/vhosts.php
+
+.. image:: /_static/img/devilbox-vhosts-directory.png
+
+**So what has happened?**
+
+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.
+
+Navigate to your newly created project directory and create a directory named `htdocs` inside it.
+
+.. code-block:: bash
+
+   # navigate to your Devilbox git directory
+   host> cd path/to devilbox
+
+   # navigate to your above created project directory
+   host> cd data/www/project-1
+
+   # create the docroot directory
+   host> mkdir htdocs
+
+Vist the vhost page again and see what has changed: http://localhost/vhosts.php
+
+.. image:: /_static/img/devilbox-vhosts-dns.png
+
+**So what has happened?**
+
+By having created the docroot directory, the web server is now able to serve your files. However it has noticed, that you have no way yet, to actually visit your project url, as no DNS record for it exists yet.
+
+The intranet already gives you the exact string that you can simply copy into your ``/etc/hosts`` file on your host operating system to solve this issue.
+
+.. 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
+     DNS entries to your host computer, but is outside the scope of this
+     *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.
+
+.. code-block:: bash
+
+    # Open your /etc/hosts file with sudo or root privileges
+    # and add the following DNS entry
+    host> sudo vi /etc/hosts
+
+    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``.
+
+Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add the following entry
+
+.. code-block:: bash
+
+    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
+host system.
+
+1. Find out the IP address the virtual machine is running on
+2. Add a DNS entry to your host operating system for this IP address.
+
+For the sake of this example, let's assume the virtual machine is running on ``192.16.0.1``, then the DNS record you will
+have to add instead on your host operating system is:
+
+**Docker Toolbox on MacOS**
+
+.. code-block:: bash
+
+    host> sudo vi /etc/hosts
+
+    192.16.0.1 project-1.loc
+
+**Docker Toolbox on Windows**
+
+Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add the following entry
+
+.. code-block:: bash
+
+    192.16.0.1 project-1.loc
+
+
+Back to intranet
+^^^^^^^^^^^^^^^^
+
+Vist the vhost page again and see what has changed: http://localhost/vhosts.php
+
+.. image:: /_static/img/devilbox-vhosts-finished.png
+
+**So what has happened?**
+
+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
+
+.. image:: /_static/img/devilbox-project-no-files.png
+
+**So what has happened?**
+
+Everything is setup now, however the webserver is trying to find a ``index.php`` file in your document root which does not yet exist.
+
+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.
+
+.. code-block:: bash
+
+   # navigate to your Devilbox git directory
+   host> cd path/to devilbox
+
+   # navigate to your projects docroot directory
+   host> cd data/www/project-1/htdocs
+
+   # Create a hello world index.php file
+   host> echo "<?php echo 'hello world';" > index.php
+
+Alternatively create an ``index.php`` file in ``data/www/project-1/htdocs`` with the following contents:
+
+.. code-block:: php
+
+   <?php echo 'hello world';
+
+Vist your project url again and see what has changed: http://project-1.loc
+
+.. image:: /_static/img/devilbox-project-hello-world.png
+
+
+Checklist
+=========
+
+1. :ref:`prerequisites` are read and understood
+2. project directory is created
+3. docroot directory is created
+4. DNS entry is added to the host operating system
+5. PHP files are added to your docroot directory

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

@@ -2,6 +2,11 @@
 Install the Devilbox
 ********************
 
+.. important::
+   :ref:`read_first`
+     Ensure you have read this document to understand how this documentation works.
+
+
 Supported OS
 ============
 
@@ -54,7 +59,7 @@ To download that, open a terminal and copy/paste the following command.
 
 .. code-block:: bash
 
-   git clone https://github.com/cytopia/devilbox
+   host> git clone https://github.com/cytopia/devilbox
 
 
 Checkout a different release
@@ -69,8 +74,8 @@ this specific git tag.
 
 .. code-block:: bash
 
-   cd path/to/devilbox
-   git checkout 0.12.1
+   host> cd path/to/devilbox
+   host> git checkout 0.12.1
 
 
 .. warning::
@@ -89,7 +94,7 @@ copied to a file named ``.env``. (Note the leading dot).
 
 .. code-block:: bash
 
-   cp env-example .env
+   host> cp env-example .env
 
 The ``.env`` file does nothing else then providing environment variables for ``Docker Compose``
 and in this case it is used as the main configuration file for the devilbox by providing all kinds
@@ -115,14 +120,14 @@ Find your user id
 
 .. code-block:: bash
 
-   id -u
+   host> id -u
 
 Find your group id
 ------------------
 
 .. code-block:: bash
 
-   id -g
+   host> id -g
 
 In most cases both values will be ``1000``, but for the sake of this example, let's assume a value
 of ``1001`` for the user id and ``1002`` for the group id.
@@ -134,7 +139,7 @@ Open the ``.env`` file with your favorite text editor and adjust those values:
    :name: .env
    :emphasize-lines: 3,4
 
-   vi .env
+   host> vi .env
 
    NEW_UID=1001
    NEW_GID=1002

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

@@ -22,7 +22,7 @@ just start them all via:
 
 .. code-block:: bash
 
-   docker-compose up
+   host> docker-compose up
 
 * If you want to gracefully stop all container, hit ``Ctrl + c``
 * If you want to kill all container, hit ``Ctrl + c`` twice
@@ -36,7 +36,7 @@ If you don't require all services to be up and running and let's say just ``PHP`
 
 .. code-block:: bash
 
-   docker-compose up httpd php mysql
+   host> docker-compose up httpd php mysql
 
 * If you want to gracefully stop all started container, hit ``Ctrl + c``
 * If you want to kill all started container, hit ``Ctrl + c`` twice

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

@@ -17,11 +17,11 @@ stop all devilbox containers:
 .. code-block:: bash
 
    # Stop containers
-   cd path/to/devilbox
-   docker-compose stop
+   host> cd path/to/devilbox
+   host> docker-compose stop
 
    # Ensure containers are stopped
-   docker-compse ps
+   host> docker-compse ps
 
 Case 1: Update master branch
 ----------------------------
@@ -31,8 +31,8 @@ If you simply want to update the master branch, do a ``git pull origin master``:
 .. code-block:: bash
 
    # Update master branch
-   cd path/to/devilbox
-   git pull origin master
+   host> cd path/to/devilbox
+   host> git pull origin master
 
 
 Case 2: Checkout release tag
@@ -43,8 +43,8 @@ If you want to checkout a specific release tag (such as ``0.12.1``), do a ``git
 .. code-block:: bash
 
    # Checkout release
-   cd path/to/devilbox
-   git checkout 0.12.1
+   host> cd path/to/devilbox
+   host> git checkout 0.12.1
 
 
 
@@ -61,15 +61,15 @@ your favorite diff editor:
 
 .. code-block:: bash
 
-   vimdiff .env env-example
+   host> vimdiff .env env-example
 
 .. code-block:: bash
 
-   diff .env env-example
+   host> diff .env env-example
 
 .. code-block:: bash
 
-   meld .env env-example
+   host> meld .env env-example
 
 
 Update Docker container
@@ -85,8 +85,8 @@ which will update all available Docker images at once.
 .. code-block:: bash
 
    # Update docker images
-   cd path/to/devilbox
-   ./update-docker.sh
+   host> cd path/to/devilbox
+   host> ./update-docker.sh
 
 .. note::
 
@@ -102,8 +102,8 @@ The devilbox is not yet at a feature-ready stable release and volumes mounts mig
 .. code-block:: bash
 
    # Remove anonymous volumes
-   cd path/to/devilbox
-   docker-compose rm
+   host> cd path/to/devilbox
+   host> docker-compose rm
 
 
 Checklist git repository

docs/index.rst

@@ -5,7 +5,15 @@ devilbox documentation
 
 .. image:: img/banner.png
 
+.. important::
+   :ref:`read_first`
+     Ensure you have read this document to understand how this documentation works.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: About
+
+   about/read-first
 
 .. toctree::
    :maxdepth: 2

docs/installation/docker-installation.rst

@@ -46,7 +46,7 @@ user is assigned to the ``docker`` group. Check this via ``groups`` or ``id`` co
 
 .. code-block:: bash
 
-   id
+   host> id
 
    uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker)