Merge pull request #237 from cytopia/documentation-dns

Release v0.13.1 (Communicate with external hosts)

.devilbox/www/config.php

@@ -13,8 +13,8 @@ error_reporting(-1);
 putenv('RES_OPTIONS=retrans:1 retry:1 timeout:1 attempts:1');
 
 
-$DEVILBOX_VERSION = 'v0.13';
-$DEVILBOX_DATE = '2018-04-14';
+$DEVILBOX_VERSION = 'v0.13.1';
+$DEVILBOX_DATE = '2018-04-28';
 $DEVILBOX_API_PAGE = 'devilbox-api/status.json';
 
 //

.devilbox/www/include/lib/container/Dns.php

@@ -56,7 +56,7 @@ class Dns extends BaseClass implements BaseInterface
 		$output = loadClass('Helper')->exec($cmd);
 
 		$version = loadClass('Helper')->egrep('/"[0-9.-]+.*"/', $output);
-		$version = loadClass('Helper')->egrep('/[0-9.-]+/', $version);
+		$version = loadClass('Helper')->egrep('/[0-9.-]+[0-9]+/', $version);
 
 		// Cache and return
 		$this->_version = $version ? $version : '';

.gitignore

@@ -19,6 +19,9 @@
 /data/*
 /backups/*
 
+# Ignore compose override file
+docker-compose.override.yml
+
 # Ignore custom HTTPD configs
 /cfg/apache-2.2/*.conf
 /cfg/apache-2.4/*.conf

docker-compose.override.yml-example

@@ -0,0 +1,23 @@
+# IMPORTANT: The version must match the version of docker-compose.yml
+version: '2.1'
+
+# The following override shows an example for the cockroachdb
+services:
+  # Your custom Docker image here:
+  cockroach:
+    image: cockroachdb/cockroach:latest
+    command: start --insecure
+    # Ensure the chosen ports are not occupied on the host system
+    ports:
+      - "${LOCAL_LISTEN_ADDR}26257:26257"
+      - "${LOCAL_LISTEN_ADDR}8080:8080"
+    networks:
+      app_net:
+        # Ensure to pick an IP address from docker-compose.yml network
+        # that is not yet taken by other sevices
+        ipv4_address: 172.16.238.200
+    # (Optional) For ease of use always automatically start these:
+    depends_on:
+      - bind
+      - php
+      - httpd

docker-compose.yml

@@ -12,6 +12,9 @@
 ##
 ## -- DO NOT EDIT THIS FILE --
 ##
+## Copy 'docker-compose.override.yml-example' to 'docker-compose.override.yml'
+## and edit this file with your custom changes (override or even new services).
+##
 ## Edit '.env' for configuration.
 ##
 ## If '.env' does not exist, copy 'env-example' to '.env'
@@ -31,29 +34,57 @@ services:
   # Bind (DNS Server)
   # ------------------------------------------------------------
   bind:
-    image: cytopia/bind:0.11
+    image: cytopia/bind:0.15
     restart: always
     ports:
       # [local-machine:]local-port:docker-port
-      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53"
+      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/tcp"
       - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/udp"
 
     environment:
       ##
       ## Debug?
       ##
-      - DEBUG_COMPOSE_ENTRYPOINT
+      - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT}
 
       ##
-      ## Bind settings
+      ## Bind wildcard/host settings
+      ##
+      - WILDCARD_DNS=${TLD_SUFFIX:-loc}=172.16.238.11
+      - EXTRA_HOSTS=${EXTRA_HOSTS}
+
+      ##
+      ## Forwarding
       ##
-      - WILDCARD_DOMAIN=${TLD_SUFFIX:-loc}
-      - WILDCARD_ADDRESS=172.16.238.11
       - DNS_FORWARDER=${BIND_DNS_RESOLVER:-8.8.8.8,8.8.4.4}
 
+      ##
+      ## Security
+      ##
+      - DNSSEC_VALIDATE=${BIND_DNSSEC_VALIDATE:-no}
+
+      ##
+      ## Time settings
+      ##
+      - TTL_TIME=${BIND_TTL_TIME}
+      - REFRESH_TIME=${BIND_REFRESH_TIME}
+      - RETRY_TIME=${BIND_RETRY_TIME}
+      - EXPIRY_TIME=${BIND_EXPIRY_TIME}
+      - MAX_CACHE_TIME=${BIND_MAX_CACHE_TIME}
+
+      ##
+      ## Query log
+      ##
+      - DOCKER_LOGS=${BIND_LOG_DNS_QUERIES}
+
     dns:
       - 127.0.0.1
 
+    # MacOS and Windows have this by default, this hack also allows it for Linux
+    extra_hosts:
+      docker.for.lin.host.internal: 172.16.238.1
+      docker.for.lin.localhost: 172.16.238.1
+
     networks:
       app_net:
         ipv4_address: 172.16.238.100
@@ -111,15 +142,18 @@ services:
       - MYSQL_BACKUP_PASS=${MYSQL_ROOT_PASSWORD}
       - MYSQL_BACKUP_HOST=mysql
 
+    dns:
+      - 172.16.238.100
+
+    # MacOS and Windows have this by default, this hack also allows it for Linux
+    extra_hosts:
+      docker.for.lin.host.internal: 172.16.238.1
+      docker.for.lin.localhost: 172.16.238.1
+
     networks:
       app_net:
         ipv4_address: 172.16.238.10
 
-    dns:
-      - 172.16.238.100
-      - 8.8.8.8
-      - 8.8.4.4
-
     volumes:
       # ---- Format: ----
       # HOST-DIRECTORY : DOCKER-DIRECTORY

docs/configuration-files/docker-compose-override-yml.rst

@@ -0,0 +1,75 @@
+.. _docker_compose_override_yml:
+
+***************************
+docker-compose.override.yml
+***************************
+
+The ``docker-compose.override.yml`` is the configuration file where you can override existing settings from ``docker-compose.yml`` or even add completely new services.
+
+By default, this file does not exist and you must create it. You can either copy the existing ``docker-compose.override.yml-example`` or create a new one.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+.. seealso:: Official Docker documentation: `Share Compose configurations between files and projects <https://docs.docker.com/compose/extends>`_
+
+
+Create docker-compose.override.yml
+==================================
+
+Copy example file
+-----------------
+
+.. code-block:: bash
+
+    host> cd path/to/devilbox
+    host> cp docker-compose.override.yml-example docker-compose.override.yml
+
+
+Create new file from scratch
+----------------------------
+
+1. Create an empty file within the Devilbox git directory named ``docker-compose.override.yml``
+2. Retrieve the currently used version from the existing ``docker-compose.yml`` file
+3. Copy this version line to your newly created ``docker-compose.override.yml`` at the very top
+
+.. code-block:: bash
+
+    # Create an empty file
+    host> cd path/to/devilbox
+    host> touch docker-compose.override.yml
+
+    # Retrieve the current version
+    host> grep ^version docker-compose.yml
+    version: '2.1'
+
+    # Add this version line to docker-compose.override.yml
+    host> echo "version: '2.1'" > docker-compose.override.yml
+
+Let's see again how this file should look like now:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+
+    version: '2.1'
+
+
+
+.. note::
+    The documentation might be outdated and the version number might already be higher.
+    Rely on the output of the ``grep`` command.
+
+
+Further reading
+===============
+
+To dive deeper into this topic and see how to actually add new services or overwrite existing
+services follow the below listed links:
+
+.. seealso::
+    * :ref:`add_your_own_docker_image`
+    * :ref:`overwrite_existing_docker_image`

docs/configuration-files/docker-compose-yml.rst

@@ -0,0 +1,13 @@
+.. _docker_compose_yml:
+
+******************
+docker-compose.yml
+******************
+
+This file is the core of the Devilbox and glues together all Docker images.
+
+It is very tempting to just change this file in order to add new services to the already existing once.
+However your git directory will become dirty and you will always have to stash your changes before pulling new features from remote. To overcome this Docker Compose offers a default override file (``docker-compose.override.yml``) that let's you specify custom changes as well as completely new services without having to touch the default ``docker-compose.yml``.
+
+.. seealso::
+    To find out more read :ref:`docker_compose_override_yml`

docs/configuration-files/env-file.rst

@@ -245,6 +245,76 @@ this project visible to everyone in your corporate LAN.
     and
     `Docker Release notes <https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-17120-ce-mac46-2018-01-09>`_
 
+.. _env_extra_hosts:
+
+EXTRA_HOSTS
+-----------
+
+This variable allows you to add additional DNS entries from hosts outside the Devilbox network,
+such as hosts running on your host operating system, the LAN or from the internet.
+
++-----------------+------------------------------+---------------+
+| Name            | Allowed values               | Default value |
++=================+==============================+===============+
+| ``EXTRA_HOSTS`` | comma separated host mapping | empty         |
++-----------------+------------------------------+---------------+
+
+Adding hosts can be done in two ways:
+
+1. Add DNS entry for an IP address
+2. Add DNS entry for a hostname/CNAME which will be mapped to whatever IP address it will resolve
+
+
+The general structure to add extra hosts looks like this
+
+.. code-block:: bash
+
+    # Single host
+    EXTRA_HOSTS='hostname=1.1.1.1'
+    EXTRA_HOSTS='hostname=CNAME'
+
+    # Multiple hosts
+    EXTRA_HOSTS='hostname1=1.1.1.1,hostname2=2.2.2.2'
+    EXTRA_HOSTS='hostname1=CNAME1,hostname2=CNAME2'
+
+* The left side represents the name by which the host will be available by
+* The right side represents the IP address by which the new name will resolve to
+* If the right side is a CNAME itself, it will be first resolved to an IP address and then the left side will resolve to that IP address.
+
+A few examples for adding extra hosts:
+
+.. code-block:: bash
+
+    # 1. One entry:
+    # The following extra host 'loc' is added and will always point to 192.168.0.7.
+    # When reverse resolving '192.168.0.7' it will answer with 'tld'.
+    EXTRA_HOSTS='loc=192.168.0.7'
+
+    # 2. One entry:
+    # The following extra host 'my.host.loc' is added and will always point to 192.168.0.9.
+    # When reverse resolving '192.168.0.9' it will answer with 'my.host'.
+    EXTRA_HOSTS='my.host.loc=192.168.0.9'
+
+    # 3. Two entries:
+    # The following extra host 'tld' is added and will always point to 192.168.0.1.
+    # When reverse resolving '192.168.0.1' it will answer with 'tld'.
+    # A second extra host 'example.org' is added and always redirects to 192.168.0.2
+    # When reverse resolving '192.168.0.2' it will answer with 'example.org'.
+    EXTRA_HOSTS='tld=192.168.0.1,example.org=192.168.0.2'
+
+    # 4. Using CNAME's for resolving:
+    # The following extra host 'my.host' is added and will always point to whatever
+    # IP example.org resolves to.
+    # When reverse resolving '192.168.0.1' it will answer with 'my.host'.
+    EXTRA_HOSTS='my.host=example.org'
+
+.. seealso::
+
+    This resembles the feature of `Docker Compose: extra_hosts <https://docs.docker.com/compose/compose-file/#external_links>`_ to add external links.
+
+.. seealso:: :ref:`communicating_with_external_hosts`
+
+
 .. _env_new_uid:
 
 NEW_UID
@@ -1335,12 +1405,123 @@ Auto-DNS) in order to resolve custom project domains defined by ``TLD_SUFFIX``.
 To also be able to reach the internet from within the Container there must be some kind of
 upstream DNS server to ask for queries.
 
+Some examples:
+
+.. code-block:: bash
+
+    BIND_DNS_RESOLVER='8.8.8.8'
+    BIND_DNS_RESOLVER='8.8.8.8,192.168.0.10'
+
+
 .. note::
     If you don't trust the Google DNS server, then set it to something else.
     If you already have a DNS server inside your LAN and also want your custom DNS (if any)
     to be available inside the containers, set the value to its IP address.
 
 
+BIND_DNSSEC_VALIDATE
+^^^^^^^^^^^^^^^^^^^^
+
+This variable controls the DNSSEC validation of the DNS server. By default it is turned off.
+
++--------------------------+--------------------------------------+---------------------+
+| Name                     | Allowed values                       | Default value       |
++==========================+======================================+=====================+
+| ``BIND_DNSSEC_VALIDATE`` | ``no``, ``auto``, ``yes``            | ``no``              |
++--------------------------+--------------------------------------+---------------------+
+
+* ``yes`` - DNSSEC validation is enabled, but a trust anchor must be manually configured. No validation will actually take place.
+* ``no`` - DNSSEC validation is disabled, and recursive server will behave in the "old fashioned" way of performing insecure DNS lookups, until you have manually configured at least one trusted key.
+* ``auto`` - DNSSEC validation is enabled, and a default trust anchor (included as part of BIND) for the DNS root zone is used.
+
+BIND_LOG_DNS
+^^^^^^^^^^^^
+
+This variable controls if DNS queries should be shown in Docker log output or not. By default no
+DNS queries are shown.
+
++--------------------------+------------------------+---------------------+
+| Name                     | Allowed values         | Default value       |
++==========================+========================+=====================+
+| ``BIND_LOG_DNS``         | ``1`` or ``0``         | ``0``               |
++--------------------------+------------------------+---------------------+
+
+If enabled all DNS queries are shown. This is useful for debugging.
+
+
+BIND_TTL_TIME
+^^^^^^^^^^^^^
+
+This variable controls the DNS TTL in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_TTL_TIME``        | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso::
+
+    * `BIND TTL <http://www.zytrax.com/books/dns/apa/ttl.html>`_
+    * `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_REFRESH_TIME
+^^^^^^^^^^^^^^^^^
+
+This variable controls the DNS Refresh time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_REFRESH_TIME``    | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_RETRY_TIME
+^^^^^^^^^^^^^^^
+
+This variable controls the DNS Retry time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_RETRY_TIME``      | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_EXPIRY_TIME
+^^^^^^^^^^^^^^^^
+
+This variable controls the DNS Expiry time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_EXPIRY_TIME``     | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_MAX_CACHE_TIME
+^^^^^^^^^^^^^^^^^^^
+
+This variable controls the DNS Max Cache time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_MAX_CACHE_TIME``  | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+
+
+
+
+
 .. |br| raw:: html
 
    <br />

docs/configuration-global/auto-dns.rst

@@ -78,32 +78,34 @@ The output should look like this (It is only important that there is no ``:53``.
 Linux
 -----
 
-If the prerequisites are met, you can edit ``/etc/resolv.conf`` with root or sudo privileges
-and add the Devilbox DNS server line by adding a ``nameserver`` directive
-which points to ``127.0.0.1``:
+If the prerequisites are met, you can edit ``/etc/dhcp/dhclient.conf`` with root or sudo privileges
+and add an instruction, which tells your local DHCP client that whenever any of your DNS servers
+are changed, you always want to have an additional entry, which is the one from the Devilbox.
+
+Add the following line to to the very beginning to ``/etc/dhcp/dhclient.conf``:
 
 .. code-block:: bash
-    :caption: /etc/resolv.conf
-    :name: /etc/resolv.conf
-    :emphasize-lines: 4
+    :caption: /etc/dhcp/dhclient.conf
+    :name: /etc/dhcp/dhclient.conf
 
-    host> sudi vi /etc/resolv.conf
-    # Dynamic resolv.conf(5) file for glibc resolver(3) generated by resolvconf(8)
-    #     DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
-    nameserver 127.0.0.1
-    nameserver 192.168.0.10
-    search local
+    prepend domain-name-servers 127.0.0.1;
 
-.. important::
-    Keep all other ``nameserver`` entries intact. The Devilbox DNS nameserver will only work
-    once the Devilbox is running. If you remove all others and don't run the Devilbox,
-    you won't be able to resolve any DNS names anymore.
+When you do that for the first time, you need to restart the ``network-manager`` service.
 
-.. important::
-    The Devilbox ``nameserver`` entry should be the very first one.
+.. code-block:: bash
+
+    # Via service command
+    $ sudo service network-manager restart
+
+    # Or the systemd way
+    $ sudo systemctl restart network-manager
+
+This will make sure that whenever your /etc/resolv.conf is deployed, you will have ``127.0.0.1``
+as the first entry and also make use of any other DNS server which are deployed via the LAN's DHCP server.
+
+If the Devilbox DNS server is not running, it does not affect the name resolution, because you will
+still have other entries in ``/etc/resolv.conf``.
 
-If you now start the Devilbox you don't need to take care about manually adding DNS records
-anymore. Auto-DNS is now setup working.
 
 
 MacOS

docs/getting-started/best-practice.rst

@@ -155,16 +155,23 @@ In case of the Devilbox ``.env`` file, just store this file in your repository a
 the Devilbox git directiry. This way you make sure that you keep your file, even when the Devilbox
 git directory is deleted and you also have a means of keeping track about changes you made.
 
+You could also go further and have several ``.env`` files available somewhere. Each of those files
+holds different configurations e.g. for different projects or customers.
+
+* ``env-customer1``
+* ``env-php55``
+* ``env-project3``
+
+You would then simply symlink one of those files to the Devilbox git directory.
+
 
 Version control service config files
 ------------------------------------
 
 .. todo:: This will require some changes on the Devilbox and will be implemented shortly.
 
-
-symlink and have your own git directory
-
-Separate data partition, backups
+* Symlink and have your own git directory
+* Separate data partition, backups
 
 
 PHP project hostname settings

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

@@ -29,7 +29,7 @@ stop all devilbox containers:
    host> docker-compose stop
 
    # Ensure containers are stopped
-   host> docker-compse ps
+   host> docker-compose ps
 
 Case 1: Update master branch
 ----------------------------

docs/index.rst

@@ -65,6 +65,9 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
    :caption: Tutorials
 
+   tutorials/communicating-with-external-hosts
+   tutorials/add-your-own-docker-image
+   tutorials/overwrite-existing-docker-image
    tutorials/adding-subdomains
    tutorials/configure-database-in-your-project
    tutorials/change-document-root
@@ -124,6 +127,8 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
 
    configuration-files/env-file
+   configuration-files/docker-compose-yml
+   configuration-files/docker-compose-override-yml
    configuration-files/apache-conf
    configuration-files/nginx-conf
    configuration-files/php-ini
@@ -158,7 +163,6 @@ host is ready to be served with your custom domain.
 
    support/faq
    support/troubleshooting
-   support/hacking
    support/contributing
    support/blogs-videos-and-use-cases
    support/artwork

docs/support/hacking.rst

@@ -1,199 +0,0 @@
-.. _hacking:
-
-*******
-Hacking
-*******
-
-This section is all about customizing the Devilbox and its Docker images specifically to your needs.
-
-
-**Table of Contents**
-
-.. contents:: :local:
-
-
-
-Rebuilding Docker images
-========================
-
-The Devilbox Docker images are rebuilt frequently and automatically pushed to Dockerhub.
-However there might be cases in which you want to rebuild right away in order to use have custom
-tools installed or of any other reason.
-
-
-How to rebuild?
----------------
-
-MySQL and Web server images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-All MySQL (including MariaDB and PerconaDB) images as well as the web server images provide
-shell scripts that makes rebuilding the image very simple.
-
-Each of those repositores contain two shell scripts for building normally and rebuilding
-without cache:
-
-* ``build/docker-build.sh``
-* ``build/docker-rebuild.sh``
-
-So you basically just clone the corresponding repository to your computer, edit the ``Dockerfile``
-to your needs and run one of the scripts.
-
-The following shows an example for Apache 2.2
-
-.. code-block:: bash
-
-    # Clone the repository and enter its directory
-    host> git clone https://github.com/devilbox/docker-apache-2.2
-    host> cd docker-apache-2.2
-
-    # Edit the Dockerfile to your needs
-    host> vi Dockerfile
-
-    # Build the Docker image
-    host> ./build/docker-build.sh
-
-PHP-FPM images
-^^^^^^^^^^^^^^
-
-The repository for PHP Docker images contains all version and hence multiple Dockerfiles.
-The build procedure is slightly different as those Dockerfiles are generated via Ansible
-build afterwards. Refer to its original repository for more detailed instructions.
-
-A very basic description is as follows:
-
-.. code-block:: bash
-
-    # Clone the repository and enter its directory
-    host> git https://github.com/devilbox/docker-php-fpm
-    host> cd docker-php-fpm
-
-    # Edit the Dockerfile template for the 'work' images
-    host> vi build/ansible/DOCKERFILES/Dockerfile-work.j2
-
-    # Generate the actual Dockerfiles
-    host> make generate
-
-    # Build one specific PHP version (in this case PHP 5.5)
-    host> make build-work-55
-
-
-How to use the rebuild images?
-------------------------------
-
-For the PHP-FPM images you do not have to do anything, as they are built with the image tag that
-is already present in ``docker-compose.yml``. For all other images you might have to adjust
-the image tag in ``docker-compose.yml`` as all images will be built with the ``latest`` tag by
-default.
-
-If you have built Apache 2.2 for example, open the ``docker-compose.yml`` file inside the Devilbox
-git directory and ensure that the current image tag is replaced with ``latest``.
-
-How it could look by default:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 2
-
-    httpd:
-      image: devilbox/${HTTPD_SERVER:-nginx-stable}:0.13
-
-How it should look with latest tag:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 2
-
-    httpd:
-      image: devilbox/${HTTPD_SERVER:-nginx-stable}:latest
-
-
-Adding your own Docker image
-============================
-
-The Devilbox is at its core just a ``docker-compose.yml`` file which easily gives you the option
-to add other Docker images it is currently lacking.
-
-
-What information do you need?
------------------------------
-
-1. A name, which you can use to refer in the ``docker-compose`` command
-2. The Docker image name itself
-3. The Docker image tag
-4. An unused IP address from the devilbox network (found inside ``docker-compose.yml``)
-
-
-How to add the image?
----------------------
-
-General example
-^^^^^^^^^^^^^^^
-
-Open ``docker-compose.yml`` with your favourite editor and paste the following snippet
-below the ``services:`` line with one level of indentation:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 3-4,7
-
-    services:
-      # Your custom Docker image here:
-      <name>:
-        image: <image-name>:<image-version>
-        networks:
-          app_net:
-            ipv4_address: <unused-ip-address>
-        # For ease of use always automatically start these:
-        depends_on:
-          - bind
-          - php
-          - httpd
-      # End of custom Docker image
-
-Cockroach DB example
-^^^^^^^^^^^^^^^^^^^^
-
-Gather the requirements for the `Cockroach DB <https://hub.docker.com/r/cockroachdb/cockroach/>`_
-Docker image:
-
-1. Name: ``cockroach``
-2. Image: ``cockroachdb/cockroach``
-3. Tag: ``latest``
-4. IP: ``172.16.238.200``
-
-Now add the information to ``docker-compose.yml`` just below the ``services:`` line:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 3-4,7
-
-    services:
-      # Your custom Docker image here:
-      cockroach:
-        image: cockroachdb/cockroach:latest
-        networks:
-          app_net:
-            ipv4_address: 172.16.238.200
-        # For ease of use always automatically start these:
-        depends_on:
-          - bind
-          - php
-          - httpd
-      # End of custom Docker image
-
-
-How to start the new service?
------------------------------
-
-The following will bring up your service including all of its dependent services,
-as defined with ``depends_on`` (bind, php and httpd). You need to replace ``<name>`` with the
-name you have chosen.
-
-.. code-block:: bash
-
-    host> docker-compose up <name>

docs/tutorials/add-your-own-docker-image.rst

@@ -0,0 +1,179 @@
+.. _add_your_own_docker_image:
+
+*************************
+Add your own Docker image
+*************************
+
+This section is all about customizing the Devilbox and its Docker images specifically to your needs.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisites
+=============
+
+The new Docker image definition will be added to a file called ``docker-compose.override.yml``.
+So before going any further, read the following section that shows you how to create this file
+for the Devilbox as well as what pitfalls to watch out for.
+
+.. seealso:: :ref:`docker_compose_override_yml`
+
+
+What information do you need?
+=============================
+
+1. ``<name>`` - A name, which you can use to refer in the ``docker-compose`` command
+2. ``<image-name>`` - The Docker image name itself
+3. ``<image-version>`` - The Docker image tag
+4. ``<unused-ip-address>`` - An unused IP address from the devilbox network (found inside ``docker-compose.yml``)
+
+
+How to add a new service?
+=========================
+
+Generic example
+---------------
+
+A single new service
+^^^^^^^^^^^^^^^^^^^^
+
+Open ``docker-compose.override.yml`` with your favourite editor and paste the following snippets
+into it.
+
+.. code-block:: yaml
+    :caption: docker-compose.override.yml
+    :name: docker-compose.override.yml
+    :emphasize-lines: 4,5,8
+
+    version: '2.1'
+    services:
+      # Your custom Docker image here:
+      <name>:
+        image: <image-name>:<image-version>
+        networks:
+          app_net:
+            ipv4_address: <unused-ip-address>
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of custom Docker image
+
+.. note::
+    * ``<name>`` has to be replaced with any name of your choice
+    * ``<image-name>`` has to be replaced with the name of the Docker image
+    * ``<image-version>`` has to be replaced with the tag of the Docker image
+    * ``<unused-ip-address>`` has to be replaced with an unused IP address
+
+Two new services
+^^^^^^^^^^^^^^^^
+
+.. code-block:: yaml
+    :caption: docker-compose.override.yml
+    :name: docker-compose.override.yml
+    :emphasize-lines: 4,5,8,16,17,20
+
+    version: '2.1'
+    services:
+      # Your first custom Docker image here:
+      <name1>:
+        image: <image1-name>:<image1-version>
+        networks:
+          app_net:
+            ipv4_address: <unused-ip-address1>
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of first custom Docker image
+      # Your second custom Docker image here:
+      <name2>:
+        image: <image2-name>:<image2-version>
+        networks:
+          app_net:
+            ipv4_address: <unused-ip-address2>
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of second custom Docker image
+
+.. note::
+    * ``<name1>`` has to be replaced with any name of your choice
+    * ``<image1-name>`` has to be replaced with the name of the Docker image
+    * ``<image1-version>`` has to be replaced with the tag of the Docker image
+    * ``<unused-ip-address1>`` has to be replaced with an unused IP address
+
+.. note::
+    * ``<name2>`` has to be replaced with any name of your choice
+    * ``<image2-name>`` has to be replaced with the name of the Docker image
+    * ``<image2-version>`` has to be replaced with the tag of the Docker image
+    * ``<unused-ip-address2>`` has to be replaced with an unused IP address
+
+
+CockroachDB example
+-------------------
+
+Gather the requirements for the `Cockroach DB <https://hub.docker.com/r/cockroachdb/cockroach/>`_
+Docker image:
+
+1. Name: ``cockroach``
+2. Image: ``cockroachdb/cockroach``
+3. Tag: ``latest``
+4. IP: ``172.16.238.200``
+
+Now add the information to ``docker-compose.override.yml``:
+
+.. code-block:: yaml
+    :caption: docker-compose.override.yml
+    :name: docker-compose.override.yml
+    :emphasize-lines: 4-5,9
+
+    version: '2.1'
+    services:
+      # Your custom Docker image here:
+      cockroach:
+        image: cockroachdb/cockroach:latest
+        command: start --insecure
+        networks:
+          app_net:
+            ipv4_address: 172.16.238.200
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of custom Docker image
+
+
+
+How to start the new service?
+=============================
+
+The following will bring up your service including all of its dependent services,
+as defined with ``depends_on`` (bind, php and httpd). You need to replace ``<name>`` with the
+name you have chosen.
+
+.. code-block:: bash
+
+    host> docker-compose up <name>
+
+In the example of Cockroach DB the command would look like this
+
+.. code-block:: bash
+
+    host> docker-compose up cockroach
+
+
+Further reading
+===============
+
+.. seealso::
+    * :ref:`docker_compose_override_yml`
+    * :ref:`overwrite_existing_docker_image`

docs/tutorials/communicating-with-external-hosts.rst

@@ -0,0 +1,175 @@
+.. _communicating_with_external_hosts:
+
+*********************************
+Communicating with external hosts
+*********************************
+
+This tutorial shows you how to connect the Devilbox to running Docker container outside the
+Devilbox network, i.e. Docker container you have started separately.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisites
+=============
+
+There are two things you need to make sure of are met beforehand:
+
+1. The external Docker container must expose its ports on all interfaces on your host operating system
+2. The IP by which the host is reachable from within the Devilbox container.
+
+Host IP: Docker on Linux
+------------------------
+
+If you run Docker on Linux the host IP is always ``172.16.238.1``, which is the default gateway
+IP address within the Devilbox bridge network (see ``docker-compose.yml``).
+
+By default Docker on Linux does not have CNAME's of the host computer as for example with MacOS
+or Windows, therefore two custom CNAME's have been added by the Devilbox in order to emulate the
+same behaviour:
+
+* CNAME: ``docker.for.lin.host.internal``
+* CNAME: ``docker.for.lin.localhost``
+
+Host IP: Docker for Mac
+-----------------------
+
+If you run Docker for Mac, an IP address is not necessary as it already provides a CNAME which will
+always point to the IP address of your host operating system. Depending on the Docker version this
+CNAME will differ:
+
+Docker 18.03.0-ce+ and Docker compose 1.20.1+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``host.docker.internal``
+
+Docker 17.12.0-ce+ and Docker compose 1.18.0+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.mac.host.internal``
+
+Docker 17.06.0-ce+ and Docker compose 1.14.0+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.mac.localhost``
+
+
+Host IP: Docker for Windows
+----------------------------
+
+If you run Docker for Windows, an IP address is not necessary as it already provides a CNAME which will
+always point to the IP address of your host operating system. Depending on the Docker version this
+CNAME will differ:
+
+Docker 18.03.0-ce+ and Docker compose 1.20.1+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.win.host.internal``
+
+Docker 17.06.0-ce+ and Docker compose 1.14.0+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.win.host.localhost``
+
+
+
+Make DNS available to the Devilbox
+==================================
+
+Inside each Devilbox Docker container you can already connect to all host ports (if they are bound
+to all interfaces) by the above specified IP addresses or CNAME's. You can however also create a
+custom DNS entry for convenience or if an external web server requires a special vhost name.
+
+Adding extra hosts
+------------------
+
+Extra hosts (hostname and IP address mappings or hostname and CNAME mappings) can be set in the
+``.env`` file.
+
+.. seealso:: :ref:`env_extra_hosts`
+
+
+Example
+-------
+
+Let's assume another Docker container is running on your host, which must be accessed by the exact
+name of ``mywebserver.loc`` in order to respond by that virtual host name.
+
+
+Mapping on Linux
+^^^^^^^^^^^^^^^^
+
+If you are running Linux as your host operating system you would use the IP address of the host
+computer which was identified as ``172.16.238.1``.
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=172.16.238.1
+
+or
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=docker.for.lin.host.internal
+
+or
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=docker.for.lin.localhost
+
+
+Mapping on MacOS
+^^^^^^^^^^^^^^^^
+
+If you are running MacOS as your host operating system you would use one of the identified CNAME's
+(depending on your Docker version).
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=host.docker.internal
+
+The CNAME ``host.docker.internal`` will be resolved to an IP address during startup and ``mywebserver.loc``
+'s DNS record will point to that IP address.
+
+
+Mapping on Windows
+^^^^^^^^^^^^^^^^^^
+
+If you are running Windows as your host operating system you would use one of the identified CNAME's
+(depending on your Docker version).
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=docker.for.win.host.internal
+
+The CNAME ``docker.for.win.host.internal`` will be resolved to an IP address during startup and ``mywebserver.loc``
+'s DNS record will point to that IP address.
+
+
+Auto DNS
+--------
+
+If you also turned on :ref:`global_configuration_auto_dns` these extra hosts will then also be available
+to your host operating system as well.
+
+
+Further reading
+===============
+
+.. seealso::
+    * :ref:`env_extra_hosts`
+    * :ref:`global_configuration_auto_dns`

docs/tutorials/enable-xdebug.rst

@@ -164,7 +164,7 @@ Docker 18.03.0-ce+ and Docker compose 1.20.1+
     :caption: xdebug.ini
     :emphasize-lines: 1
 
-    xdebug.remote_host=docker.for.mac.host.internal
+    xdebug.remote_host=docker.for.win.host.internal
     xdebug.remote_connect_back=0
 
 Docker 17.06.0-ce+ and Docker compose 1.14.0+
@@ -174,7 +174,7 @@ Docker 17.06.0-ce+ and Docker compose 1.14.0+
     :caption: xdebug.ini
     :emphasize-lines: 1
 
-    xdebug.remote_host=docker.for.mac.host.internal
+    xdebug.remote_host=docker.for.win.host.localhost
     xdebug.remote_connect_back=0
 
 If you have older versions, upgrade.

docs/tutorials/overwrite-existing-docker-image.rst

@@ -0,0 +1,114 @@
+.. _overwrite_existing_docker_image:
+
+*******************************
+Overwrite existing Docker image
+*******************************
+
+This section is all about customizing the Devilbox and its Docker images specifically to your needs.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisites
+=============
+
+The new Docker image overwrite will be added to a file called ``docker-compose.override.yml``.
+So before going any further, read the following section that shows you how to create this file
+for the Devilbox as well as what pitfalls to watch out for.
+
+.. seealso:: :ref:`docker_compose_override_yml`
+
+
+What information do you need?
+=============================
+
+1. The service to overwrite
+
+
+How to overwrite a service?
+===========================
+
+Generic steps
+-------------
+
+1. Copy the whole service definition from docker-compose.yml to docker-compose.override.yml
+2. Remove anything unecessary
+3. Adjust the values you need
+
+Overwrite Docker image for the bind service
+-------------------------------------------
+
+The following example is using the ``bind`` service and overrides the Docker image
+to illustrate how this is done :
+
+
+First you simply copy the while definition of the bind service from ``docker-compose.yml`` to
+``docker-compose.override.yml``:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+
+    version: '2.1'
+    services:
+      bind:
+        image: cytopia/bind:0.11
+        restart: always
+        ports:
+          # [local-machine:]local-port:docker-port
+          - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53"
+          - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/udp"
+
+        environment:
+          ##
+          ## Debug?
+          ##
+          - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT}
+          - DOCKER_LOGS=1
+
+          ##
+          ## Bind settings
+          ##
+          - WILDCARD_ADDRESS=172.16.238.11
+          - DNS_FORWARDER=${BIND_DNS_RESOLVER:-8.8.8.8,8.8.4.4}
+
+        dns:
+          - 127.0.0.1
+
+        networks:
+          app_net:
+            ipv4_address: 172.16.238.100
+
+The second step is to remove everything that you do not need to overwrite:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+
+    version: '2.1'
+    services:
+      bind:
+        image: cytopia/bind:0.11
+
+The last step is to actually adjust the value you want to change for the bind service:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+    :emphasize-lines: 4
+
+    version: '2.1'
+    services:
+      bind:
+        image: someother/bind:latest
+
+
+Further reading
+===============
+
+.. seealso::
+    * :ref:`docker_compose_override_yml`
+    * :ref:`add_your_own_docker_image`

env-example

@@ -86,6 +86,29 @@ LOCAL_LISTEN_ADDR=
 TLD_SUFFIX=loc
 
 
+###
+### Optional DNS configuration
+### Allows you to add extra DNS records (above the wildcard entry)
+### Useful if your host computer run other Docker services that you want to connect to or reach
+### from within the Devilbox network by a custom hostname.
+###
+### Format:
+### -------
+### Resolve any custom defined hostname to an IP address (useable inside container and host os)
+###     EXTRA_HOSTS=<hostname>=<ip>[,<hostname>=<ip>]
+###
+### Resolve any custom defined hostname to whatever IP address a CNAME resolves to
+### (Useable inside the container and host OS).
+### Note: CNAME must be resolvable by Google DNS
+###     EXTRA_HOSTS=<hostname>=<CNAME>[,<hostname>=<CNAME>]
+###
+### Examples:
+### ---------
+### EXTRA_HOSTS=hostname.loc=1.2.3.4
+### EXTRA_HOSTS=host.loc=1.2.3.4,host.example.org=3.4.5.6
+EXTRA_HOSTS=
+
+
 ###
 ### Set your user id and group id
 ###
@@ -518,6 +541,35 @@ HOST_PORT_BIND=1053
 ###
 BIND_DNS_RESOLVER=8.8.8.8,8.8.4.4
 
+###
+### Validate DNSSEC
+###
+### Values:
+###  no:    DNSSEC validation is disabled
+###  yes:   DNSSEC validation is enabled, but a trust anchor must be manually configured.
+###  auto:  DNSSEC validation is enabled, and a default trust anchor for root zone is used.
+###
+BIND_DNSSEC_VALIDATE=no
+
+###
+### Bind timing options (time in seconds)
+###
+### Leave empty for defaults.
+### Only change when you know what you are doing.
+###
+BIND_TTL_TIME=
+BIND_REFRESH_TIME=
+BIND_RETRY_TIME=
+BIND_EXPIRY_TIME=
+BIND_MAX_CACHE_TIME=
+
+###
+### Show DNS Queries in Docker logs output?
+###
+### 1: Yes
+### 0: No
+BIND_LOG_DNS_QUERIES=0
+
 
 
 ################################################################################