Extend documentation

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

@@ -52,7 +52,7 @@ Download the devilbox
 The devilbox does not need to be installed. The only thing that is required is its git directory.
 To download that, open a terminal and copy/paste the following command.
 
-.. code-block:: console
+.. code-block:: bash
 
    git clone https://github.com/cytopia/devilbox
 
@@ -67,7 +67,7 @@ specific ``git tag``.
 Lets say you want your devilbox setup to be at release ``0.12.1``, all you have to do is to check out
 this specific git tag.
 
-.. code-block:: console
+.. code-block:: bash
 
    cd path/to/devilbox
    git checkout 0.12.1
@@ -87,7 +87,7 @@ Inside the cloned devilbox git directory, you will find a file called ``env-exam
 acts as a template with sane defaults for ``Docker Compose``. In order to use it, it must be
 copied to a file named ``.env``. (Note the leading dot).
 
-.. code-block:: console
+.. code-block:: bash
 
    cp env-example .env
 
@@ -113,14 +113,14 @@ on a terminal:
 Find your user id
 -----------------
 
-.. code-block:: console
+.. code-block:: bash
 
    id -u
 
 Find your group id
 ------------------
 
-.. code-block:: console
+.. code-block:: bash
 
    id -g
 

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

@@ -1,3 +1,73 @@
 ******************
 Start the Devilbox
 ******************
+
+Congratulations, when you have reached this page everything has been set up and you can now get your
+hands dirty.
+
+.. note::
+
+     Starting and stopping containers is done via ``docker-compose``. If you have never worked with
+     it before, have a look at their documentation for an
+     `overview <https://docs.docker.com/compose/reference/overview/>`_,
+     `up <https://docs.docker.com/compose/reference/up/>`_ and
+     `stop <https://docs.docker.com/compose/reference/stop/>`_ commands.
+
+
+Start all container
+===================
+
+If you want all provided services to be available (as defined in ``docker-compose.yml``),
+just start them all via:
+
+.. code-block:: bash
+
+   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
+
+
+Start some container
+====================
+
+If you don't require all services to be up and running and let's say just ``PHP``, ``HTTPD`` and
+``MYSQL``, enter the following command:
+
+.. code-block:: bash
+
+   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
+
+.. seealso::
+   :ref:`available_container`
+      Have a look at this page to get an overview about all available container and by what name
+      they have to be specified.
+
+
+Open Devilbox intranet
+======================
+
+Once ``docker-compose up`` has finished and all or the selected container are up and running,
+you can visit the Devilbox intranet with your favorite Web browser at http://localhost or
+http://127.0.0.1.
+
+The Intranet start page will also show you all running and failed containers:
+
+.. image:: /_static/img/devilbox-dash-full.png
+.. image:: /_static/img/devilbox-dash-selective.png
+
+.. warning::
+   :ref:`docker_toolbox`
+      When you are using ``Docker Toolbox`` the Devilbox Web server port will not be available on
+      your host computer. You have to forward the virtual machines port to your host computer.
+      Read more about it on this guide.
+
+
+Checklist
+=========
+
+1. Docker container are started successfully with ``docker-compose up``
+2. Intranet is reachable via ``http://localhost`` or ``http://127.0.0.1``

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

@@ -2,9 +2,55 @@
 Update the Devilbox
 *******************
 
+If you are in the initial install process, you can safely skip this section and come back once
+you actually want to update the Devilbox.
+
 Update git repository
 =====================
 
+Stop container
+--------------
+
+Before updating your git branch or checking out a different tag or commit, make sure to properly
+stop all devilbox containers:
+
+.. code-block:: bash
+
+   # Stop containers
+   cd path/to/devilbox
+   docker-compose stop
+
+   # Ensure containers are stopped
+   docker-compse ps
+
+Case 1: Update master branch
+----------------------------
+
+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
+
+
+Case 2: Checkout release tag
+----------------------------
+
+If you want to checkout a specific release tag (such as ``0.12.1``), do a ``git checkout 0.12.1``:
+
+.. code-block:: bash
+
+   # Checkout release
+   cd path/to/devilbox
+   git checkout 0.12.1
+
+
+
+Keep ``.env`` file in sync
+--------------------------
+
 .. warning::
       Whenever you check out a different version, make sure that your ``.env`` file is up-to-date
       with the bundled ``env-example`` file. Different Devilbox releases might require different
@@ -13,23 +59,65 @@ Update git repository
 You can also compare your current ``.env`` file with the provided ``env-example`` file by using
 your favorite diff editor:
 
-How to diff the ``.env`` file
------------------------------
-
-.. code-block:: console
+.. code-block:: bash
 
    vimdiff .env env-example
 
-.. code-block:: console
+.. code-block:: bash
 
    diff .env env-example
 
-.. code-block:: console
+.. code-block:: bash
 
    meld .env env-example
 
 
-
-
 Update Docker container
 =======================
+
+Updating the git branch shouldn't be needed to often, most changes are actually shipped via newer
+``Docker images``, so you should frequently update those.
+
+This is usually achieved by issueing a ``docker pull`` command with the correct image name and image
+version. For your convenience there is a shell script in the Devilbox git directory: ``update-docker.sh``
+which will update all available Docker images at once.
+
+.. code-block:: bash
+
+   # Update docker images
+   cd path/to/devilbox
+   ./update-docker.sh
+
+.. note::
+
+     The Devilbox own Docker images (Apache, Nginx, PHP and MySQL) are even built every night to ensure
+     latest security patches and tool versions are applied.
+
+
+Remove anonymous volumes
+========================
+
+The devilbox is not yet at a feature-ready stable release and volumes mounts might change from release to release until version 1.0 will be released. This can cause errors during startup. To solve those issues after updating, you should remove all anonymouse volumes with the following command:
+
+.. code-block:: bash
+
+   # Remove anonymous volumes
+   cd path/to/devilbox
+   docker-compose rm
+
+
+Checklist git repository
+========================
+
+1. Ensure containers are stopped
+2. Ensure desired branch, tag or commit is checked out or latest changes are pulled
+3. Ensure ``.env`` file is in sync with ``env-example`` file
+4. Ensure anonymous volumes are removed
+
+
+Checklist Docker images
+=======================
+
+1. Ensure ``./update-docker.sh`` is executed
+2. Ensure anonymous volumes are removed
+

docs/index.rst

@@ -22,6 +22,7 @@ devilbox documentation
    :maxdepth: 2
    :caption: Tutorials
 
+   tutorials/configure-database-in-your-project
    tutorials/change-document-root
    tutorials/change-container-versions
    tutorials/work-inside-the-container

docs/installation/docker-installation.rst

@@ -44,7 +44,7 @@ called ``docker``. After having installed Docker on your system, ensure that you
 user is assigned to the ``docker`` group. Check this via ``groups`` or ``id`` command.
 
 
-.. code-block:: console
+.. code-block:: bash
 
    id
 

docs/readings/available-container.rst

@@ -0,0 +1,5 @@
+.. _available_container:
+
+*******************
+Available container
+*******************