devilbox/docs/custom-container/enable-blackfire.rst

Enable and configure Blackfire

This section will guide you through getting Blackfire integrated into the Devilbox.

* * * custom_container_enable_all_additional_container * docker_compose_override_yml_how_does_it_work

Table of Contents

local

Overview

Available overwrites

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 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	latest	Controls the Blackfire version to use.
BLACKFIRE_SERVER_ID	id	A valid server id is required in order to start blackfire-agent.
BLACKFIRE_SERVER_TOKEN	token	A valid server token is required in order to start blackfire-agent.
BLACKFIRE_CLIENT_ID	id	A valid client id is required in order to use blackfire cli.
BLACKFIRE_CLIENT_TOKEN	token	A valid client token is required in order to use blackfire cli.

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).

host> cp compose/docker-compose.override.yml-blackfire docker-compose.override.yml

* docker_compose_override_yml * add_your_own_docker_image * overwrite_existing_docker_image

2. Adjust env settings

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.

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

You must also explicitly enable the PHP blackfire module and disable xdebug via .env

PHP_MODULES_ENABLE=blackfire
PHP_MODULES_DISABLE=xdebug

env_file

3. Copy blackfire php.ini template

In order for the PHP blackfire module to know where the blackfire-agent is listening, we must configure its PHP settings. There is already a default template that you can simply copy.

host> cp cfg/php-ini-7.2/devilbox-php.ini-blackfire cfg/php-ini-7.2/blackfire.ini

The above example shows the procedure for PHP 7.2, if you are using a different version, you must navigate to its corresponding configuration directory.

Read more here: php_ini

4. Configure blackfire cli (optional)

If you want to use the blackfire cli from within the PHP container, its configuration must be configured. There is already a startup template which does it for you.

You first need to add the Blackfire client id and token to .env:

BLACKFIRE_CLIENT_ID=<valid client id>
BLACKFIRE_CLIENT_TOKEN=<valid client token>

Then all that's left to do is to copy the startup script which configures the blackfire cli for you.

host> cp autostart/configure-blackfire-cli.sh-example autostart/configure-blackfire-cli.sh

* custom_scripts_globally

5. 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.

host> docker-compose up -d php httpd bind blackfire

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:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-blackfire docker-compose.override.yml

# Copy php.ini into place
cp cfg/php-ini-7.2/devilbox-php.ini-blackfire cfg/php-ini-7.2/blackfire.ini

# Set Blackfire server id and token
echo "BLACKFIRE_SERVER_ID=<valid server id>"       >> .env
echo "BLACKFIRE_SERVER_TOKEN=<valid server token>" >> .env

# Set Blackfire client id and token
echo "BLACKFIRE_CLIENT_ID=<valid client id>"       >> .env
echo "BLACKFIRE_CLIENT_TOKEN=<valid client 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

# Ensure blackfire is enabled and xdebug is disabled
# IMPORTANT: This replacement is only an example and will overwrite
#            all other enabled/disabled modules.
#            Do not do it this way.
sed -i'' 's/^PHP_MODULES_ENABLE=.*/PHP_MODULES_ENABLE=blackfire/g' .env
sed -i'' 's/^PHP_MODULES_DISABLE=.*/PHP_MODULES_ENABLE=xdebug/g' .env

# Start container
docker-compose up -d php httpd bind blackfire