From 04250f2fc329c585d319256bab9360dbec52a0c6 Mon Sep 17 00:00:00 2001 From: cytopia Date: Sun, 8 Jul 2018 09:26:52 +0200 Subject: [PATCH] Shared Devilbox server in LAN --- .../advanced/add-custom-cname-dns-entries.rst | 105 ----------- docs/advanced/add-custom-cname-records.rst | 42 +++++ .../access-devilbox-from-android.rst | 2 + .../access-devilbox-from-iphone.rst | 3 + .../deploy-devilbox-via-ansible.rst | 5 + .../shared-devilbox-server-in-lan.rst | 174 +++++++++++++++++- docs/getting-started/prerequisites.rst | 17 +- .../dns/add-custom-dns-server-on-linux.rst | 109 +++++++++++ .../dns/add-custom-dns-server-on-mac.rst | 109 +++++++++++ .../dns/add-custom-dns-server-on-win.rst | 103 +++++++++++ .../dns/add-project-dns-entry-on-linux.rst | 65 +++++++ docs/index.rst | 3 +- 12 files changed, 628 insertions(+), 109 deletions(-) delete mode 100644 docs/advanced/add-custom-cname-dns-entries.rst create mode 100644 docs/advanced/add-custom-cname-records.rst create mode 100644 docs/corporate-usage/deploy-devilbox-via-ansible.rst create mode 100644 docs/howto/dns/add-custom-dns-server-on-linux.rst create mode 100644 docs/howto/dns/add-custom-dns-server-on-mac.rst create mode 100644 docs/howto/dns/add-custom-dns-server-on-win.rst create mode 100644 docs/howto/dns/add-project-dns-entry-on-linux.rst diff --git a/docs/advanced/add-custom-cname-dns-entries.rst b/docs/advanced/add-custom-cname-dns-entries.rst deleted file mode 100644 index 785a246a..00000000 --- a/docs/advanced/add-custom-cname-dns-entries.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. _add_custom_cname_dns_entries: - -**************************** -Add custom CNAME DNS entries -**************************** - -This section explains how to connect from inside a Devilbox container to the host operating system. - - -**Table of Contents** - -.. contents:: :local: - -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 - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=172.16.238.1 - -or - -.. code-block:: bash - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=docker.for.lin.host.internal - -or - -.. code-block:: bash - :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 - :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 - :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:`setup_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:`setup_auto_dns` diff --git a/docs/advanced/add-custom-cname-records.rst b/docs/advanced/add-custom-cname-records.rst new file mode 100644 index 00000000..2cef6913 --- /dev/null +++ b/docs/advanced/add-custom-cname-records.rst @@ -0,0 +1,42 @@ +.. _add_custom_cname_records: + +**************************** +Add custom CNAME DNS entries +**************************** + +You can add an infinite number of custom +`CNAME `_ records that will be available in your +running Docker container. +If Auto-DNS is turned on, those records will be available on your host operating system as well. + +.. seealso:: :ref:`setup_auto_dns` + + +**Table of Contents** + +.. contents:: :local: + + +Why and what? +============= + +This might be useful if you have an IP address or hostname on your LAN or any other domain which +you want to expose to your container by a different CNAME of your choice. + +Think of it as setting your ``/etc/hosts``, but which will be distributed accross all hosts which +are using the Devilbox' bundled DNS server. + +How? +==== + +Adjust the :ref:`env_extra_hosts` variable inside ``.env`` to add as many CNAME's as you need. + +As an example, to create a CNAME ``mywebserver.com`` pointing to ``172.16.238.1``, change your +.env file as shown below: + +.. code-block:: bash + :caption: .env + + EXTRA_HOSTS=mywebserver.loc=172.16.238.1 + +.. seealso:: See :ref:`env_extra_hosts` for an in-depth explanation with multiple examples. diff --git a/docs/corporate-usage/access-devilbox-from-android.rst b/docs/corporate-usage/access-devilbox-from-android.rst index 9875670a..f5e32978 100644 --- a/docs/corporate-usage/access-devilbox-from-android.rst +++ b/docs/corporate-usage/access-devilbox-from-android.rst @@ -3,3 +3,5 @@ Access Devilbox from Android **************************** TODO + +just run second bind server and hook it up via dhcp or custom app diff --git a/docs/corporate-usage/access-devilbox-from-iphone.rst b/docs/corporate-usage/access-devilbox-from-iphone.rst index ba6aa2e3..387624a9 100644 --- a/docs/corporate-usage/access-devilbox-from-iphone.rst +++ b/docs/corporate-usage/access-devilbox-from-iphone.rst @@ -3,3 +3,6 @@ Access Devilbox from iPhone *************************** TODO + + +just run second bind server and hook it up via dhcp or custom app diff --git a/docs/corporate-usage/deploy-devilbox-via-ansible.rst b/docs/corporate-usage/deploy-devilbox-via-ansible.rst new file mode 100644 index 00000000..a63dd00b --- /dev/null +++ b/docs/corporate-usage/deploy-devilbox-via-ansible.rst @@ -0,0 +1,5 @@ +*************************** +Deploy Devilbox via Ansible +*************************** + +TODO diff --git a/docs/corporate-usage/shared-devilbox-server-in-lan.rst b/docs/corporate-usage/shared-devilbox-server-in-lan.rst index b107966e..aeb022f1 100644 --- a/docs/corporate-usage/shared-devilbox-server-in-lan.rst +++ b/docs/corporate-usage/shared-devilbox-server-in-lan.rst @@ -2,4 +2,176 @@ Shared Devilbox server in LAN ***************************** -TODO +Devilbox as a shared **development**, **staging** or **CI** server is setup in a similar way as +you would do locally. The only three important parts to take care of are: + +1. Project access to deploy/update code +2. Handle DNS entries +3. Share Devilbox CA + + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +This walk-through will use the following example values: + ++--------------------+------------------+-----------+---------------------------+ +| LAN / Network | Devilbox server | TLD_SUFFX | LOCAL_LISTEN_ADDR | ++====================+==================+===========+===========================+ +| ``192.168.0.0/24`` | ``192.168.0.12`` | ``loc`` | ``192.168.0.12`` or empty | ++--------------------+------------------+-----------+---------------------------+ + +.. seealso:: + * :ref:`env_tld_suffix` + * :ref:`env_local_listen_addr` + + +Project access +============== + +SSH +--- + +Enable and start an SSH server and give access to whatever system or user requires it. +This can be done directly on the host system or via various other Docker container that offer +ssh server. + +Copy via sftp +^^^^^^^^^^^^^ +If your SSH server is setup, users can use their sftp clients to deploy code updates. This however +is not encouraged and you should use git or any other version control system. + +Manually git pull/checkout +^^^^^^^^^^^^^^^^^^^^^^^^^^ +When using git, users can directly ssh into the shared Devilbox server and ``git pull`` or +``git checkout `` on their projects. + +Automated git pull/checkout +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In case you are using a staging or CI server, use Jenkins jobs or other automation tools +(e.g. Ansible) to auto-deploy via SSH. + +Samba +----- + +For a shared development server, you could also setup Samba network shares for each projects +and have users deploy their code via Samba. + + +Handle DNS records +================== + +There are multiple ways of having DNS records available accross the LAN. + +.. important:: + When using a shared Devilbox server and another Devilbox setup on your local computer, + ensure that you are using different :ref:`env_tld_suffix` in order to not confuse + DNS records. + +Use a real domain +----------------- + +If you own a real domain, such as ``my-company.com``, you can create a wildcard DNS record for +a subdomain, such as ``*.dev.my-company.com`` which must point to ``192.168.0.12.``. +This should be done in your hosting provider's DNS configuration pannel. + +You must then also change the ``TLD_SUFFIX`` to that subdomain. + +.. code-block:: bash + :caption: .env + + TLD_SUFFIX=dev.my-company.com + +Handle DNS records in your own DNS server +----------------------------------------- + +If your LAN already provides its own customizable DNS server, you can setup a new wildcard DNS +zone for ``*.loc`` which points to ``192.168.0.12``. + +Run a second instance of the Devilbox DNS server +------------------------------------------------ + +If the above two methods for automated DNS records don't apply to you, you will need to run +a second stand-alone Docker container of the Devilbox DNS server. + +Run this container permantently on the shared Devilbox server with the following command: + +.. code-block:: bash + + host> docker run -d \ + --restart unless-stopped \ + -p 53:53/tcp \ + -p 53:53/udp \ + -e WILDCARD_DNS='loc=192.168.0.12' \ + -t cytopia/bind + +.. seealso:: https://github.com/cytopia/docker-bind + +Now there are two ways to consume the DNS records on your local machine: + +1. Manual +2. DHCP distributed + +Manual DNS settings +^^^^^^^^^^^^^^^^^^^ +When using this approach, you have to manually add the DNS server (IP: ``192.168.0.12``) to your +host operating system. + +.. important:: + Keep in mind that you have to do this for every machine within the network which wants to access + the shared Devilbox server. + +.. seealso:: + * :ref:`howto_add_custom_dns_server_on_linux` + * :ref:`howto_add_custom_dns_server_on_mac` + * :ref:`howto_add_custom_dns_server_on_win` + +DHCP distributed +^^^^^^^^^^^^^^^^ +This is the automated and more pain-free approach, as all devices within the network will be able +to access projects on the shared Devilbox server. + + +Self-managed DHCP server +"""""""""""""""""""""""" +If you run your own DHCP server within a network, you probably know how to add other DNS servers. +The only thing you should keep in mind is, that the Devilbox DNS server should be the first in +the list. + +DSL box / LAN or WIFI router +"""""""""""""""""""""""""""" +Most `SOHO `_ networks probably use some +vendor router which has a web interface. Generally speaking, you need to find the DNS/DHCP settings +in its web interface and add the Devilbox DNS server as the first in the list (``192.168.0.12``). + +.. seealso:: + * `Change DNS server in Fritzbox `_ + + +Add hosts entries for every project +----------------------------------- + +As you also do for the Devilbox locally when not using Auto-DNS, you can do as well for remote +computer. Just edit your local hosts file and add one DNS entry for every project on the shared +Devilbox server. + +Keep in mind that this time you will have to use ``192.168.0.12`` instead of ``127.0.0.1``. + +.. seealso:: + * :ref:`howto_add_project_dns_entry_on_linux` + * :ref:`howto_add_project_dns_entry_on_mac` + * :ref:`howto_add_project_dns_entry_on_win` + + +Share Devilbox CA +================= + +The last step to also have valid HTTPS connections on your shared Devilbox server is to copy +the CA onto your local machine and import it into your browser or system. + +.. seealso:: :ref:`setup_valid_https` diff --git a/docs/getting-started/prerequisites.rst b/docs/getting-started/prerequisites.rst index 7dd06690..77f230ff 100644 --- a/docs/getting-started/prerequisites.rst +++ b/docs/getting-started/prerequisites.rst @@ -113,7 +113,7 @@ Linux Docker on Linux requires super user privileges which is granted to a system wide group called ``docker``. After having installed Docker on your system, -ensure that your local user is assigned to the ``docker`` group: +ensure that your local user is a member of the ``docker`` group. .. code-block:: bash @@ -121,7 +121,6 @@ ensure that your local user is assigned to the ``docker`` group: uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker) - .. seealso:: * |ext_lnk_install_docker_centos| @@ -144,6 +143,16 @@ Docker for Mac Docker for Mac is the native and recommended version to choose when using the Devilbox. +Docker for Mac requires super user privileges which is granted to a system +wide group called ``docker``. After having installed Docker on your system, +ensure that your local user is a member of the ``docker`` group. + +.. code-block:: bash + + host> id + + uid=502(cytopia) gid=20(staff) groups=20(staff),999(docker) + .. seealso:: Docker for Mac @@ -179,6 +188,10 @@ Docker for Windows Docker for Windows is the native and recommended version to choose when using the Devilbox. This however is only available since **Windows 10**. +Docker for Windows requires administrative privileges which is granted to a system +wide group called ``docker-users``. After having installed Docker on your system, +ensure that your local user is a member of the ``docker-users`` group. + .. seealso:: Docker for Windows diff --git a/docs/howto/dns/add-custom-dns-server-on-linux.rst b/docs/howto/dns/add-custom-dns-server-on-linux.rst new file mode 100644 index 00000000..292aaff5 --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-linux.rst @@ -0,0 +1,109 @@ +:orphan: + +.. _howto_add_custom_dns_server_on_linux: + +****************************** +Add custom DNS server on Linux +****************************** + +TODO: the whole document is copied!!!!!!!!!!!!!!!!!!!! + +On MacOS, custom DNS entries can be added to the ``/etc/hosts`` and will take precedence over the +same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +In order to better illustrate the process, we are going to use two projects as an example. +See the following table for project directories and :ref:`env_tld_suffix`. + ++-------------------+------------+--------------------------+-----------------------+ +| Project directory | TLD_SUFFIX | Project URL | Required DNS name | ++===================+============+==========================+=======================+ +| project-1 | ``loc`` | http://project-1.loc | ``project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ +| www.project-1 | ``loc`` | http://www.project-1.loc | ``www.project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ + +Docker for Mac +-------------- + +When using Docker for Mac you can use ``127.0.0.1`` for the IP address. + +1. Open ``/etc/hosts`` with admistrative privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + +Docker Toolbox +-------------- + +When using the Docker Toolbox, you cannot use ``127.0.0.1`` for DNS entries, but rather need to +use the IP address of the Docker Toolbox machine instead. + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` + +For this example we will assume the Docker Toolbox IP address is ``192.168.99.100``. + + +1. Open ``/etc/hosts`` with admistrative privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 192.168.99.100 project-1.loc + 192.168.99.100 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms diff --git a/docs/howto/dns/add-custom-dns-server-on-mac.rst b/docs/howto/dns/add-custom-dns-server-on-mac.rst new file mode 100644 index 00000000..1fea3731 --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-mac.rst @@ -0,0 +1,109 @@ +:orphan: + +.. _howto_add_custom_dns_server_on_mac: + +****************************** +Add custom DNS server on MacOS +****************************** + +TODO: the whole document is copied!!!!!!!!!!!!!!!!!!!! + +On MacOS, custom DNS entries can be added to the ``/etc/hosts`` and will take precedence over the +same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +In order to better illustrate the process, we are going to use two projects as an example. +See the following table for project directories and :ref:`env_tld_suffix`. + ++-------------------+------------+--------------------------+-----------------------+ +| Project directory | TLD_SUFFIX | Project URL | Required DNS name | ++===================+============+==========================+=======================+ +| project-1 | ``loc`` | http://project-1.loc | ``project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ +| www.project-1 | ``loc`` | http://www.project-1.loc | ``www.project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ + +Docker for Mac +-------------- + +When using Docker for Mac you can use ``127.0.0.1`` for the IP address. + +1. Open ``/etc/hosts`` with admistrative privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + +Docker Toolbox +-------------- + +When using the Docker Toolbox, you cannot use ``127.0.0.1`` for DNS entries, but rather need to +use the IP address of the Docker Toolbox machine instead. + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` + +For this example we will assume the Docker Toolbox IP address is ``192.168.99.100``. + + +1. Open ``/etc/hosts`` with admistrative privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 192.168.99.100 project-1.loc + 192.168.99.100 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms diff --git a/docs/howto/dns/add-custom-dns-server-on-win.rst b/docs/howto/dns/add-custom-dns-server-on-win.rst new file mode 100644 index 00000000..452a49f4 --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-win.rst @@ -0,0 +1,103 @@ +:orphan: + +.. _howto_add_custom_dns_server_on_win: + +******************************** +Add custom DNS server on Windows +******************************** + +TODO: the whole document is copied!!!!!!!!!!!!!!!! + +On Windows, custom DNS entries can be added to the ``C:\Windows\System32\drivers\etc`` and will +take precedence over the same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +In order to better illustrate the process, we are going to use two projects as an example. +See the following table for project directories and :ref:`env_tld_suffix`. + ++-------------------+------------+--------------------------+-----------------------+ +| Project directory | TLD_SUFFIX | Project URL | Required DNS name | ++===================+============+==========================+=======================+ +| project-1 | ``loc`` | http://project-1.loc | ``project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ +| www.project-1 | ``loc`` | http://www.project-1.loc | ``www.project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ + +Docker for Windows +------------------ + +When using Docker for Windows you can use ``127.0.0.1`` for the IP address. + +1. Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges via ``notepad.exe`` or + any other text editor. + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: C:\Windows\System32\drivers\etc + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + +Docker Toolbox +-------------- + +When using the Docker Toolbox, you cannot use ``127.0.0.1`` for DNS entries, but rather need to +use the IP address of the Docker Toolbox machine instead. + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` + +For this example we will assume the Docker Toolbox IP address is ``192.168.99.100``. + + +1. Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges via ``notepad.exe`` or + any other text editor. + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: C:\Windows\System32\drivers\etc + + 192.168.99.100 project-1.loc + 192.168.99.100 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms diff --git a/docs/howto/dns/add-project-dns-entry-on-linux.rst b/docs/howto/dns/add-project-dns-entry-on-linux.rst new file mode 100644 index 00000000..fcd6115e --- /dev/null +++ b/docs/howto/dns/add-project-dns-entry-on-linux.rst @@ -0,0 +1,65 @@ +:orphan: + +.. _howto_add_project_dns_entry_on_linux: + +****************************** +Add project DNS entry on Linux +****************************** + +On Linux, custom DNS entries can be added to the ``/etc/hosts`` and will take precedence over the +same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +In order to better illustrate the process, we are going to use two projects as an example. +See the following table for project directories and :ref:`env_tld_suffix`. + ++-------------------+------------+--------------------------+-----------------------+ +| Project directory | TLD_SUFFIX | Project URL | Required DNS name | ++===================+============+==========================+=======================+ +| project-1 | ``loc`` | http://project-1.loc | ``project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ +| www.project-1 | ``loc`` | http://www.project-1.loc | ``www.project-1.loc`` | ++-------------------+------------+--------------------------+-----------------------+ + +Step by step +------------ + +When using Docker on Linux you can use ``127.0.0.1`` for the IP address. + +1. Open ``/etc/hosts`` with root privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (127.0.0.1) 56(84) bytes of data. + 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms diff --git a/docs/index.rst b/docs/index.rst index 61142257..183c881e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -75,7 +75,7 @@ host is ready to be served with your custom domain. advanced/connect-to-host-os advanced/connect-to-other-docker-container advanced/connect-to-external-hosts - advanced/add-custom-cname-dns-entries + advanced/add-custom-cname-records advanced/add-your-own-docker-image advanced/overwrite-existing-docker-image @@ -95,6 +95,7 @@ host is ready to be served with your custom domain. :maxdepth: 2 :numbered: + corporate-usage/deploy-devilbox-via-ansible corporate-usage/shared-devilbox-server-in-lan corporate-usage/access-devilbox-from-android corporate-usage/access-devilbox-from-iphone