Documentation restructuring

docs/howto/docker/docker-toolbox-and-the-devilbox.rst

@@ -0,0 +1,168 @@
+:orphan:
+
+.. include:: ../../_includes/global/links.rst
+
+.. _howto_docker_toolbox_and_the_devilbox:
+
+*******************************
+Docker Toolbox and the Devilbox
+*******************************
+
+Docker Toolbox is a legacy solution to bring Docker to systems which don’t natively support Docker.
+This is achieved by starting a virtualized Linux instance (e.g.: inside VirtualBox) and have
+Docker run inside this machine.
+
+You don’t have to take care about setting up the virtual machine, this is done automatically with
+the provided setup file (Windows and MacOS).
+
+However, there are a few stumbling blocks you need to pay attention to in order to use the Devilbox
+at its full potential.
+
+.. seealso::
+
+   Docker Toolbox
+     * |ext_lnk_install_docker_toolbox_win|
+     * |ext_lnk_install_docker_toolbox_mac|
+     * |ext_lnk_install_docker_toolbox_mac_native_vs_toolbox|
+     * |ext_link_docker_machine|
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Devilbox listening address configuration
+========================================
+
+First thing you need to make sure is that the ``LOCAL_LISTEN_ADDR`` variable from your ``.env``
+file is empty. When it is empty all services bind to all IP addresses inside the virtual machine
+and thus being able to be seen from outside the virtual machine (your host operating system).
+
+You can verifiy that the variable is actually empty by checking your ``.env`` file:
+
+.. code-block:: bash
+
+   host> grep ^LOCAL_LISTEN_ADDR .env
+
+   LOCAL_LISTEN_ADDR=
+
+.. important:: The variable should exist, but there should not be any value after the equal sign.
+
+.. seealso:: :ref:`env_file`
+
+
+Find the Docker Toolbox IP address
+==================================
+
+The Devilbox intranet will not be available under ``127.0.0.1`` or ``localhost`` as it does not run
+on your host operating system, but on a virtualized Linux machine which has a different IP address.
+
+To find out the IP address on which Docker Toolbox is running you have to use the
+``docker-machine`` command. Open a terminal and type the following:
+
+.. code-block:: bash
+
+   host> docker-machine ip default
+   192.168.99.100
+
+The above example outputs ``192.168.99.100``, but this might be different on your machine.
+
+In this example I would then paste ``http://192.168.99.100`` in the web browsers address bar to
+reach the Devilbox intranet.
+
+.. seealso::
+
+   * :ref:`howto_open_terminal_on_mac`
+   * :ref:`howto_open_terminal_on_win`
+
+
+Project DNS record pitfalls
+===========================
+
+When creating manual DNS records per project, you have to keep in mind that you cannot use
+``127.0.0.1`` for the IP address part. You have to use the IP address of the Docker Toolbox
+virtual machine as was shown in the above example.
+
+
+Assuming the Docker Toolbox IP address is: ``192.168.99.100``, you have to create DNS records as
+follows:
+
+.. code-block:: bash
+   :caption: /etc/resolv.conf or C:\\Windows\\System32\\drivers\\etc
+
+   192.168.99.100 project.loc
+
+.. seealso::
+
+   * :ref:`howto_add_project_dns_entry_on_mac`
+   * :ref:`howto_add_project_dns_entry_on_win`
+
+
+Auto-DNS via port forwarding
+============================
+
+In order to make Auto-DNS for projects work as it does for native Docker implementations you will
+have to do some prior configuration.
+
+How does Auto-DNS work?
+-----------------------
+
+Auto-DNS is a catch-all DNS resolver for your chosen :ref:`env_tld_suffix` that will redirect any
+domain to ``127.0.0.1``. Unfortunately Docker Toolbox does not listen on that IP address.
+
+How to fix it for Docker Toolbox
+--------------------------------
+
+To overcome this problem, you will have to create two port forwards on your host operating system
+from ``127.0.0.1`` to the Docker machine IP address for `http` (port 80) and `https` (port 443).
+
+Assuming the Docker Toolbox IP address is ``192.168.99.100`` the two port forwards must be as
+follows:
+
++-----------+-----------+----------------+---------+
+| From IP   | From port | To IP          | To port |
++===========+===========+================+=========+
+| 127.0.0.1 | 80        | 192.168.99.100 | 80      |
++-----------+-----------+----------------+---------+
+| 127.0.0.1 | 443       | 192.168.99.100 | 443     |
++-----------+-----------+----------------+---------+
+
+.. seealso::
+
+   :ref:`setup_auto_dns`
+
+.. todo:: This section requires a step-by-step guide for Mac on Windows on port-forwarding.
+
+
+Mount shared folders
+====================
+
+Docker Toolbox will automatically set up a shared directory between your host operating system and
+the virtual Linux machine. Only files and directories within this shared directory can be used to
+be mounted into Docker container. If you plan to mount files or directories outside of this default
+path you have to create a new shared directory as described below.
+
+MacOS
+-----
+
+When you want to have your projects reside not somewhere in the ``/Users`` directory, ensure you
+have read, understood and applied the following:
+
+    "By default, Toolbox only has access to the ``/Users`` directory and mounts it into the VMs at
+    ``/Users``. If your project lives elsewhere or needs access to other directories on the host
+    filesystem, you can add them."
+
+.. seealso:: |ext_lnk_install_docker_toolbox_mac_shared_directory|
+
+Windows
+-------
+
+When you want to have your projects reside not somewhere in the ``C:\Users`` directory, ensure you
+have read, understood and applied the following:
+
+    "By default, Toolbox only has access to the ``C:\Users`` directory and mounts it into the VMs
+    at ``/c/Users``. If your project lives elsewhere or needs access to other directories on the
+    host filesystem, you can add them, using the VirtualBox UI."
+
+.. seealso:: |ext_lnk_install_docker_toolbox_win_shared_directory|

docs/howto/docker/find-docker-and-docker-compose-version.rst

@@ -0,0 +1,23 @@
+:orphan:
+
+.. _howto_find_docker_and_docker_compose_version:
+
+**************************************
+Find Docker and Docker Compose version
+**************************************
+
+Open a terminal and type the following:
+
+.. code-block:: bash
+
+    # Get Docker version
+    host> docker --version
+
+    # Get Docker Compose version
+    host> docker-compose --version
+
+
+.. seealso::
+
+   * :ref:`howto_open_terminal_on_mac`
+   * :ref:`howto_open_terminal_on_win`

docs/howto/docker/find-docker-toolbox-ip-address.rst

@@ -0,0 +1,48 @@
+:orphan:
+
+.. _howto_find_docker_toolbox_ip_address:
+
+******************************
+Find Docker Toolbox IP address
+******************************
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Get IP address
+==============
+
+1. Open an environment prepared Terminal
+
+2. Enter the following command to get the IP address of the Docker Toolbox virtual machine:
+
+   .. code-block:: bash
+
+      host> docker-machine ip default
+
+      192.168.99.100
+
+The above example outputs ``192.168.99.100``, but this might be a different IP address on your
+machine.
+
+.. seealso::
+
+   * :ref:`howto_open_terminal_on_mac`
+   * :ref:`howto_open_terminal_on_win`
+
+
+What to do with it
+==================
+
+The Docker Toolbox IP address is the address where the Devilbox intranet as well as all of its
+projects will be available at.
+
+* Use it to access the intranet via your browser (``http://192.168.99.100`` in this example)
+* Use it for manual DNS entries
+
+.. seealso::
+
+   * :ref:`howto_add_project_dns_entry_on_mac`
+   * :ref:`howto_add_project_dns_entry_on_win`