(Last Updated On: July 11, 2018)

This guide will cover the installation and configuration of Graphite on Ubuntu 18.04 Bionic Beaver Linux. Graphite is a highly available time-series monitoring and data store with support for data visualization. Ideally, you will install other tools on a system to monitor, which will collect the metrics and ship them to Graphite e.g Statsd.

Graphite Architecture

Graphite consists of 3 software components:

  1. carbon – a Twisted daemon that listens for time-series data
  2. whisper – a simple database library for storing time-series data (similar in design to RRD)
  3. graphite webapp – A Django webapp that renders graphs on-demand using Cairo

Feeding data to graphite is the easy part. Data that are sent to Carbon become immediately available for graphing in the webapp. From webapp, you can create and display graphs including a simple URL API for rendering that makes it easy to embed graphs in other web pages.

Method 1: Installing Graphite on Ubuntu 18.04 using Docker (Recommended)

The first and easy method to install Graphite on Ubuntu 18.04 is using Docker.

Step 1: Update system and installed packages.

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo reboot

Step 2: Install Docker Engine

For installation of Docker Engine on Ubuntu 18.04, use our guide:

How to install Docker CE on Ubuntu / Debian / Fedora / Arch / CentOS

Confirm that the service is running before you can proceed:

root@graphite:~# systemctl status docker
● docker.service - Docker Application Container Engine
   Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2018-07-11 07:45:15 UTC; 43s ago
     Docs: https://docs.docker.com
 Main PID: 8898 (dockerd)
    Tasks: 16
   CGroup: /system.slice/docker.service
           ├─8898 /usr/bin/dockerd -H fd://
           └─8937 docker-containerd --config /var/run/docker/containerd/containerd.toml

Step 3: Install Graphite and statsd container

Once the docker engine is installed and running, it is time to start docker container for Graphite and Statsd. We will use the official Docker repo for Graphite:

Create directories on the host system for persistent data storage:

$ sudo mkdir -p /data/graphite/{statsd,configs,data}

Graphite & Statsd can be complex to set up. The docker image provided will have you running & collecting stats in just a few minutes.

$ sudo docker run -d \
 --name graphite \
 --restart=always \
 -p 80:80 \
 -p 2003-2004:2003-2004 \
 -p 2023-2024:2023-2024 \
 -p 8125:8125/udp \
 -p 8126:8126 \
 -v /data/graphite/configs:/opt/graphite/conf \
 -v /data/graphite/data:/opt/graphite/storage \
 -v /data/graphite/statsd:/opt/statsd \
 graphiteapp/graphite-statsd

Wait for docker engine to download and start docker container for you. It may take some time depending on your internet speed. Once it is done, you should be able to see docker container running:

root@graphite:~# docker ps
CONTAINER ID        IMAGE                         COMMAND             CREATED             STATUS              PORTS                                                                                                                                                        NAMES
959fe7ab2abd        graphiteapp/graphite-statsd   "/sbin/my_init"     11 seconds ago      Up 10 seconds       0.0.0.0:80->80/tcp, 0.0.0.0:2003-2004->2003-2004/tcp, 8080/tcp, 0.0.0.0:2023-2024->2023-2024/tcp, 0.0.0.0:8126->8126/tcp, 8125/tcp, 0.0.0.0:8125->8125/udp   graphite

This starts a Docker container named: graphite. Please also note that you can freely remap container port to any host port in case of corresponding port is already occupied on the host.

Includes the following components

  • Nginx – reverse proxies the graphite dashboard
  • Graphite – front-end dashboard
  • Carbon – back-end
  • Statsd – UDP based back-end proxy

Mapped Ports

Host Container Service
80 80 nginx
2003 2003 carbon receiver – plaintext
2004 2004 carbon receiver – pickle
2023 2023 carbon aggregator – plaintext
2024 2024 carbon aggregator – pickle
8080 8080 Graphite internal gunicorn port (without Nginx proxying).
8125 8125 statsd
8126 8126 statsd admin

By default, statsd listens on the UDP port 8125. If you want it to listen on the TCP port 8125 instead, you can set the environment variable STATSD_INTERFACE to tcp when running the container.

Step 3: Accessing the Graphite Web interface

When everything is running fine, access Graphite web dashboard by using the server IP address or port number and the port mapped on the host to container’s port 80:

The default logins creds are:

Username: root
Password: root

Change this login credentials after the first login at http://ip-address/admin/auth/user/1/

Provide desired root password and confirm it.

You can now log out and re-login to confirm that the new password is working.

Method 2: Installing Graphite on Ubuntu 18.04 From apt packages

Now that we’ve covered the basics of Graphite, let’s proceed to the installation. Follow the steps below to get Graphite running on your Ubuntu 18.04 server.

Step 1: Update system packages:

The first step in the installation is to ensure that all system packages are updated:

$ sudo apt-get update
$ sudo apt-get upgrade

Consider rebooting the server after an upgrade

$ sudo reboot

Step 2: Installing Graphite on Ubuntu 18.04

Once the server is up from reboot, proceed to install graphite packages. We will install Graphite web application and carbon, which stores the data in Graphite’s specialized database.

$ sudo apt-get install graphite-web graphite-carbon

Wait for the packages to finish installing then proceed to the next step.

# apt policy graphite-web
graphite-web:
  Installed: 1.0.2+debian-2
  Candidate: 1.0.2+debian-2
  Version table:
 *** 1.0.2+debian-2 500
        500 http://mirrors.digitalocean.com/ubuntu bionic/universe amd64 Packages
        100 /var/lib/dpkg/status

# apt policy graphite-carbon 
graphite-carbon:
  Installed: 1.0.2-1
  Candidate: 1.0.2-1
  Version table:
 *** 1.0.2-1 500
        500 http://mirrors.digitalocean.com/ubuntu bionic/universe amd64 Packages
        100 /var/lib/dpkg/status

Step 3: Install and configure MariaDB Database server

By default, Graphites uses an SQLite database to store Django models such as saved graphs, dashboards, user preferences, etc. Note that Metric data is not stored here. In this guide, we will use the MariaDB database server. Check our guide on how to Install MariaDB on Ubuntu 18.04.

Once the database server is up and ready, create a database for Graphite. Login to your database server as root user and create a database for graphite:

$ mysql -u root -p
Enter password: 
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 19258
Server version: 10.3.7-MariaDB-1:10.3.7+maria~bionic-log mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [(none)]> create database graphite_db;
MariaDB [(none)]> grant all privileges on graphite_db.* tographite_user identified by "strongpassword";
Query OK, 0 rows affected (0.000 sec)
MariaDB [(none)]> flush privileges;
Query OK, 0 rows affected (0.001 sec)

Once the database is ready

Step 4: Configure Graphite & Carbon

Once you have installed Graphite packages, proceed to the configuration:

$ sudo vim /etc/graphite/local_settings.py

Set timezone:

TIME_ZONE = "Africa/Nairobi"

Set a secret key used for salting of hashes used in auth tokens. You can generate one using uuidgen

SECRET_KEY = 'my_secret_key'

Please set this to a long, random unique string to use as a secret key. For the database section, comment below section:

DATABASES = {
    'default': {
        'NAME': '/var/lib/graphite/graphite.db',
        'ENGINE': 'django.db.backends.sqlite3',
        'USER': '',
        'PASSWORD': '',
        'HOST': '',
        'PORT': ''
    }
}

Then add configuration for MySQL / MariaDB

DATABASES = {
    'default': {
        'NAME': 'graphite_db',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'graphite_user',
        'PASSWORD': 'strongpassword',
        'HOST': '127.0.0.1',
        'PORT': ''
    }
}

Install pymysql Python module

$ sudo apt-get install python3-pymysql
$ sudo apt-get install python-pymysql

Now sync the database to have proper structure:

$ sudo graphite-manage migrate auth
Operations to perform:
  Apply all migrations: auth
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK

$ sudo graphite-manage migrate
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions, tagging
Running migrations:
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying sessions.0001_initial... OK
  Applying tagging.0001_initial... OK
  Applying tagging.0002_on_delete... OK
 Enable carbon caching:
$ sudo /etc/default/graphite-carbon
CARBON_CACHE_ENABLED=true
Enable Log rotation:
$ sudo /etc/carbon/carbon.conf
ENABLE_LOGROTATION = True

start Carbon service/ St to start on boot with the following commands:

$ sudo systemctl start carbon-cache
$ sudo systemctl enable carbon-cache

Step 5: Configuring The Webapp

We have our setup ready, the only thing we need to do is configure the web application. For this we will set up the following:

$ sudo apt-get install nginx