Quick Start

Installation

There are two ways to get started with GRU: Either clone the project and run the python server - or run it using the the Docker image.

We recommend using Docker, since it eliminates the need to install all the different python and OS dependencies.

If you plan on contributing or simply hacking on GRU itself, you should probably use the local server instead. Keep in mind that GRU provides a pretty flexible plugin system. You can develop your own plugins and keep using the docker image.

Basic Configuration

Before we can run GRU, we need to setup a yaml file describing how to access our inventory and optionally how to authenticate and authorize users as well as set other configuration parameters to adjust GRU to our liking.

Here’s a very basic example of how this configuration might look like, without any authentication or authorization:

---
flask:
  # Keep this one random. used by the session system.
  secret_key: 'fojegj340fuccotnhvi39yombpris'

# Here we set up EC2 as our source of inventory.
inventory:
  provider: gru.contrib.inventory.providers.EC2Provider
  config:
   accounts:
      # setting aws_access_key and aws_secret_access_key is optional
      # otherwise, will be taken from ~/.aws/credentials
      # or environment variables
      - regions: ['us-east-1']
  # Whiche metadata field to use as a hostname
  host_display_name_field: tag:Name
  # Fields to create logical groups of hosts by
  group_by:
    - field: tag:stack
      title: Stack
    - field: tag:role
      title: Role
    - field: region
      title: Region
  # Fields visible when showing a table of hosts
  host_table_fields:
    - field: tag:role
      title: Role
    - field: tag:environment
      title: Env
    - field: architecture
      title: Arch
    - field: instance-state-name
      title: Status
    - field: private-ip-address
      title: IP
  # Fields visible by default when looking at a single host
  # (The user can toggle to view remaining fields)
  host_info_fields:
    - field: tag:role
      title: Role
    - field: region
      title: DC
    - field: tag:environment
      title: Env
    - field: architecture
      title: Arch
    - field: instance-state-name
      title: Status
    - field: private-ip-address
      title: IP

Please review the Configuration Reference section or check out the examples/ directory on Github.

Running using Docker

Assuming you already have a yaml configuration file named gru.yaml, all we need to do is run the docker image:

$ docker run --rm -it \
    -v $PWD:/etc/gru \
    -e GRU_SETTINGS=/etc/gru/gru.yaml \
    -e "AWS_ACCESS_KEY_ID=AKXXXXXXXXXXXXXXXXXX" \  # Set this to your AWS keys
    -e "AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
    -p 5000:5000 \
    similarweb/gru:latest

If you are using custom plugins, simply mount the module directory and reflect that in your settings file:

$ docker run --rm -it \
    -v $PWD:/etc/gru \
    -e GRU_SETTINGS=/etc/gru/gru.yaml \
    -e "AWS_ACCESS_KEY_ID=AKXXXXXXXXXXXXXXXXXX" \  # Set this to your AWS keys
    -e "AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
    -v /path/to/plugins:/opt/gru-plugins \
    -p 5000:5000 \
    similarweb/gru:latest

This will automatically pull the gru image from docker hub, and run a server using the gru.yaml settings file.

Running a local server

Running a local server has been tested on Debian and Ubuntu linux. It should be able to run on OSX and Windows as well, but it hasn’t been thoroughly tested.

First, install GRU’s dependencies:

$ apt-get install --no-install-recommends \
    python-dev \
    libssl-dev \
    libsasl2-dev \
    libldap2-dev

Once that’s done, we need to clone the GRU project:

$ git clone git://github.com/similarweb/gru .

Then, install all the required Python dependencies. Preferably, this step should be done in a virtualenv):

$ pip install -r requirements.txt

Now, run the server itself using the settings file you created:

$ GRU_SETTINGS="/path/to/gru.yaml" python app.py runserver

A server will be started, listening on http://localhost:5000