StackState runs on the Java virtual machines and comes packaged with its own graph database called StackGraph. To run StackState you must first run StackGraph, a time traveling graph database we’ve built on top of HBase. StackState is built on a highly distributed architecture, therefore it runs as a number of Java processes that communicate with each other via TCP/IP.


To install StackState on Fedora, Red Hat or CentOS there is an RPM package available to easily install and upgrade StackState. For Debian and Ubuntu there is a DEB package available. Packages can be obtained from the distribution website.

Installing StackState

Below are installation instructions for StackState on different platforms.

Installing StackState on Fedora, Red Hat, CentOS, Debian or Ubuntu

Installation instructions

To let yum automatically install the right java version for the RPM package use: - yum localinstall <stackstate>.rpm

Or you can use rpm, which assumes the correct java version is already installed: - rpm -i <stackstate>.rpm

To install using the DEB package, assuming the correct java version is already installed: - dpkg -i <stackstate>.deb

Alternatively use apt-get which will also install the proper Java version: - apt-get install <stackstate>.deb

The package creates a stackstate user and group as which StackState will be running. To start you first have to register StackState by running: sudo -u stackstate /opt/stackstate/bin/ register --key <license-key>.

StackState needs to know how it can be reached by the agent and other integrations to receive topology and telemetry data. Configure this, before starting StackState, by finding the line containing # baseUrl = in /opt/stackstate/etc/application_stackstate.conf, uncomment it and set it to the URL at which other systems can reach StackState. By default StackState exposes the endpoint for this as a plain HTTP endpoint on port 7077. So depending on the exact setup (HTTPS enabled, a reverse proxy in front of StackState, etc…) the entry should be similar to baseUrl = "http://<hostname>:7077".

By default, the data directory is set to /opt/stackstate/var/lib and the log directory is set to /opt/stackstate/var/log. It is possible to change the data and log directories by setting the appropriate environment variables prior to installing StackState. Set environment variable STACKSTATE_DATA_DIR to set the data directory and set the environment variable STACKSTATE_LOG_DIR to set the log directory.

Installing StackState on MacOs and other Linux flavors

StackState has been tested on recent versions of MacOs and Ubuntu.

Installation instructions

  1. Unzip the <stackstate>.zip into the directory where you want to install StackState.
  2. Create a user and group used called stackstate.
  3. Before starting StackState, it has to configure its directory structure. This is done by running a config script, which uses a directory structure configured inside the script. If you want to change the default structure, you can edit this file, before starting the config script. Execute the line below to run the config script, passing the user and group created in the previous step.
    • bin/ stackstate stackstate

Starting StackState

To start using StackState, see Starting / Stopping.

Installing StackState in a distributed configuration

The default packaging assumes StackState and StackGraph run on the same server. To install StackState and StackGraph on different servers (still only 1 instance of every application) some configurations need to be changed.

On both servers install StackState with the normal RPM or Debian package. On the server where only StackGraph should be running start StackGraph with sudo systemctl start stackgraph.service. On the server where only StackState should be running the provided SystemD configuration needs to be adapted. Edit the file /lib/systemd/system/stackstate.service file:

  • Remove the stackgraph.service from the Requires and After sections
  • Define the environment variable ZOOKEEPER_QUORUM=<your-stackgraph-server> under the [Service] section, with the hostname of your StackGraph server as the value.

After these changes the stackstate.service file should look approximately like this:

Description=StackState System monitor Service

ExecStart=/opt/stackstate/bin/ start
ExecReload=/opt/stackstate/bin/ reload
ExecStop=/opt/stackstate/bin/ stop


Now register StackState with sudo -u stackstate /opt/stackstate/bin/ register --key <license-key> and start it with sudo systemctl start stackstate.service.