ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2024-12-19 04:47:52 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #237 from cytopia/documentation-dns

Browse Source 
Release v0.13.1 (Communicate with external hosts)
This commit is contained in:
cytopia 2018-04-29 11:41:36 +02:00 committed by GitHub
commit 139dc7cec7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 477 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.devilbox/www/config.php
View File

@ -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';
//

53
docker-compose.yml
View File

@ -34,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
@ -114,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

181
docs/configuration-files/env-file.rst
View File

@ -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 />

42
docs/configuration-global/auto-dns.rst
View File

@ -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

1
docs/index.rst
View File

@ -65,6 +65,7 @@ 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

175
docs/tutorials/communicating-with-external-hosts.rst Normal file
View File

@ -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`

4
docs/tutorials/enable-xdebug.rst
View File

@ -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.

52
env-example
View File

@ -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
################################################################################