Fix #202 Document MailHog integration

compose/README.md

@@ -0,0 +1,3 @@
+# Docker Compose overwrites
+
+This directory container various `docker-compose.override.yml` examples to be used with the Devilbox.

compose/docker-compose.override.yml-mailhog

@@ -0,0 +1,15 @@
+version: '2.1'
+
+services:
+  mailhog:
+    hostname: mailhog
+    image: mailhog/mailhog:latest
+    ports:
+      - "${LOCAL_LISTEN_ADDR}8025:8025"
+    networks:
+      app_net:
+        ipv4_address: 172.16.238.201
+    depends_on:
+      - bind
+      - php
+      - httpd

docs/_includes/links/tools.rst

@@ -296,3 +296,15 @@
    <a target="_blank" href="https://github.com/devilbox/watcherp">
      watcherp <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
    </a>
+
+
+..
+   ============================================================
+   Additional container
+   ============================================================
+
+.. |ext_lnk_container_mailhog| raw:: html
+
+   <a target="_blank" href="https://github.com/mailhog/MailHog">
+     MailHog <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>

docs/custom-container/integrate-mailhog.rst

@@ -0,0 +1,108 @@
+.. include:: /_includes/all.rst
+
+.. _custom_container_ingegrate_mailhog:
+
+*****************
+Integrate Mailhog
+*****************
+
+This section will guide you through getting Mailhog integrated into the Devilbox.
+
+.. seealso:: |ext_lnk_container_mailhog|
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Overview
+========
+
+The Devilbox ships various example configurations to overwrite the default stack. Those files are
+located under ``compose/`` in the Devilbox git directory.
+
+In case of Mailhog, the file is ``compose/docker-compose.override.yml-mailhog``. 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-mailhog`` |
++-----------------------+-------------------------------------------------+
+| Container IP address  | ``172.16.238.201``                              |
++-----------------------+-------------------------------------------------+
+| Exposed port          | ``8025``                                        |
++-----------------------+-------------------------------------------------+
+| Available at          | ``http://localhost:8025``                       |
++-----------------------+-------------------------------------------------+
+| Container name        | ``mailhog``                                     |
++-----------------------+-------------------------------------------------+
+| Further configuration | php.ini settings need to be applied per version |
++-----------------------+-------------------------------------------------+
+
+
+Instructions
+============
+
+Copy example docker-compose.override.yml
+----------------------------------------
+
+Copy the mailhog Docker Compose overwrite file into the root of the Devilbox git directory.
+
+.. code-block:: bash
+
+   host> cp compose/docker-compose.override.yml-mailhog docker-compose.override.yml
+
+.. seealso::
+   * :ref:`docker_compose_override_yml`
+   * :ref:`add_your_own_docker_image`
+   * :ref:`overwrite_existing_docker_image`
+
+
+Adjust PHP settings
+-------------------
+
+The next step is to tell PHP that it should use a different mail forwarder.
+
+Let's assume you are using PHP 7.2.
+
+
+.. code-block:: bash
+
+   # Navigate to the PHP ini configuration directory of your chosen version
+   host> cd cfg/php-ini-7.2
+
+   # Create and open a new *.ini file
+   host> vi mailhog.ini
+
+Add the following content to the newly created ini file:
+
+.. code-block:: ini
+   :caption: mailhog.ini
+
+   [mail function]
+   sendmail_path = '/usr/local/bin/mhsendmail --smtp-addr="mailhog:1025"'
+
+.. seealso:: :ref:`php_ini`
+
+
+Start the Devilbox
+------------------
+
+The final step is to start the Devilbox with mailhog.
+
+Let's assume you want to start ``php``, ``httpd``, ``bind``, ``mysql`` and ``mailhog``.
+
+.. code-block:: bash
+
+   host> docker-compose up -d php httpd bind mysql mailhog
+
+.. seealso:: :ref:`start_the_devilbox`
+
+
+Functionality
+-------------
+
+* Once the Devilbox is running, visit http://localhost:8025 in your browser.
+* Any email send by any of the Devilbox managed projects will then appear in Mailhog

docs/index.rst

@@ -83,18 +83,22 @@ host is ready to be served with your custom domain.
 .. toctree::
    :caption: vhost-gen
    :maxdepth: 2
-   :numbered:
 
    vhost-gen/virtual-host-templates
    vhost-gen/customize-all-virtual-hosts-globally
    vhost-gen/customize-specific-virtual-host
    vhost-gen/example-add-subdomains
 
+.. toctree::
+   :caption: Add custom container
+   :maxdepth: 2
+
+   custom-container/integrate-mailhog
+
 
 .. toctree::
    :caption: Corporate Usage
    :maxdepth: 2
-   :numbered:
 
    corporate-usage/shared-devilbox-server-in-lan
    corporate-usage/use-external-databases