Skip to content

Server

This section describes how to deploy and host a Hydra Dashboard server.

Prerequisites

  • Docker engine 1.10.0+ (download it here)
  • Docker compose 1.6.0+

Deployment

The Dashboard is made up of three docker services:

  • influxdb: Persists metrics in influxDB (an open-source, performant, time-series database).
  • grafana: Web-based portal to display metric analytics collected during compilation (Grafana is an open-source platform). This service needs to be able to connect to the influxdb service to query its data.
  • server: Exposes a REST endpoint used by Metrics service to push the collected metrics. Received metrics data is persisted in the influxdb service.

The Dashboard can be deployed either locally or on a shared server. Once the Dashboard is up and running, read Metrics service to understand how metrics are collected and pushed to the Dashboard.

Local

1) Create a docker-compose.yml file with the following content:

version: "2"

services:
    influxdb:
        image: influxdb:1.5.2
        ports: ["8086:8086"]
        volumes: ["${STORAGE}:/var/lib/influxdb/"]
        networks: ["sandbox"]

    grafana:
        image: triplequote/dashboard_grafana:1.1.0
        ports: ["3000:3000"]
        networks: ["sandbox"]
        depends_on: ["influxdb"]

    server:
        image: triplequote/dashboard_server:1.1.0
        ports: ["3333:3333"]
        networks: ["sandbox"]
        depends_on: ["influxdb"]
        command: "-Dtriplequote.dashboard.server.datastore.influxDB.url=http://influxdb:8086"

networks:

  sandbox:
    driver: bridge

Note: If using Windows, influxdb might fail to properly start with Docker because it can't mount external volumes. This is a known problem (here is the related ticket). The good news is that a fix for this problem was recently merged and it will be included in the upcoming influxdb 1.6.0 release. Until then, download and install influxdb v1.5 on your Windows host and remove the influxdb service from the docker-compose.yml file before running it.

2) Create a directory under your ${user.home}. This directory is going to be used by the influxdb service to persist the compilation metrics. For instance, if you are on Mac OSX, /Users/john/hydra-metrics-db would work well (this assumes that ${user.home} is /Users/john).

3) Open a terminal and cd to the folder containing the docker-compose.yml file. Then, run docker-compose as follows: STORAGE=/Users/john/hydra-metrics-db docker-compose up.

$ STORAGE=/Users/john/hydra-metrics-db docker-compose up
Creating docker_influxdb_1 ... done
Creating docker_grafana_1  ... done
Creating docker_server_1   ... done
Attaching to docker_influxdb_1, docker_server_1, docker_grafana_1
influxdb_1  | ts=2018-05-07T14:10:44.708712Z lvl=info msg="InfluxDB starting" log_id=07vjtTP0000 version=1.5.2 branch=1.5 commit=02d7d4f043b34ecb4e9b2dbec298c6f9450c2a32
[...]

Assuming the default ports (3000, 3333, and 8086) set in the docker-compose.yml are free, open http://0.0.0.0:3000/d/000000001/trends in your preferred browser and you should see the Trends dashboard:

Dashboard Trends empty

Remote

Deploying the dashboard on a remote server boils down to running the three docker services defined in the above docker-compose.yml.

What's important to remember is that users will have to set in their build the URL where the server service is running, since by default Hydra pushes metrics to http://localhost:3333. Therefore, the URL on which the server is running has to be accessible for users to successfully push data to it.

Configuration

Each service offers a high degree of configurability to meet your deployment requirements.

InfluxDB

For the influxdb service we use the official influxdb docker image. Refer to the "Configuration" section on the dockerhub influxdb page for details on how to configure influxdb with docker.

Note that if the influxdb exposed port is changed, the server service needs to be started with the proper URL to connect to the influxdb service. In practice, this means that the system property -Dtriplequote.dashboard.server.datastore.influxDB.url passed to the server service must be updated accordingly. Furthermore, the Grafana hydraDB datasource configuration should also be updated or Grafana will report errors when opening the different dashboards.

Grafana dashboard

The dashboard_grafana docker image is currently based on Grafana 5.0.3 and it's preconfigured to allow anonymous access to all dashboards. The administrator username/password is the Grafana's default, i.e., admin/admin. Refer to the Grafana documentation for how to configure Grafana in detail. However, note that in the future we might migrate away from Grafana, so we recommend not to invest too much time into customization.

Note that the grafana service exposed port can be changed as it suits you best without impacting any of the other services.

Server

The server service is started with the following HOCON configuration:

triplequote.dashboard.server {
  logLevel = "INFO"

  address = "0.0.0.0"
  port = 3333

  datastore.influxDB {
    name = "hydraDB"
    url = "http://localhost:8086"
    username = "root"
    password = "root"

    retentionPolicy {
      name = "hydraRetentionPolicy"
      duration = "180d"
      shardDuration = "1d"
      replicationFactor = 1
    }
  }
}

Each key in the configuration can be overridden when starting the server service via system properties. For instance, as mentioned in the previous section about configuring InfluxDB, if the influxdb exposed port is changed, the URL used by the server to connect to influxdb must be updated by passing the system property -Dtriplequote.dashboard.server.datastore.influxDB.url.

Note that the server also defines the retention policy for the data persisted in influxdb. The current default is to retain data for six months, but you should feel free to change this as it suits you best.

Logging

The server is configured to log to the standard output using the following logback configuration:

<configuration>

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%date{yyyy-MM-dd HH:mm:ss} [%level] %logger{15} in %thread - %message%n%xException</pattern>
        </encoder>
    </appender>

    <appender name="ASYNCSTDOUT" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="STDOUT" />
    </appender>

    <root level="${triplequote.dashboard.server.logLevel:-INFO}">
        <appender-ref ref="ASYNCSTDOUT" />
    </root>

</configuration>

It's possible to provide a different logback configuration via the system property -Dlogback.configurationFile=/path/to/config.xml. However, note that to log at "DEBUG" level you only need to set -Dtriplequote.dashboard.server.logLevel="DEBUG" before the server is started.