Docker/Docker Compose Installation Guide

This guide provides step-by-step instructions for installing and running Beer Garden using docker. It covers both docker-compose and using the individual docker images.


For this guide we assume you have the following:

Docker-compose file

The first step is to clone the git repository that contains the docker-compose.yml file:

git clone [email protected]:beer-garden/beer-garden.git

cd beer-garden/docker/docker-compose

In this directory you will see a docker-compose.yml file that describes the different components of Beer Garden and how they fit together.


Before we can run Beer Garden we need to make one small change to the configuration.

Beer Garden needs to tell plugins the hostname of a RabbitMQ broker where they’ll listen for messages. This value is set as BG_PLUGIN_MQ_HOST in the environment or --plugin-mq-host on the command line. The default value in docker-compose.yml is localhost - this allows containers running outside of the compose network with --network host (as in the quickstart) to work. However, running this way is not really appropriate in most cases.

To allow Beer Garden to work in all cases you’ll need to set this value to something that will resolve to the machine you’re currently using. Ideally this will be a fully-qualified name, but an IP address would work as well.

To change the value open docker-compose.yml and find the line near the top that says BG_PLUGIN_MQ_HOST: localhost. Change "localhost" to whatever value makes sense for your specific setup.

If you intend for plugins to connect to this Beer Garden from a different machine make sure you use a name or IP address that’s resolvable from the plugin’s perspective.

That’s it! You’ve configured Beer Garden!


Then run this command to start Beer Garden:

docker-compose up -d

That’s it! Once that finishes Beer Garden will be running in the background. Point a browser at http://localhost and you’ll see a message letting you know that Beer Garden couldn’t find any systems. That’s OK - you’re about to add one!

Test your installation

We have a docker image with a very simple plugin you can use to test out your Beer Garden. Run it with this command:

docker run bgio/example-plugin --bg-host <IP-ADDRESS> --ssl-disabled

Where <IP-ADDRESS> is the same value you used during the configuration file step earlier.

The --ssl-disabled is necessary because your brand new Beer Garden doesn’t have a valid server certificate.

Start a Remote Plugin

If you have a remote plugin, you simply need to start it and point it to the host you just stood up!

Start a Local Plugin

If you have a local plugin, then this Beer Garden is ready to deploy it. Simply copy your plugin into the ./plugins/ then navigate to http://<IP-ADDRESS>:80 then:

  1. Click on Administration on the left side of the page

  2. Click on System Administration

  3. Click Rescan System Directory at the top right of the screen

You should see your plugin appear!

If your plugin does not appear, be sure to checkout the logs using: docker-compose logs -f beer-garden


Run this command to stop Beer Garden.

docker-compose down