InfluxDB

Last reviewed Aug 26, 2026 · 784 words

InfluxDB's biggest problem for a self-hoster is that "InfluxDB" names three different databases. Version 1 speaks InfluxQL, version 2 speaks Flux, and version 3 is a Rust rewrite that speaks SQL and InfluxQL and dropped Flux. Every tutorial on the internet targets one of them without saying which, and a dashboard query copied from the wrong generation fails with an error that mentions none of this. Pick the version before anything else. For a homelab collecting metrics from Home Assistant, Telegraf or a few sensors, my answer is the influxdb:2 image, and the rest of this guide explains why that is still true in 2026 despite version 3 being the future.

The version table you will wish someone had shown you

The "query language changes between versions" line in the catalogue is this table. Flux, the functional language version 2 introduced, is officially in maintenance and absent from version 3. If you write Flux dashboards today you are writing something you will port later. That is the trap, and the way around it is to use the InfluxQL compatibility endpoint on version 2, which gives you queries that work on 1, 2 and 3.

Why version 2 still wins for a homelab

Version 3 Core is open source and fast, but at last check the Core edition limits queries to roughly the most recent 72 hours of data, with longer-range queries reserved for the commercial Enterprise edition. For a real-time dashboard that is fine; for "show me my solar production over the last year" it is a dealbreaker, and long-range history is most of why a homelab keeps a time series database at all. The catalogue's "clustering reserved for enterprise" is the same commercial shape: the open version is single-node in every generation.

Version 2 has no such window, the built-in UI is good enough that you may never open Grafana for simple views, retention is a per-bucket setting, and the Home Assistant integration targets it directly. It runs in 512 MB of RAM comfortably for a household's worth of sensors.

The compose file that does the setup for you

The image will initialise itself from environment variables on first run, which saves the influx setup dance:

services:
  influxdb:
    image: influxdb:2
    ports:
      - "8086:8086"
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=change-this-now
      - DOCKER_INFLUXDB_INIT_ORG=home
      - DOCKER_INFLUXDB_INIT_BUCKET=sensors
      - DOCKER_INFLUXDB_INIT_RETENTION=365d
    volumes:
      - ./influxdb2-data:/var/lib/influxdb2
      - ./influxdb2-config:/etc/influxdb2
    restart: unless-stopped

Set the retention at creation. An unbounded bucket fed by Home Assistant's default of every state change will grow by hundreds of megabytes a month, and the fix later is a manual delete. After first boot, create a second token with write-only permission on the bucket for Telegraf and Home Assistant; the operator token from setup should not be in any config file but yours.

Telegraf is the reason to choose it over Prometheus

Prometheus pulls from exporters; InfluxDB accepts pushes, and Telegraf is the push agent with about 300 input plugins covering Docker, SNMP, MQTT, system stats, Modbus and most things with a serial port. For IoT and sensor data, push is the natural model: a battery device wakes up, writes a line, and sleeps, which the pull model handles badly. For monitoring long-lived services, Prometheus is the better fit and that is the split that decides most monitoring stacks. If your data is mostly "things in the house", InfluxDB plus Telegraf is right; if it is mostly "containers on a server", it is not. VictoriaMetrics is the tool to look at if you want one database that accepts both InfluxDB line protocol and Prometheus scrapes.

What I'd do

Run influxdb:2 with the compose above, one bucket per data source with an explicit retention, InfluxQL rather than Flux for anything I write by hand, and Grafana on top once I have more than 3 dashboards. I would ignore version 3 until the query window changes or my history need shrinks, and I would not touch version 1 for a new install. Three query languages is a mess the project created for itself, but the version 2 server underneath is a solid, low-maintenance store for years of household metrics on half a gigabyte of RAM.