diff --git a/.devilbox/www/config.php b/.devilbox/www/config.php index 5aaa81962..86668cf71 100644 --- a/.devilbox/www/config.php +++ b/.devilbox/www/config.php @@ -14,7 +14,7 @@ $DEVILBOX_VERSION = 'v0.15'; -$DEVILBOX_DATE = '2019-03-04'; +$DEVILBOX_DATE = '2019-03-06'; $DEVILBOX_API_PAGE = 'devilbox-api/status.json'; // diff --git a/CHANGELOG.md b/CHANGELOG.md index c861da170..d7562cce4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,7 @@ major versions. - Blackfire - ELK (Elastic Search, Logstash and Kibana) - MailHog + - Ngrok - RabbitMQ - Solr - Varnish diff --git a/README.md b/README.md index 6b304eecd..f6a9839fd 100644 --- a/README.md +++ b/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 Blackfire ELK MailHog + Ngrok RabbitMQ Solr HAProxy @@ -374,15 +375,17 @@ Additionally to the default stack, there are a variety of other services that ca 1.8 5.x.y v1.0.0 + 2.x 3.6 5 - 1.X + 1.x 4 ... 6.x.y latest + 3.7 6 @@ -392,6 +395,7 @@ Additionally to the default stack, there are a variety of other services that ca 1.18.0 7.x.y + latest 7 @@ -402,6 +406,7 @@ Additionally to the default stack, there are a variety of other services that ca + latest latest diff --git a/compose/docker-compose.override.yml-all b/compose/docker-compose.override.yml-all index 5d7bd8609..ef4c64b83 100644 --- a/compose/docker-compose.override.yml-all +++ b/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 # ----------------------------------------------------------------------------------------------- diff --git a/compose/docker-compose.override.yml-ngrok b/compose/docker-compose.override.yml-ngrok new file mode 100644 index 000000000..55b4e2827 --- /dev/null +++ b/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 diff --git a/docs/_includes/links/documentation.rst b/docs/_includes/links/documentation.rst index a4b6f9514..9e3e31a8d 100644 --- a/docs/_includes/links/documentation.rst +++ b/docs/_includes/links/documentation.rst @@ -40,6 +40,18 @@ Dockerhub: MailHog +.. |ext_lnk_ngrok_github| raw:: html + + + Github: ngrok + + +.. |ext_lnk_ngrok_dockerhub| raw:: html + + + Dockerhub: ngrok + + .. |ext_lnk_blackfire_github| raw:: html diff --git a/docs/_includes/snippets/additional-container.rst b/docs/_includes/snippets/additional-container.rst index 06142b721..b3b8f8b14 100644 --- a/docs/_includes/snippets/additional-container.rst +++ b/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 | diff --git a/docs/_includes/snippets/docker-compose-override-tree-view.rst b/docs/_includes/snippets/docker-compose-override-tree-view.rst index 00b0d6159..688d740ba 100644 --- a/docs/_includes/snippets/docker-compose-override-tree-view.rst +++ b/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 diff --git a/docs/corporate-usage/showcase-over-the-internet.rst b/docs/corporate-usage/showcase-over-the-internet.rst new file mode 100644 index 000000000..cad6d128d --- /dev/null +++ b/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: + +* ``::`` +* ``::,::`` + +.. note:: Even more than two tunnels are supported, but this will again depend on your Ngrok license. + +Where each individual part consists of: + +* ```` is the virtual hostname that you want to serve via Ngrok +* ```` is the hostname or IP address of the web server +* ```` is the port on which the web server is reachable via HTTP + +Expose ``my-project.loc`` via web server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ````: my-project.loc +* ````: httpd +* ````: 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ````: my-project.loc +* ````: varnish +* ````: 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* ````: my-project.loc +* ````: haproxy +* ````: 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. + +* ````: my-project.loc +* ````: httpd +* ````: 80 + +and + +* ````: website1.loc +* ````: httpd +* ````: 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. + +* ````: my-project.loc +* ````: httpd +* ````: 80 + +and + + +* ````: my-project.loc +* ````: varnish +* ````: 6081 + +So the resulting ``.env`` value will be: + +.. code-block:: bash + + NGROK_HTTP_TUNNELS=my-project.loc:httpd:80,my-project.loc:varnish:6081 diff --git a/docs/custom-container/enable-all-container.rst b/docs/custom-container/enable-all-container.rst index 516b29067..e1e5c1f40 100644 --- a/docs/custom-container/enable-all-container.rst +++ b/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` diff --git a/docs/custom-container/enable-ngrok.rst b/docs/custom-container/enable-ngrok.rst new file mode 100644 index 000000000..229472486 --- /dev/null +++ b/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: + +* ``::`` +* ``::,::`` + +.. 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. + +* ```` is the virtual hostname that you want to serve via Ngrok +* ```` is the hostname or IP address of the web server +* ```` 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 diff --git a/docs/index.rst b/docs/index.rst index 135e9af51..fcc5e6a11 100644 --- a/docs/index.rst +++ b/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