{"id":25565949,"url":"https://github.com/laiti/ruuvistack","last_synced_at":"2026-04-29T20:09:18.787Z","repository":{"id":277842382,"uuid":"933704913","full_name":"laiti/ruuvistack","owner":"laiti","description":"Ruuvi dashboard setup with Docker, Caddy, Mosquitto and Grafana","archived":false,"fork":false,"pushed_at":"2025-02-20T17:39:54.000Z","size":405,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T18:39:17.159Z","etag":null,"topics":["caddy","docker-compose","grafana","makefile","mosquitto-mqtt-broker","ruuvi-gateway","ruuvitag"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laiti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-16T14:05:44.000Z","updated_at":"2025-02-18T06:46:05.000Z","dependencies_parsed_at":"2025-02-16T14:50:20.744Z","dependency_job_id":null,"html_url":"https://github.com/laiti/ruuvistack","commit_stats":null,"previous_names":["laiti/ruuvi-dashboard","laiti/ruuvistack"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laiti%2Fruuvistack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laiti%2Fruuvistack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laiti%2Fruuvistack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laiti%2Fruuvistack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laiti","download_url":"https://codeload.github.com/laiti/ruuvistack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239922482,"owners_count":19718969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caddy","docker-compose","grafana","makefile","mosquitto-mqtt-broker","ruuvi-gateway","ruuvitag"],"created_at":"2025-02-20T22:21:18.026Z","updated_at":"2026-03-15T05:30:18.991Z","avatar_url":"https://github.com/laiti.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruuvi-docker\nDocker setup to set up a complete Ruuvitag monitoring stack with alerts. Aims to be highly configurable in a single place (.env file.)\n\n## Components\n\n- [Ruuvi Gateway](https://ruuvi.com/gateway/) - A dedicated device to route Ruuvitag data with MQTT.\n\n- [Eclipse Mosquitto™](https://mosquitto.org/) - An open source MQTT broker.\n\n- [Caddy](https://caddyserver.com/) - The Ultimate Server with Automatic HTTPS.\n\n- [Grafana](https://grafana.com/) - The open and composable observability platform.\n\n- [InfluxDB](https://www.influxdata.com/) - Platform for time series data.\n\n- [RuuviBridge](https://github.com/Scrin/RuuviBridge) - A data bridge between Mosquitto and InfluxDB.\n\n...and of course Docker and Docker-compose.\n\n## Architecture\n\n### As [Mermaid](https://mermaid.live/) graph\n\n![Preview](https://raw.githubusercontent.com/laiti/ruuvi-dashboard/main/doc/architecture.png)\n\n```\nflowchart TD\n    A[Ruuvitags] --\u003e|Bluetooth broadcast| B(Ruuvi Gateway)\n    B --\u003e|MQTT over TLS| C@{ shape: processes, label: \"Mosquitto\" }\n    subgraph Docker containers\n    D(Ruuvibridge) --\u003e|Subscribe via MQTT| C\n    D --\u003e|Write measurement data| E@{ shape: cyl, label: \"InfluxDB\" }\n    F@{ shape: win-pane, label: \"Grafana\" } --\u003e|Read measurement data| E\n    end\n    F --\u003e|Temperature alert via HTTPS API| G@{shape: rect, label: \"Telegram bot\"}\n```\n\n## Setup guide\n\n### In short\nTo bring the Docker containers up:\n1) Populate `.env` file (example available at `examples/` dir)\n2) Create Mosquitto certs with `make certs` and users with `make users`\n3) Create Ruuvibridge config, InfluxDB2 client config and Mosquitto passwd file with `make config`\n4) Run `docker-compose up` in the root directory.\n\nNOTE: This launches Grafana in the public net with `admin/admin` default credentials to the hostname you set in `.env`. Be sure to change the password before anyone else does it. If they do not work, refer to the [grafana-oss docker image documentation](https://hub.docker.com/r/grafana/grafana-oss).\n\nBesides that, there's some manual work to do.\n\n### Mosquitto\n\n#### Encryption\nIf you wish to encrypt your MQTT traffic (highly recommended in public internet), you need to generate certificates. And deliver the client certificate to Ruuvi Gateway. In short the command is `make config` but you might want to check the Makefile for details.\n\nWe possibly could use Caddy as well to encrypt the traffic but I am not sure how well that works with WebSockets.\n\n#### Users\nMosquitto users and passwords are defined in `mosquitto/config/passwd`. Passwords are hashed. To create the file with required gateway and ruuvibridge users, simply command `make users`.\n\n### InfluxDB\nTo use InfluxDB in, you need to create couple of things manually. This setup uses InfluxDB 2.\n\n#### Connecting to InfluxDB\n\nBy default the InfluxDB is accessible only from Grafana and Ruuvibridge containers. Should you wish to run the InfluxDB command, you need to open the port. One way is to enable the `port:` statement from `compose.yaml` and restart container. You can create InfluxDB client config to your home directory (`~/.influxdbv2/configs`) with `make config`.\n\n#### Create ruuvi bucket and config\n\nThe `-r 1825d` sets the retention period in days for the data. Adjust this according to your free disk space and how frequently Ruuvitags send the data. I use the longlife firmware version in my tags to extend battery life and save disk space.\n\n```\n. ./.env\ninflux config create --config-name ${INFLUXDB_BUCKET} --host-url http://localhost:8086 --token ${INFLUXDB_ADMIN_TOKEN} --active\n\ninflux bucket create -n ${INFLUXDB_BUCKET} --org-id ${INFLUXDB_ORGANIZATION} -r 1825d -t \u003ctoken\u003e\n```\n\n#### Create grafana and ruuvibridge users:\n```\n. ./.env\ninflux user create -n ruuvibridge --org ${INFLUXDB_ORGANIZATION}\ninflux user password -n ruuvibridge\n\ninflux user create -n grafana --org ${INFLUXDB_ORGANIZATION}\ninflux user password -n grafana\ninflux auth create --org ${INFLUXDB_ORGANIZATION} --user grafana --read-authorizations --read-buckets\n```\n\nConfigure ruuvibridge token to `ruuvibridge/config.yml` under the `influxdb_publisher`.\n\n### Ruuvibridge\n\nRuuvibridge is configured with just `ruuvibridge/config.yml`, example config is in `examples/ruuvibridge.config.yml`. This setup uses the recommended **MQTT listener** mode. As the traffic between Mosquitto, Ruuvibridge and InfluxDB happens between Docker containers, no SSL is required. You can also create a template from variables in `.env` via `Makefile` with command `make config`\n\nChange the `username` and `password` under `mqtt_listener` to the ones you created in Mosquitto. And configure your Ruuvitag BT addressess under `tag_names` and you should be good to go.\n\n### Ruuvi Gateway settings\n\nEnter the Ruuvi Gateway settings and proceed to page 7 (Cloud Options). Configure as below.\n\n#### 7/11 Cloud Options ([screenshot](doc/ruuvi-gateway-settings-7-cloud-options.png))\n\n-\t✅ Use Ruuvi Cloud and/or a custom server and configure other advanced settings.\n\n#### 8/11 Ruuvi Cloud ([screenshot](doc/ruuvi-gateway-settings-8-custom-server-mqtt.png))\n\n- ✅ MQTT(S)\n   - ✅ MQTT over Secure WebSocket\n    - Server: wss://\u003cMOSQUITTO_BROKER_HOSTNAME from .env\u003e\n    - Port: 8886\n    - Data format\n    \t- ✅ Don't decode, send data in raw format (default)\n    - Username: \u003cMOSQUITTO_GATEWAY_USER from .env\u003e\n    - Password: \u003cMOSQUITTO_GATEWAY_PASSWORD from .env\u003e\n    - Topic prefix\n        - ✅ Use ‘ruuvi’ on the prefix\n        - ✅ Use Ruuvi Gateway's MAC address on the topic prefix\n        - 🟩 Use a custom topic prefix\n    - ✅ Use client SSL certificate (*.pem,*.crt,*.cert,*.key)\n        - \u003cUpload `ruuvigw.crt` and `ruuvigw.key` from `mosquitto/config/certs/clients/` here\u003e\n    - ✅ Use custom SSL certificate for the server (*.pem,*.crt,*.cert)\n    \t- \u003cUpload `mosquitto/config/certs/ca/ca.crt` here\u003e\n\n### Grafana\n\nOnce you've set up Grafana, you can log in, configure InfluxDB as data source and start querying Ruuvitag data if all works. As stated above, the default login is `admin/admin`.\n\n#### Example query for single tag with offset (usually handy with humidity measurements)\n\n```\nfrom(bucket: \"ruuvi\")\n    |\u003e range(start: v.timeRangeStart, stop: v.timeRangeStop)\n    |\u003e filter(fn: (r) =\u003e r._measurement == \"ruuvi_measurements\" and r._field == \"humidity\" and r.name == \"Sauna\")\n    |\u003e map(fn: (r) =\u003e ({r with _value: float(v: r._value) - 5.75 }))\n    |\u003e aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: true)\n    |\u003e yield(name: \"_time\")\n```\n\n#### Example query for alert\n```\nfrom(bucket: \"ruuvi\")\n    |\u003e range(start: -5m)\n    |\u003e filter(fn: (r) =\u003e r._measurement == \"ruuvi_measurements\" and r._field == \"temperature\" and r.name == \"Sauna\")\n```\n\nUsing the `r.name` requires that you've set up the `tag_names` in `ruuvibridge/config.yml` properly.\n\n#### Alerts as Telegram messages\nGrafana supports alert messages via Telegram out of the box. You can find [example alert template](examples/telegram-alert.template) in the `doc/` directory\n## Sources\n\n- https://github.com/mchestr/Secure-MQTT-Docker\n- https://cedalo.com/blog/mqtt-tls-configuration-guide/\n- https://docs.influxdata.com/influxdb/v2/install/use-docker-compose/\n- https://medium.com/@tomer.klein/docker-compose-and-mosquitto-mqtt-simplifying-broker-deployment-7aaf469c07ee\n- https://github.com/sukesh-ak/setup-mosquitto-with-docker/tree/main\n- https://github.com/Scrin/RuuviBridge","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaiti%2Fruuvistack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaiti%2Fruuvistack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaiti%2Fruuvistack/lists"}