1. Documentation
  2. Getting Up and Running
  3. Docker

Docker

If you are using Docker, you might want to use the official Blackfire Docker image to run the Agent and get some inspiration from our recipes to install the Client and the Probe.

To ease the process of using Blackfire with Docker, define these environment variables on the Docker host machine:

or to display your Blackfire's credentials.

From now on, we assume that these environment variables are set up properly.

Docker Compose

If you use docker compose, you can declare the Blackfire agent as a service. To do so, use the following snippet:

or to display your Blackfire's credentials.

version: '3'
services:
  blackfire:
    image: blackfire/blackfire:2
    ports: ["8307"]
    environment:
        # Exposes BLACKFIRE_SERVER_* environment variables from the host
        BLACKFIRE_SERVER_ID: <YOUR_BLACKFIRE_SERVER_ID>
        BLACKFIRE_SERVER_TOKEN: <YOUR_BLACKFIRE_SERVER_TOKEN>

        # Exposes BLACKFIRE_CLIENT_* environment variables
        # allowing the client to communicate with Blackfire's API:
        BLACKFIRE_CLIENT_ID: <YOUR_BLACKFIRE_CLIENT_ID>
        BLACKFIRE_CLIENT_TOKEN: <YOUR_BLACKFIRE_CLIENT_TOKEN>

CLI Client for HTTP Profiling

When profiling remote servers, you may use the Blackfire CLI tool which is embedded in Blackfire Docker image.

Assuming you configured blackfire service as explained above, you may use the following command:

1
docker compose exec blackfire blackfire curl http://example.com

To make it less verbose, create an alias:

1
2
alias blackfire-curl='docker compose exec blackfire blackfire curl'
blackfire-curl http://example.com/

Note

STDOUT & STDERR using docker compose

When using docker compose exec STDOUT and STDERR outputs are mixed up. This is due to the limitations of the pseudo TTY which is allocated by default by Docker Compose.

This can be an issue when using the --json option to dump a profile data in JSON. The profile data is indeed output to STDOUT by blackfire curl command, while the process info is output to STDERR.

The workaround in this case is to use Docker Compose -T option:

1
docker compose exec -T blackfire blackfire curl http://example.com

Debugging the Agent

By default, the agent is quiet and does not produce logs. To debug problems, increase the log verbosity by setting BLACKFIRE_LOG_LEVEL to 4:

or to display your Blackfire's credentials.

version: '3'
services:
  blackfire:
    image: blackfire/blackfire:2
    ports: ["8307"]
    environment:
        # Define Blackfire Agent log vebosity level
        BLACKFIRE_LOG_LEVEL: 4

        # Exposes BLACKFIRE_SERVER_* environment variables from the host
        BLACKFIRE_SERVER_ID: <YOUR_BLACKFIRE_SERVER_ID>
        BLACKFIRE_SERVER_TOKEN: <YOUR_BLACKFIRE_SERVER_TOKEN>

        # Exposes BLACKFIRE_CLIENT_* environment variables
        # allowing the client to communicate with Blackfire's API:
        BLACKFIRE_CLIENT_ID: <YOUR_BLACKFIRE_CLIENT_ID>
        BLACKFIRE_CLIENT_TOKEN: <YOUR_BLACKFIRE_CLIENT_TOKEN>

You may then tail the logs with docker compose:

1
docker compose logs -f blackfire

Raw Docker Image

The Blackfire image is the fastest way to get the Blackfire agent running:

1
docker run --name="blackfire" -d -e BLACKFIRE_SERVER_ID -e BLACKFIRE_SERVER_TOKEN blackfire/blackfire:2

Note

Upgrading

To upgrade the Blackfire image, pull the newest image from Docker and restart the agent container:

1
docker pull blackfire/blackfire:2

You can check the version of a running Blackfire container with the following command:

1
docker exec blackfire blackfire-agent -v

CLI Client for HTTP Profiling

When profiling remote servers, you may use the Blackfire CLI tool which is embedded in Blackfire Docker image:

1
2
3
4
5
6
docker run -it --rm \
    -e BLACKFIRE_CLIENT_ID \
    -e BLACKFIRE_CLIENT_TOKEN \
    --expose 8307 \
    blackfire/blackfire:2 blackfire \
    curl http://example.com/

To make it less verbose, create an alias:

1
2
alias blackfire-curl='docker run -it --rm -e BLACKFIRE_CLIENT_ID -e BLACKFIRE_CLIENT_TOKEN blackfire/blackfire:2 blackfire curl'
blackfire-curl http://example.com/

Using the Probe

To install the Blackfire Probe in your application container, read the following guides, depending on your runtime:

Using Blackfire Player With Docker

To use Blackfire Player with Docker, read the dedicated guide.