ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2024-12-23 14:42:25 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Shared Devilbox server in LAN

Browse Source
This commit is contained in:
cytopia 2018-07-08 09:26:52 +02:00
parent 1725de8c48
commit 04250f2fc3
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
12 changed files with 628 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
docs/advanced/add-custom-cname-dns-entries.rst
View File

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

42
docs/advanced/add-custom-cname-records.rst Normal file
View File

@ -0,0 +1,42 @@
.. _add_custom_cname_records:
****************************
Add custom CNAME DNS entries
****************************
You can add an infinite number of custom
`CNAME <https://en.wikipedia.org/wiki/CNAME_record>`_ 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.

2
docs/corporate-usage/access-devilbox-from-android.rst
View File

@ -3,3 +3,5 @@ Access Devilbox from Android
****************************
TODO
just run second bind server and hook it up via dhcp or custom app

3
docs/corporate-usage/access-devilbox-from-iphone.rst
View File

@ -3,3 +3,6 @@ Access Devilbox from iPhone
***************************
TODO
just run second bind server and hook it up via dhcp or custom app

5
docs/corporate-usage/deploy-devilbox-via-ansible.rst Normal file
View File

@ -0,0 +1,5 @@
***************************
Deploy Devilbox via Ansible
***************************
TODO

174
docs/corporate-usage/shared-devilbox-server-in-lan.rst
View File

@ -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 <branch>`` 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 <https://en.wikipedia.org/wiki/Small_office/home_office>`_ 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 <https://en.avm.de/service/fritzbox/fritzbox-7390/knowledge-base/publication/show/165_Configuring-different-DNS-servers-in-the-FRITZ-Box/>`_
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`

17
docs/getting-started/prerequisites.rst
View File

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

109
docs/howto/dns/add-custom-dns-server-on-linux.rst Normal file
View File

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

109
docs/howto/dns/add-custom-dns-server-on-mac.rst Normal file
View File

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

103
docs/howto/dns/add-custom-dns-server-on-win.rst Normal file
View File

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

65
docs/howto/dns/add-project-dns-entry-on-linux.rst Normal file
View File

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

3
docs/index.rst
View File

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