ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-01-18 18:56:25 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

\#453 Add Ngrok Documentation

Browse Source
This commit is contained in:
cytopia 2019-03-06 14:10:04 +01:00
parent a7133dd6ed
commit bc987a5663
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
8 changed files with 344 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.md
View File

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

12
docs/_includes/links/documentation.rst
View File

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

2
docs/_includes/snippets/additional-container.rst
View File

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

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

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

133
docs/corporate-usage/showcase-over-the-internet.rst Normal file
View File

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

1
docs/custom-container/enable-all-container.rst
View File

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

186
docs/custom-container/enable-ngrok.rst Normal file
View File

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

2
docs/index.rst
View File

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