Merge pull request #358 from cytopia/docker-blackfire

Adding new container: Blackfire

README.md

@@ -45,11 +45,11 @@ Furthermore, the Devilbox provides an **identical** and **reproducable developme
 The Devilbox ships the following pre-configured Docker container in any available version.
 
 | Web server | SQL        | NoSQL     | Queue & Search | Misc      |
-|------------|------------|-----------|----------------|---------|
+|------------|------------|-----------|----------------|-----------|
 | Apache     | MariaDB    | Memcached | RabbitMQ       | Bind      |
-| Nginx      | MySQL      | MongoDB   | Solr           | MailHog |
+| Nginx      | MySQL      | MongoDB   | Solr           | Blackfire |
-|            | PerconaDB  | Redis     |                | PHP     |
+|            | PerconaDB  | Redis     |                | MailHog   |
-|            | PostgreSQL |           |                |         |
+|            | PostgreSQL |           |                | PHP       |
 
 > **Documentation:**
 > [Available Container](https://devilbox.readthedocs.io/en/latest/readings/available-container.html)
@@ -101,8 +101,8 @@ Find documentation and help here
 <table width="100%" style="width:100%; display:table;">
  <thead>
   <tr>
-   <th width="50%" style="width:33%;">Linux and MacOS</th>
+   <th width="50%" style="width:50%;">Linux and MacOS</th>
-   <th width="50%" style="width:33%;">Windows</th>
+   <th width="50%" style="width:50%;">Windows</th>
   </tr>
  </thead>
  <tbody style="vertical-align: bottom;">
@@ -293,6 +293,7 @@ Additionally to the default stack, there are a variety of other services that ca
 <table>
  <thead>
   <tr>
+   <th>Blackfire</th>
    <th>MailHog</th>
    <th>RabbitMQ</th>
    <th>Solr</th>
@@ -300,21 +301,25 @@ Additionally to the default stack, there are a variety of other services that ca
  </thead>
  <tbody>
   <tr>
+   <td><a target="_blank" title="Blackfire 1.8"    href="https://github.com/blackfireio/docker">1.8</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="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>
   </tr>
   <tr>
+   <td>...</td>
    <td><a target="_blank" title="MailHog latest"   href="https://github.com/mailhog/MailHog">latest</a></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>
   </tr>
   <tr>
+   <td><a target="_blank" title="Blackfire 1.18.0" href="https://github.com/blackfireio/docker">1.18.0</a></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>
   </tr>
   <tr>
+   <td><a target="_blank" title="Blackfire latest" href="https://github.com/blackfireio/docker">latest</a></td>
    <td></td>
    <td></td>
    <td><a target="_blank" title="Solr latest"      href="https://github.com/apache/lucene-solr">latest</a></td>

compose/docker-compose.override.yml-all

@@ -2,6 +2,20 @@ version: '2.1'
 
 services:
 
+  blackfire:
+    image: blackfire/blackfire:${BLACKFIRE:-latest}
+    hostname: blackfire
+    environment:
+      - BLACKFIRE_SERVER_ID=${BLACKFIRE_SERVER_ID:-id}
+      - BLACKFIRE_SERVER_TOKEN=${BLACKFIRE_SERVER_TOKEN:-token}
+    networks:
+      app_net:
+        ipv4_address: 172.16.238.200
+    depends_on:
+      - bind
+      - php
+      - httpd
+
   mailhog:
     image: mailhog/mailhog:${MAILHOG_SERVER:-latest}
     hostname: mailhog
@@ -9,7 +23,7 @@ services:
       - "${LOCAL_LISTEN_ADDR}${HOST_PORT_MAILHOG:-8025}:8025"
     networks:
       app_net:
-        ipv4_address: 172.16.238.200
+        ipv4_address: 172.16.238.201
     depends_on:
       - bind
       - php

compose/docker-compose.override.yml-blackfire

@@ -0,0 +1,16 @@
+version: '2.1'
+
+services:
+  blackfire:
+    image: blackfire/blackfire:${BLACKFIRE:-latest}
+    hostname: blackfire
+    environment:
+      - BLACKFIRE_SERVER_ID=${BLACKFIRE_SERVER_ID:-id}
+      - BLACKFIRE_SERVER_TOKEN=${BLACKFIRE_SERVER_TOKEN:-token}
+    networks:
+      app_net:
+        ipv4_address: 172.16.238.200
+    depends_on:
+      - bind
+      - php
+      - httpd

compose/docker-compose.override.yml-mailhog

@@ -8,7 +8,7 @@ services:
       - "${LOCAL_LISTEN_ADDR}${HOST_PORT_MAILHOG:-8025}:8025"
     networks:
       app_net:
-        ipv4_address: 172.16.238.200
+        ipv4_address: 172.16.238.201
     depends_on:
       - bind
       - php

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_blackfire_github| raw:: html
+
+   <a target="_blank" href="https://github.com/blackfireio/docker">
+     Github: Blackfire <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>
+
+.. |ext_lnk_blackfire_dockerhub| raw:: html
+
+   <a target="_blank" href="https://hub.docker.com/r/blackfire/blackfire/">
+     Dockerhub: Blackfire <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>
+
 .. |ext_lnk_rabbitmq_github| raw:: html
 
    <a target="_blank" href="https://github.com/rabbitmq/rabbitmq-server">

docs/_includes/snippets/additional-container.rst

@@ -1,9 +1,11 @@
-+---------------------------+----------+----------+----------------+
++---------------------------+-----------+-----------+----------------+
 | Container                 | Name      | Hostname  | IP Address     |
-+===========================+==========+==========+================+
++===========================+===========+===========+================+
-| MailHog                   | mailhog  | mailhog  | 172.16.238.200 |
+| Blackfire                 | blackfire | blackfire | 172.16.238.200 |
-+---------------------------+----------+----------+----------------+
++---------------------------+-----------+-----------+----------------+
+| MailHog                   | mailhog   | mailhog   | 172.16.238.201 |
++---------------------------+-----------+-----------+----------------+
 | RabbitMQ                  | rabbit    | rabbit    | 172.16.238.210 |
-+---------------------------+----------+----------+----------------+
++---------------------------+-----------+-----------+----------------+
 | Solr                      | solr      | solr      | 172.16.238.220 |
-+---------------------------+----------+----------+----------------+
++---------------------------+-----------+-----------+----------------+

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

@@ -9,11 +9,12 @@ However, each example also exists in its standalone file as shown below:
    host> tree -L 1 compose/
    compose/
    ├── docker-compose.override.yml-all
+   ├── docker-compose.override.yml-blackfire
    ├── docker-compose.override.yml-mailhog
    ├── docker-compose.override.yml-rabbitmq
    ├── docker-compose.override.yml-solr
    └── README.md
 
-   0 directories, 5 files
+   0 directories, 6 files
 
 .. seealso:: :ref:`custom_container_enable_all_additional_container`

docs/advanced/add-your-own-docker-image.rst

@@ -126,7 +126,7 @@ Docker image:
 1. Name: ``cockroach``
 2. Image: ``cockroachdb/cockroach``
 3. Tag: ``latest``
-4. IP: ``172.16.238.200``
+4. IP: ``172.16.238.240``
 
 Now add the information to ``docker-compose.override.yml``:
 
@@ -142,7 +142,7 @@ Now add the information to ``docker-compose.override.yml``:
        command: start --insecure
        networks:
          app_net:
-           ipv4_address: 172.16.238.200
+           ipv4_address: 172.16.238.240
        # For ease of use always automatically start these:
        depends_on:
          - bind

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

@@ -53,6 +53,7 @@ That includes, but is not limited to:
 In order to fully customize each container, refer to their own documentation section:
 
 .. seealso::
+   * :ref:`custom_container_enable_blackfire`
    * :ref:`custom_container_enable_mailhog`
    * :ref:`custom_container_enable_rabbitmq`
    * :ref:`custom_container_enable_solr`

docs/custom-container/enable-blackfire.rst

@@ -0,0 +1,161 @@
+.. include:: /_includes/all.rst
+
+.. _custom_container_enable_blackfire:
+
+******************************
+Enable and configure Blackfire
+******************************
+
+This section will guide you through getting Blackfire integrated into the Devilbox.
+
+.. seealso::
+   * |ext_lnk_blackfire_github|
+   * |ext_lnk_blackfire_dockerhub|
+   * :ref:`custom_container_enable_all_additional_container`
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Overview
+========
+
+Available overwrites
+--------------------
+
+.. include:: /_includes/snippets/docker-compose-override-tree-view.rst
+
+
+Blackfire settings
+------------------
+
+In case of Blackfire, the file is ``compose/docker-compose.override.yml-blackfire``. 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-blackfire`` |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Container IP address  | ``172.16.238.200``                                                                                    |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Container host name   | ``blackfire``                                                                                         |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Container name        | ``blackfire``                                                                                         |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Mount points          | none                                                                                                  |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Exposed port          | none                                                                                                  |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Available at          | n.a.                                                                                                  |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+| Further configuration | ``BLACKFIRE_SERVER_ID`` and ``BLACKFIRE_SERVER_TOKEN`` must be set via ``.env``                       |
++-----------------------+-------------------------------------------------------------------------------------------------------+
+
+Blackfire env variables
+-----------------------
+
+Additionally the following ``.env`` variables can be created for easy configuration:
+
++------------------------------+---------------+---------------------------------------------------------------+
+| Variable                     | Default value | Description                                                   |
++==============================+===============+===============================================================+
+| ``BLACKFIRE_SERVER_ID``      | ``id``        | A valid server id is required in order to use blackfire.      |
++------------------------------+---------------+---------------------------------------------------------------+
+| ``BLACKFIRE_SERVER_TOKEN``   | ``token``     | A valid server token is required in order to use blackfire.   |
++------------------------------+---------------+---------------------------------------------------------------+
+| ``BLACKFIRE_SERVER``         | ``latest``    | Controls the Blackfire version to use.                        |
++------------------------------+---------------+---------------------------------------------------------------+
+
+
+Instructions
+============
+
+1. Copy docker-compose.override.yml
+-----------------------------------
+
+Copy the Blackfire 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-blackfire 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 (required)
+-------------------------------------
+
+By default Blackfire is using some dummy values for BLACKFIRE_SERVER_ID and BLACKFIRE_SERVER_TOKEN.
+You must however aquire valid values and set the in your ``.env`` file in order for Blackfire
+to properly start. Those values can be obtained at their official webpage.
+
+.. code-block:: bash
+   :caption: .env
+
+   BLACKFIRE_SERVER_ID=<valid server id>
+   BLACKFIRE_SERVER_TOKEN=<valid server token>
+
+   #BLACKFIRE_SERVER=1.12.0
+   #BLACKFIRE_SERVER=1.13.0
+   #BLACKFIRE_SERVER=1.14.0
+   #BLACKFIRE_SERVER=1.14.1
+   #BLACKFIRE_SERVER=1.15.0
+   #BLACKFIRE_SERVER=1.16.0
+   #BLACKFIRE_SERVER=1.17.0
+   #BLACKFIRE_SERVER=1.17.1
+   #BLACKFIRE_SERVER=1.18.0
+   BLACKFIRE_SERVER=latest
+
+.. seealso:: :ref:`env_file`
+
+
+3. Start the Devilbox
+---------------------
+
+The final step is to start the Devilbox with Blackfire.
+
+Let's assume you want to start ``php``, ``httpd``, ``bind`` and ``blackfire``.
+
+.. code-block:: bash
+
+   host> docker-compose up -d php httpd bind blackfire
+
+.. seealso:: :ref:`start_the_devilbox`
+
+
+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-blackfire docker-compose.override.yml
+
+   # Create .env variable
+   echo "BLACKFIRE_SERVER_ID=<valid server id>"       >> .env
+   echo "BLACKFIRE_SERVER_TOKEN=<valid server token>" >> .env
+
+   echo "#BLACKFIRE_SERVER=1.12.0"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.13.0"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.14.0"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.14.1"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.15.0"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.16.0"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.17.0"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.17.1"                    >> .env
+   echo "#BLACKFIRE_SERVER=1.18.0"                    >> .env
+   echo "BLACKFIRE_SERVER=latest"                     >> .env
+
+   # Start container
+   docker-compose up -d php httpd bind blackfire

docs/custom-container/enable-mailhog.rst

@@ -39,7 +39,7 @@ must be copied into the root of the Devilbox git directory.
 +=======================+=====================================================================================================+
 | Example compose file  | ``compose/docker-compose.override.yml-all`` or |br| ``compose/docker-compose.override.yml-mailhog`` |
 +-----------------------+-----------------------------------------------------------------------------------------------------+
-| Container IP address  | ``172.16.238.200``                                                                                  |
+| Container IP address  | ``172.16.238.201``                                                                                  |
 +-----------------------+-----------------------------------------------------------------------------------------------------+
 | Container host name   | ``mailhog``                                                                                         |
 +-----------------------+-----------------------------------------------------------------------------------------------------+

docs/index.rst

@@ -94,6 +94,7 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
 
    custom-container/enable-all-container
+   custom-container/enable-blackfire
    custom-container/enable-mailhog
    custom-container/enable-rabbitmq
    custom-container/enable-solr

docs/readings/available-container.rst

@@ -49,5 +49,7 @@ computer unresponsive.
 
 .. seealso::
    * :ref:`custom_container_enable_all_additional_container`
+   * :ref:`custom_container_enable_blackfire`
    * :ref:`custom_container_enable_mailhog`
    * :ref:`custom_container_enable_rabbitmq`
+   * :ref:`custom_container_enable_solr`