Installing from Source

This guide will show you how to install Beer Garden for development. When you’re done you should be able to make changes to Beer Garden, run the tests, and push up your changes.

Prerequisites

You will absolutely need these things:

  • Python 3.7+. You’ll need a full environment (with pip).

  • Connectivity to MongoDB 3.2+

  • Connectivity to RabbitMQ

  • Git, correctly configured to talk to GitHub

  • NPM Install


These things are nice to have:

  • Some sort of virtualenv setup, virtualenvwrapper is nice

  • A Python IDE (e.g. PyCharm)

Installing these is outside the scope of this documentation, so please refer to their installation instructions if you need help with them.

Install and Setup

Clone the Repos

There are two main repositories you’ll need: beer-garden and bindings. Both are part of the beer-garden GitHub group. Clone them:

git clone https://github.com/beer-garden/beer-garden.git
git clone https://github.com/beer-garden/brewtils.git

Install Dependencies

This is where virtualenvwrapper is helpful. There are two repositories that have their own dependencies (beer-garden & brewtils). There’s a .venv file in each of them, so make a virtualenv for each of them:

mkvirtualenv brewtils
mkvirtualenv beer-garden

Sweet. Now for each of the projects you can install the dependencies:

make deps

At this point we need a little sidebar about how beer-garden is structured. Beer-Garden is the application that actually run, and bg-utils and brewtils are libraries. Real quick:

  • Brewtils is the library plugin developers use to create plugins. It has things like our models and decorators.

  • Beer-Garden is our 'internal' library with things like our model-database mappings.

  • Beer-Garden is the REST server that also serves the static frontend.

  • Beer-Garden is basically all the application logic.

So, as you can probably guess, beer-garden has a compile-time dependency on brewtils.

When you ran make deps earlier pip grabbed the latest brewtils from GitHub. So if you make changes to those projects they won’t actually show up when you run beer-garden. We need to tell our virtualenvs to install those distributions in 'editable' mode. From the beer-garden root directory:

cd beer-garden; pip uninstall -y brewtils; pip install -e ../../brewtils

The Beer Garden UI utilizes NPM to install Javascript dependencies.

cd beer-garden/src/ui;
npm install;

Run the Tests

To make sure everything is working you can run the Python tests. Each project has a Makefile to help run the tests and more. To generate coverage:

make coverage

And you should see all the tests pass.

Run the Application

The repositories come with configuration settings that make sense for development (these are in the dev_conf directories), so you should just be able to start the application.

Both of these commands will run until you stop them, so you’ll either need to use two shells or run them in the background. Use Ctrl-C to kill them. 
cd beer-garden; bin/app.sh

If you are utilizing NPM to serve the website

cd beer-garden/src/ui;
npm run serve;

You should see logs as the application starts up. Then you can visit http://localhost:8080 to see the application!

If you are going to utilize a different hosting platform:

cd beer-garden/src/ui;
npm run build;

You should see the static files hosted in beer-garden/src/ui/dist and any hosting platform just needs to point to that directory, or copy that to their hosting directory. For example, you can host via NGINX.