InfluxDB is a time-series database: it stores timestamped measurements — server metrics, sensor readings, energy usage, financial ticks — and makes it easy to query them by time range, downsample and aggregate. It pairs naturally with Telegraf (collector) and Grafana (dashboards).
Versions
- InfluxDB 2.x — open-source, widely deployed; Flux and InfluxQL query languages, built-in UI, tokens and buckets.
- InfluxDB 3 — the newer engine (Core is open source, with Enterprise editions), SQL-first, built on Apache Arrow and Parquet.
- 1.x — legacy.
This guide uses 2.x, which is stable and well documented. Check InfluxData’s documentation for the current recommendations before starting a large new project.
1. Run with Docker
mkdir -p ~/influxdb && cd ~/influxdbcompose.yaml:
services:
influxdb:
image: influxdb:2
restart: unless-stopped
ports:
- "127.0.0.1:8086:8086"
volumes:
- influx-data:/var/lib/influxdb2
- influx-config:/etc/influxdb2
environment:
DOCKER_INFLUXDB_INIT_MODE: setup
DOCKER_INFLUXDB_INIT_USERNAME: admin
DOCKER_INFLUXDB_INIT_PASSWORD: ${INFLUX_PASSWORD}
DOCKER_INFLUXDB_INIT_ORG: myorg
DOCKER_INFLUXDB_INIT_BUCKET: metrics
DOCKER_INFLUXDB_INIT_RETENTION: 90d
DOCKER_INFLUXDB_INIT_ADMIN_TOKEN: ${INFLUX_TOKEN}
volumes:
influx-data:
influx-config:cat > .env <<EOF
INFLUX_PASSWORD=$(openssl rand -base64 18)
INFLUX_TOKEN=$(openssl rand -hex 32)
EOF
chmod 600 .env
docker compose up -dThe init variables create the organisation, the first bucket (with 90-day retention) and an admin token on first start.
(Native packages are also available from InfluxData’s apt repository: sudo apt install influxdb2, then influx setup.)
2. UI and access
The UI is on port 8086 (localhost). Use an SSH tunnel (ssh -L 8086:127.0.0.1:8086 user@server) or proxy it through Nginx with HTTPS. Don’t expose 8086 publicly without TLS.
3. Tokens
Create a write-only token for each data source and a read-only token for Grafana, scoped to specific buckets (UI → Load Data → API Tokens, or influx auth create). Keep the admin token for administration only.
4. Write data
InfluxDB uses line protocol: measurement,tags fields timestamp.
curl -s -X POST "http://127.0.0.1:8086/api/v2/write?org=myorg&bucket=metrics&precision=s" \
-H "Authorization: Token $WRITE_TOKEN" \
--data-binary "temperature,room=office,sensor=s1 value=22.4 $(date +%s)"- Tags (indexed, string) — things you filter and group by: host, region, sensor.
- Fields (not indexed) — the values: temperature, cpu_percent.
Avoid tags with unbounded unique values (user IDs, request IDs) — high cardinality is the main performance pitfall.
5. Collect server metrics with Telegraf
sudo apt install -y telegraf # from InfluxData's repository/etc/telegraf/telegraf.conf (relevant parts):
[[outputs.influxdb_v2]]
urls = ["http://127.0.0.1:8086"]
token = "$INFLUX_WRITE_TOKEN"
organization = "myorg"
bucket = "metrics"
[[inputs.cpu]]
[[inputs.mem]]
[[inputs.disk]]
[[inputs.net]]
[[inputs.system]]Telegraf has hundreds of input plugins (Nginx, MySQL, Docker, MQTT, SNMP…). For MQTT-based IoT devices, combine with Mosquitto.
6. Query
Flux example (UI Data Explorer or API):
from(bucket: "metrics")
|> range(start: -6h)
|> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
|> aggregateWindow(every: 1m, fn: mean)InfluxQL is also available through the v1 compatibility API.
7. Grafana
Add an InfluxDB data source in Grafana (Flux or InfluxQL), with the read-only token. See Grafana and Prometheus for setting up Grafana.
Retention and downsampling
Buckets have a retention period; data older than it is deleted automatically. Keep raw data short (e.g. 30–90 days) and use tasks to downsample into a long-term bucket (e.g. hourly means kept for years).
Backups
docker compose exec influxdb influx backup /var/lib/influxdb2/backup-$(date +%F) -t "$INFLUX_TOKEN"Copy the backup directory off the server.
Alternatives
- Prometheus — pull-based metrics, the standard for infrastructure monitoring.
- TimescaleDB — time series inside PostgreSQL with full SQL.
- ClickHouse — fast analytics on huge event tables.