SquirrelDB Installation

Database

SquirrelDB stores its metrics in Cassandra or in ClickHouse. Pick one, and have it running before starting SquirrelDB. See storage backends if you are unsure which one to use.

Cassandra

You can follow the Cassandra installation documentation, or run it with Docker:

# The network is needed only if you run SquirrelDB with Docker.
docker network create squirreldb

docker run -d --name squirreldb-cassandra -p 127.0.0.1:9042:9042 --restart unless-stopped \
    -v cassandra:/var/lib/cassandra --net squirreldb cassandra

ClickHouse

You can follow the ClickHouse installation documentation, or run it with Docker:

# The network is needed only if you run SquirrelDB with Docker.
docker network create squirreldb

docker run -d --name squirreldb-clickhouse -p 127.0.0.1:9000:9000 --restart unless-stopped \
    -v clickhouse:/var/lib/clickhouse --net squirreldb \
    -e CLICKHOUSE_DB=squirreldb \
    -e CLICKHOUSE_USER=squirreldb \
    -e CLICKHOUSE_PASSWORD=mypassword \
    clickhouse/clickhouse-server

SquirrelDB connects on the native protocol (port 9000), and creates its own tables in the database — but not the database itself, so it must exist beforehand. The Docker image creates it for you with CLICKHOUSE_DB.

SquirrelDB

Docker

The preferred method to install SquirrelDB is Docker.

Cassandra

# Set the address of your Cassandra servers here, separated by commas.
SQUIRRELDB_CASSANDRA_ADDRESSES=squirreldb-cassandra:9042

docker run -d --name squirreldb -p 127.0.0.1:9201:9201 --restart unless-stopped \
    --net squirreldb -e SQUIRRELDB_CASSANDRA_ADDRESSES bleemeo/squirreldb

ClickHouse

docker run -d --name squirreldb -p 127.0.0.1:9201:9201 --restart unless-stopped \
    --net squirreldb \
    -e SQUIRRELDB_BACKEND=clickhouse \
    -e SQUIRRELDB_CLICKHOUSE_ADDRESSES=squirreldb-clickhouse:9000 \
    -e SQUIRRELDB_CLICKHOUSE_DATABASE=squirreldb \
    -e SQUIRRELDB_CLICKHOUSE_USERNAME=squirreldb \
    -e SQUIRRELDB_CLICKHOUSE_PASSWORD=mypassword \
    bleemeo/squirreldb

List every ClickHouse server node in SQUIRRELDB_CLICKHOUSE_ADDRESSES, separated by commas: there is no node discovery, and SquirrelDB routes queries only to the healthy ones.

Binary

SquirrelDB is a single static Go binary, published on the latest GitHub release for Linux on x86-64, i386, ARMv6 and ARM64.

For example, if you are on an x86-64 platform:

sudo wget https://github.com/bleemeo/squirreldb/releases/latest/download/squirreldb-linux_x86_64.bin \
    -O /usr/local/bin/squirreldb
sudo chmod +x /usr/local/bin/squirreldb

Configuration file

By default SquirrelDB reads the file squirreldb.conf in its working directory. Point it elsewhere with --config, which accepts both files and directories — a directory loads every .conf file it contains, which is handy to split the configuration into fragments:

squirreldb --config /etc/squirreldb/squirreldb.conf
squirreldb --config /etc/squirreldb/conf.d

Every option can also be set through an environment variable, so a deployment needs no file at all. See the configuration reference.

Running as a service

There is no packaged service unit, so create one. For example, in /etc/systemd/system/squirreldb.service:

[Unit]
Description=SquirrelDB
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/squirreldb --config /etc/squirreldb/squirreldb.conf
Restart=always
RestartSec=5
DynamicUser=yes

[Install]
WantedBy=multi-user.target

Then enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now squirreldb

SquirrelDB keeps no local state — everything lives in Cassandra or ClickHouse, and in Redis for the short term store — so the service needs no data directory.

Next steps

SquirrelDB is now listening, but nothing writes to it yet: see SquirrelDB with Prometheus and Dashglass to send it your metrics and build dashboards on top of them.