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.

Since these are the early days of StackState there are still a lot of ways to simplify our installation process that we are aware of.


Server requirements

To install the StackState server, you must meet the following requirements:

  • Operating system: Microsoft Windows (64-bit) or a Unix-family operating system running Java

  • Oracle, IBM, or Apple Java Development Kit (JDK):

    • JDK 8 patch level 102 or later
  • RAM: At least 8 GB of RAM available for StackState and an additional 6 GB of RAM available for StackGraph

  • Hard disk space: At least 100GB of hard disk space available for StackState and an additional 50GB of hard disk space available for StackGraph. The actual disk space requirements depend on the amount of data StackState will process

Networking requirements

Before installing StackState, ensure that the network connection to the StackState host name works. You should be able to successfully execute ping stackstate_hostname.

By default, StackState requires port 7070 to be available for the StackState GUI and API.

StackState and StackGraph internally need access to the following additional ports:

  • StackState: 7071, 9092, 9200, 9300
  • StackGraph: 16020, 8020, 10102, 50070, 10103, 10104, 50010, 43451, 50075, 16030, 44350, 16000, 50020, 2181, 46534, 53288, 16010, 46734, 36366, 57464

Client requirements

To use the StackState GUI, you must use one of the following web browsers:

  • Firefox
  • Chrome
  • Internet Explorer 11 or later
  • Edge


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.

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>.

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.

Starting StackState

  • The DEB and RPM packages install SystemD services for StackState and StackGraph. StackState can be started with sudo systemctl start stackstate.service this will also start StackGraph. If needed StackGraph can be started separately with sudo systemctl start stackgraph.service. Stopping the services and service status can also be checked with systemctl.
  • The /opt/stackstate/bin/ command can also be used for several maintenance tasks like creating a backup. Run /opt/stackstate/bin/ --help to get a complete list.

Installing StackState on MacOs and other Linux flavors

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

Installation instructions

  1. Unzip the into the directory where you want to install StackState.
  2. Create a user and group used for 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/ $user $group

Starting StackState

To start using StackState, see usage.

Installing StackState on Windows

StackState has been tested on Windows 7 and up. A 64 bit version of Windows is required.

Installation instructions

  1. Download and install Java 8 (JRE) 64-bits

    • Set a global JAVA_HOME environment variable to the installation directory of Java (parent directory of bin\java.exe).
      • Note: Please make sure you point it to the 64 bits version (so not the one under *\Program Files (x86)\Java\*)
    • Java needs to be on the path: add %JAVA_HOME%\bin at the end of the definition for the PATH environment variable. see for an explanation on how to add environment variables and Java to the path.
  2. Download and install the Visual C++ Redistributable for Visual Studio 2015: vc_redist.x64.exe

    • from Microsoft
    • or alternatively from Softpedia
  3. Unzip the zipfile containing StackState and you are ready to go.
    For an overview how to start and stop stackstate and stackgraph and general usage see usage

Upgrading StackState

When upgrading stackstate, the package will not automatically create a backup of StackGraph data. If you want to make a backup run the bin/ script. It will create a backup and store it inside the /opt/stackstate/backups/ directory. It will also start StackState and StackGraph when the upgrade was successfull. Run the command: - rpm -U stackstate.rpm

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.

Configuring a reverse proxy

StackState makes heavy use of Websockets, so when setting up a reverse proxy to make StackState available on, for example, port 80 or 443 (with TLS) you will also need to proxy Websocket requests. An example setup for Nginx for this looks like this (proxying port 80 to StackState running on localhost port 7070):

  http {
      map $http_upgrade $connection_upgrade {
          default upgrade;
          '' close;

      server {
          listen 80;
          location / {
              proxy_http_version 1.1;
              proxy_set_header Upgrade $http_upgrade;
              proxy_set_header Connection $connection_upgrade;