Docker installation

Docker compose Quickstart

A docker compose is available and is recommended to quickly deploy and test all the components.

Firstly you will need to download all the content from this folder. You will find 2 files: :::note docker-compose.yml This is the Docker Compose file, which instructs Docker on how to deploy the Bleemeo Community Edition stack. ::: :::note nats.conf This is a basic configuration file for NATS to enable an MQTT endpoint. In production, ensure the MQTT port is secured, particularly if exposed to the internet. NATS should be configured with TLS and authentication. For more details, refer to the NATS TLS documentation and the authentication setup guide. :::

Once done you can start the stack by using the following command:

docker compose up -d

Docker setup

An alternative to the docker compose method is to run each container manually using docker run.

SquirrelDB

SquirrelDB is a timeseries database, highly optimized for storing metrics. It has several interesting features:

Blazing fast read of recent metrics using an in-memory store for short term storage.
Efficient and scalable long term storage with Cassandra.
Expose a PromQL endpoint, making it compatible with Prometheus compatible tools, like Grafana to view your metrics.

Installing SquirrelDB is easy with Docker. First let’s create a Docker network so all our components will be able to communicate.

docker network create bleemeo

Now let’s run Cassandra that will hold our long term storage.

docker run -d --name "cassandra" --restart unless-stopped --net bleemeo \
    -v cassandra:/var/lib/cassandra \
    -e MAX_HEAP_SIZE=128M -e HEAP_NEWSIZE=24M cassandra

Then we can start SquirrelDB and connect it to Cassandra.

docker run -d --name "squirreldb" --restart unless-stopped --net bleemeo \
    -e SQUIRRELDB_CASSANDRA_ADDRESSES=cassandra:9042 bleemeo/squirreldb

MQTT

MQTT is a standard messaging protocol providing a lightweight publish/subscribe messaging transport. In this example we will use NATS as our MQTT server, it provides a high-performance and scalable messaging system. You are free to use any other MQTT server, it will work the same.

We need to write a configuration file for NATS to make it expose a MQTT endpoint.

cat > nats.conf << EOF
server_name: "bleemeo-mqtt"

jetstream {}

mqtt {
   port: 1883
}
EOF

Then we can run NATS with this configuration.

docker run -d --name "nats" --restart unless-stopped -p 1883:1883 \
    --net bleemeo -v $(pwd)/nats.conf:/etc/nats/nats.conf:ro \
    nats -c /etc/nats/nats.conf

Note that in production the MQTT port should be protected, especially if it’s exposed over internet, NATS should be configured to use TLS and authentication. See NATS TLS documentation and the authentication setup for more information.

SquirrelDB Ingestor

We can run SquirrelDB Ingestor with some configuration to tell him where to find our database and the MQTT server.

docker run -d --name="squirreldb-ingestor" --restart unless-stopped --net bleemeo \
    -e INGESTOR_REMOTE_WRITE_URL="http://squirreldb:9201/api/v1/write" \
    -e INGESTOR_MQTT_BROKER_URL="tcp://nats:1883" \
    bleemeo/squirreldb-ingestor

Again we can check the logs to make it sure it successfully connected to MQTT.

docker logs -f squirreldb-ingestor

You should see the message MQTT connection established.

Grafana

Now that our metrics can be stored in our Time Series Database, we are only missing something to view them and be notified of problems. For that we can use Grafana.

docker run -d --name="grafana" --restart unless-stopped -p 127.0.0.1:3000:3000 \
    --net bleemeo grafana/grafana