Merge pull request #522 from cytopia/feature-ngrok

Feature ngrok

.devilbox/www/config.php

@@ -14,7 +14,7 @@ putenv('RES_OPTIONS=retrans:1 retry:1 timeout:1 attempts:1');
 
 
 $DEVILBOX_VERSION = 'v0.15';
-$DEVILBOX_DATE = '2019-03-04';
+$DEVILBOX_DATE = '2019-03-06';
 $DEVILBOX_API_PAGE = 'devilbox-api/status.json';
 
 //

CHANGELOG.md

@@ -41,6 +41,7 @@ major versions.
     - Blackfire
     - ELK (Elastic Search, Logstash and Kibana)
     - MailHog
+    - Ngrok
     - RabbitMQ
     - Solr
     - Varnish

README.md

@@ -88,7 +88,7 @@ Each of them is also available in multiple different versions in order to reflec
 | HAProxy | Apache     | MariaDB    | Memcached | RabbitMQ | Solr   | ElasticSearch | Bind      |
 | Varnish | Nginx      | MySQL      | MongoDB   |          |        | Logstash      | Blackfire |
 |         | PHP        | PerconaDB  | Redis     |          |        | Kibana        | MailHog   |
-|         |            | PostgreSQL |           |          |        |               |           |
+|         |            | PostgreSQL |           |          |        |               | Ngrok     |
 
 > **Documentation:**
 > [Available Container](https://devilbox.readthedocs.io/en/latest/readings/available-container.html)
@@ -363,6 +363,7 @@ Additionally to the default stack, there are a variety of other services that ca
    <th>Blackfire</th>
    <th>ELK</th>
    <th>MailHog</th>
+   <th>Ngrok</th>
    <th>RabbitMQ</th>
    <th>Solr</th>
    <th>HAProxy</th>
@@ -374,15 +375,17 @@ Additionally to the default stack, there are a variety of other services that ca
    <td><a target="_blank" title="Blackfire 1.8"    href="https://github.com/blackfireio/docker">1.8</a></td>
    <td><a target="_blank" title="ELK stack"        href="https://www.docker.elastic.co">5.x.y</a></td>
    <td><a target="_blank" title="MailHog v1.0.0"   href="https://github.com/mailhog/MailHog">v1.0.0</a></td>
+   <td><a target="_blank" title="Ngrok 2.x"        href="https://github.com/devilbox/docker-ngrok">2.x</a></td>
    <td><a target="_blank" title="RabbitMQ 3.6"     href="https://github.com/rabbitmq/rabbitmq-server">3.6</a></td>
    <td><a target="_blank" title="Solr 5"           href="https://github.com/apache/lucene-solr">5</a></td>
-   <td><a target="_blank" title="HAProxy 1.X"      href="https://github.com/devilbox/docker-haproxy">1.X</a></td>
+   <td><a target="_blank" title="HAProxy 1.x"      href="https://github.com/devilbox/docker-haproxy">1.x</a></td>
    <td><a target="_blank" title="Varnish 4"        href="https://github.com/devilbox/docker-varnish">4</a></td>
   </tr>
   <tr>
    <td>...</td>
    <td><a target="_blank" title="ELK stack"        href="https://www.docker.elastic.co">6.x.y</a></td>
    <td><a target="_blank" title="MailHog latest"   href="https://github.com/mailhog/MailHog">latest</a></td>
+   <td></td>
    <td><a target="_blank" title="RabbitMQ 3.7"     href="https://github.com/rabbitmq/rabbitmq-server">3.7</a></td>
    <td><a target="_blank" title="Solr 6"           href="https://github.com/apache/lucene-solr">6</a></td>
    <td></td>
@@ -392,6 +395,7 @@ Additionally to the default stack, there are a variety of other services that ca
    <td><a target="_blank" title="Blackfire 1.18.0" href="https://github.com/blackfireio/docker">1.18.0</a></td>
    <td><a target="_blank" title="ELK stack"        href="https://www.docker.elastic.co">7.x.y</a></td>
    <td></td>
+   <td></td>
    <td><a target="_blank" title="RabbitMQ latest"  href="https://github.com/rabbitmq/rabbitmq-server">latest</a></td>
    <td><a target="_blank" title="Solr 7"           href="https://github.com/apache/lucene-solr">7</a></td>
    <td></td>
@@ -402,6 +406,7 @@ Additionally to the default stack, there are a variety of other services that ca
    <td></td>
    <td></td>
    <td></td>
+   <td></td>
    <td><a target="_blank" title="Solr latest"      href="https://github.com/apache/lucene-solr">latest</a></td>
    <td></td>
    <td><a target="_blank" title="Varnish latest"   href="https://github.com/devilbox/docker-varnish">latest</a></td>

compose/docker-compose.override.yml-all

@@ -41,6 +41,25 @@ services:
       - php
       - httpd
 
+  # -----------------------------------------------------------------------------------------------
+  # Ngrok
+  # -----------------------------------------------------------------------------------------------
+  ngrok:
+    image: devilbox/ngrok:0.2
+    hostname: ngrok
+    environment:
+      - HTTP_TUNNELS=${NGROK_HTTP_TUNNELS:-httpd:httpd:80}
+      - AUTHTOKEN=${NGROK_AUTHTOKEN:-}
+    ports:
+      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_NGROK:-4040}:4040"
+    networks:
+      app_net:
+        ipv4_address: 172.16.238.202
+    depends_on:
+      - bind
+      - php
+      - httpd
+
   # -----------------------------------------------------------------------------------------------
   # RabbitMQ
   # -----------------------------------------------------------------------------------------------

compose/docker-compose.override.yml-ngrok

@@ -0,0 +1,23 @@
+# vim: set ft=yaml:
+version: '2.1'
+
+services:
+
+  # -----------------------------------------------------------------------------------------------
+  # Ngrok
+  # -----------------------------------------------------------------------------------------------
+  ngrok:
+    image: devilbox/ngrok:0.2
+    hostname: ngrok
+    environment:
+      - HTTP_TUNNELS=${NGROK_HTTP_TUNNELS:-httpd:httpd:80}
+      - AUTHTOKEN=${NGROK_AUTHTOKEN:-}
+    ports:
+      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_NGROK:-4040}:4040"
+    networks:
+      app_net:
+        ipv4_address: 172.16.238.202
+    depends_on:
+      - bind
+      - php
+      - httpd

docs/_includes/links/documentation.rst

@@ -40,6 +40,18 @@
      Dockerhub: MailHog <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
    </a>
 
+.. |ext_lnk_ngrok_github| raw:: html
+
+   <a target="_blank" href="https://github.com/devilbox/docker-ngrok">
+     Github: ngrok <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>
+
+.. |ext_lnk_ngrok_dockerhub| raw:: html
+
+   <a target="_blank" href="https://hub.docker.com/r/devilbox/ngrok/">
+     Dockerhub: ngrok <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>
+
 .. |ext_lnk_blackfire_github| raw:: html
 
    <a target="_blank" href="https://github.com/blackfireio/docker">

docs/_includes/snippets/additional-container.rst

@@ -5,6 +5,8 @@
 +-------------------------------------+-----------+-----------+----------------+
 | MailHog                             | mailhog   | mailhog   | 172.16.238.201 |
 +-------------------------------------+-----------+-----------+----------------+
+| Ngrok                               | ngrok     | ngrok     | 172.16.238.202 |
++-------------------------------------+-----------+-----------+----------------+
 | RabbitMQ                            | rabbit    | rabbit    | 172.16.238.210 |
 +-------------------------------------+-----------+-----------+----------------+
 | Solr                                | solr      | solr      | 172.16.238.220 |

docs/_includes/snippets/docker-compose-override-tree-view.rst

@@ -12,6 +12,7 @@ However, each example also exists in its standalone file as shown below:
    ├── docker-compose.override.yml-blackfire
    ├── docker-compose.override.yml-elk
    ├── docker-compose.override.yml-mailhog
+   ├── docker-compose.override.yml-ngrok
    ├── docker-compose.override.yml-rabbitmq
    ├── docker-compose.override.yml-solr
    ├── docker-compose.override.yml-varnish

docs/corporate-usage/showcase-over-the-internet.rst

@@ -0,0 +1,133 @@
+.. include:: /_includes/all.rst
+
+.. _showcase_over_the_internet:
+
+**************************
+Showcase over the internet
+**************************
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Why
+===
+
+Sometimes it is just convinient to make your local project available over the internet to quickly
+showcase your current work to a customer. Instead of having to deploy it somewhere and even be able
+to live code during the showcase the Devilbox provides an easy way to accomplish exactly this via
+Ngrok.
+
+
+How
+===
+
+First you want to add Ngrok to the Devilbox stack via its pre-defined Docker Compose override file.
+
+.. seealso::    * :ref:`custom_container_enable_ngrok`
+
+Once you have followed the above documentation everything works with default settings. To actually
+customize and choose the virtual host to expose you will need to alter the ``NGROK_HTTP_TUNNELS``
+.env variable.
+
+How this can be done exactly will be shown in a couple of examples below.
+
+Examples
+--------
+
+Recall the following formats for the variable:
+
+* ``<domain.tld>:<addr>:<port>``
+* ``<domain1.tld>:<addr>:<port>,<domain2.tld>:<addr>:<port>``
+
+.. note:: Even more than two tunnels are supported, but this will again depend on your Ngrok license.
+
+Where each individual part consists of:
+
+* ``<domain.tld>`` is the virtual hostname that you want to serve via Ngrok
+* ``<addr>`` is the hostname or IP address of the web server
+* ``<port>`` is the port on which the web server is reachable via HTTP
+
+Expose ``my-project.loc`` via web server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``<domain.tld>``: my-project.loc
+* ``<addr>``: httpd
+* ``<port>``: httpd80
+
+So the resulting ``.env`` value will be:
+
+.. code-block:: bash
+
+   NGROK_HTTP_TUNNELS=my-project.loc:httpd:80
+
+Expose ``my-project.loc`` via Varnish
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``<domain.tld>``: my-project.loc
+* ``<addr>``: varnish
+* ``<port>``: 6081
+
+So the resulting ``.env`` value will be:
+
+.. code-block:: bash
+
+   NGROK_HTTP_TUNNELS=my-project.loc:varnish:6081
+
+Expose ``my-project.loc`` via HAProxy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* ``<domain.tld>``: my-project.loc
+* ``<addr>``: haproxy
+* ``<port>``: 80
+
+So the resulting ``.env`` value will be:
+
+.. code-block:: bash
+
+   NGROK_HTTP_TUNNELS=my-project.loc:haproxy:80
+
+
+Expose ``my-project.loc`` and ``website1.loc`` via web server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: Exposing more than one vhost will require a pro enough license from Ngrok.
+
+* ``<domain.tld>``: my-project.loc
+* ``<addr>``: httpd
+* ``<port>``: 80
+
+and
+
+* ``<domain.tld>``: website1.loc
+* ``<addr>``: httpd
+* ``<port>``: 80
+
+
+So the resulting ``.env`` value will be:
+
+.. code-block:: bash
+
+   NGROK_HTTP_TUNNELS=my-project.loc:httpd:80,website1.loc:httpd:80
+
+Expose ``my-project.loc`` via web server and varnish
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: Exposing more than one vhost will require a pro enough license from Ngrok.
+
+* ``<domain.tld>``: my-project.loc
+* ``<addr>``: httpd
+* ``<port>``: 80
+
+and
+
+
+* ``<domain.tld>``: my-project.loc
+* ``<addr>``: varnish
+* ``<port>``: 6081
+
+So the resulting ``.env`` value will be:
+
+.. code-block:: bash
+
+   NGROK_HTTP_TUNNELS=my-project.loc:httpd:80,my-project.loc:varnish:6081

docs/custom-container/enable-all-container.rst

@@ -58,6 +58,7 @@ In order to fully customize each container, refer to their own documentation sec
    * :ref:`custom_container_enable_blackfire`
    * :ref:`custom_container_enable_elk_stack`
    * :ref:`custom_container_enable_mailhog`
+   * :ref:`custom_container_enable_ngrok`
    * :ref:`custom_container_enable_rabbitmq`
    * :ref:`custom_container_enable_solr`
    * :ref:`custom_container_enable_varnish`

docs/custom-container/enable-ngrok.rst

@@ -0,0 +1,186 @@
+.. include:: /_includes/all.rst
+
+.. _custom_container_enable_ngrok:
+
+**************************
+Enable and configure Ngrok
+**************************
+
+This section will guide you through getting Ngrok integrated into the Devilbox.
+
+.. seealso::
+   * |ext_lnk_ngrok_github|
+   * |ext_lnk_ngrok_dockerhub|
+   * :ref:`custom_container_enable_all_additional_container`
+   * :ref:`docker_compose_override_yml_how_does_it_work`
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Overview
+========
+
+Available overwrites
+--------------------
+
+.. include:: /_includes/snippets/docker-compose-override-tree-view.rst
+
+
+Ngrok settings
+--------------
+
+In case of Ngrok, the file is ``compose/docker-compose.override.yml-ngrok``. This file
+must be copied into the root of the Devilbox git directory.
+
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| What                  | How and where                                                                                       |
++=======================+=====================================================================================================+
+| Example compose file  | ``compose/docker-compose.override.yml-all`` or |br| ``compose/docker-compose.override.yml-ngrok``   |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Container IP address  | ``172.16.238.202``                                                                                  |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Container host name   | ``ngrok``                                                                                           |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Container name        | ``ngrok``                                                                                           |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Mount points          | none                                                                                                |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Exposed port          | ``4040`` (can be changed via ``.env``)                                                              |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Available at          | ``http://localhost:4040``                                                                           |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+| Further configuration | ``NGROK_HTTP_TUNNELS`` and ``NGROK_AUTHTOKEN``                                                      |
++-----------------------+-----------------------------------------------------------------------------------------------------+
+
+Ngrok env variables
+-------------------
+
+Additionally the following ``.env`` variables can be created for easy configuration:
+
++------------------------------+--------------------+----------------------------------------------------------------------+
+| Variable                     | Default value      | Description                                                          |
++==============================+====================+======================================================================+
+| ``HOST_PORT_NGROK``          | ``4040``           | Controls the host port on which Ngrok admin UI will be available at. |
++------------------------------+--------------------+----------------------------------------------------------------------+
+| ``NGROK_HTTP_TUNNELS``       | ``httpd:httpd:80`` | Defines one or more Ngrok tunnels (depending on your license)        |
++------------------------------+--------------------+----------------------------------------------------------------------+
+| ``NGROK_AUTHTOKEN``          | empty              | Free or paid license token for Ngrok (can also be empty)             |
++------------------------------+--------------------+----------------------------------------------------------------------+
+
+NGROK_HTTP_TUNNELS
+^^^^^^^^^^^^^^^^^^
+
+Ngrok tunnel definitions can be in the form of:
+
+* ``<domain.tld>:<addr>:<port>``
+* ``<domain1.tld>:<addr>:<port>,<domain2.tld>:<addr>:<port>``
+
+.. note::
+   If you don't use a license you can only specify a single tunnel. If your license is pro enough,
+   you can have multiple comma separated tunnels.
+
+* ``<domain.tld>`` is the virtual hostname that you want to serve via Ngrok
+* ``<addr>`` is the hostname or IP address of the web server
+* ``<port>`` is the port on which the web server is reachable via HTTP
+
+.. code-block:: bash
+
+   # Make vhost "project1.loc" which runs on localhost:8080 available
+   HTTP_TUNNELS=project1.loc:localhost:8080
+
+   # Make two vhosts available which run on host apache:80
+   HTTP_TUNNELS=project1.loc:apache:80,project2.loc:apache:80
+
+   # Make two vhosts from two different web server addresses available
+   HTTP_TUNNELS=project1.loc:localhost:8080,project2.loc:apache:80
+
+
+Instructions
+============
+
+1. Copy docker-compose.override.yml
+-----------------------------------
+
+Copy the Ngrok Docker Compose overwrite file into the root of the Devilbox git directory.
+(It must be at the same level as the default ``docker-compose.yml`` file).
+
+.. code-block:: bash
+
+   host> cp compose/docker-compose.override.yml-ngrok docker-compose.override.yml
+
+.. seealso::
+   * :ref:`docker_compose_override_yml`
+   * :ref:`add_your_own_docker_image`
+   * :ref:`overwrite_existing_docker_image`
+
+
+2. Adjust ``.env`` settings (optional)
+--------------------------------------
+
+By Default Ngrok will forward the ``httpd`` domain, which is represents the default virtual host
+(the Devilbox intranet) to your web server (also named ``httpd``) and makes the admin UI available
+on port ``4040`` on your local machine.
+
+You can of course change the domain as well as where to forward it to (e.g.: to Varnish or HAProxy
+instead).
+
+Additionally you can also specify a license token in order to allow for more tunnels via
+``NGROK_AUTHTOKEN``.
+
+.. code-block:: bash
+   :caption: .env
+
+   HOST_PORT_NGROK=4040
+   # Share project1.loca over the internet
+   NGROK_HTTP_TUNNELS=project1.loc:httpd:80
+   # No license token specified
+   NGROK_AUTHTOKEN=
+
+.. seealso:: :ref:`env_file`
+
+
+3. Start the Devilbox
+---------------------
+
+The final step is to start the Devilbox with Ngrok.
+
+Let's assume you want to start ``php``, ``httpd``, ``bind`` and ``ngrok``.
+
+.. code-block:: bash
+
+   host> docker-compose up -d php httpd bind ngrok
+
+.. seealso:: :ref:`start_the_devilbox`
+
+
+4. Start using it
+-----------------
+
+* Once the Devilbox is running, visit http://localhost:4040 in your browser.
+* Get URL for public available project
+
+
+TL;DR
+=====
+
+For the lazy readers, here are all commands required to get you started.
+Simply copy and paste the following block into your terminal from the root of your Devilbox git
+directory:
+
+.. code-block:: bash
+
+   # Copy compose-override.yml into place
+   cp compose/docker-compose.override.yml-ngrok docker-compose.override.yml
+
+   # Create .env variable
+   echo "HOST_PORT_NGROK=4040"                      >> .env
+   echo "# Share project1.loca over the internet"   >> .env
+   echo "NGROK_HTTP_TUNNELS=project1.loc:httpd:80"  >> .env
+   echo "# No license token specified"              >> .env
+   echo "NGROK_AUTHTOKEN="                          >> .env
+
+   # Start container
+   docker-compose up -d php httpd bind ngrok

docs/index.rst

@@ -121,6 +121,7 @@ host is ready to be served with your custom domain.
    custom-container/enable-blackfire
    custom-container/enable-elk-stack
    custom-container/enable-mailhog
+   custom-container/enable-ngrok
    custom-container/enable-rabbitmq
    custom-container/enable-solr
    custom-container/enable-varnish
@@ -132,6 +133,7 @@ host is ready to be served with your custom domain.
 
    corporate-usage/shared-devilbox-server-in-lan
    corporate-usage/use-external-databases
+   corporate-usage/showcase-over-the-internet
 ..
    corporate-usage/deploy-devilbox-via-ansible
    corporate-usage/access-colleagues-devilbox