influxdata/telegraf-controller repository overview

⁠Telegraf Controller

Telegraf Controller is a web application for managing your Telegraf fleet: build Telegraf configurations visually, serve them to your agents from a single URL, and monitor agent health through heartbeats.

⁠Supported tags

• latest — the most recent stable release
• X.Y — the most recent patch release of a minor version (for example 1.2)
• X.Y.Z — a specific release (for example 1.2.0)

⁠Quick start

docker run -d \
  --name telegraf-controller \
  -p 8888:8888 \
  -p 8000:8000 \
  -e TELEGRAF_CONTROLLER_EULA=accept \
  -v telegraf-controller:/var/lib/telegraf-controller \
  influxdata/telegraf-controller:latest

Open http://localhost:8888⁠ and follow the setup screen to create the owner account. By default Telegraf Controller runs on an embedded SQLite database stored in the mounted volume.

To create the owner account without using the browser (for scripted or infrastructure-as-code deployments), pass all three bootstrap variables:

  -e [email protected] \
  -e OWNER_USERNAME=admin \
  -e OWNER_PASSWORD='<strong password>' \

⁠License (EULA)

Telegraf Controller requires acceptance of its End User License Agreement. Set TELEGRAF_CONTROLLER_EULA=accept to accept it. Without acceptance, the container exits immediately with instructions.

Acceptance is recorded in the data directory, so with a mounted volume you only need the variable on first run or if a future release updates the EULA (release notes call this out). Without a volume, every container start is a fresh instance and requires the variable. Leaving it set permanently (as in the examples here) is safe and idempotent.

Read the full Telegraf Controller EULA⁠.

⁠Data persistence

All state (the EULA acceptance record, the embedded SQLite database, the audit log, and instance identity) lives in /var/lib/telegraf-controller. Mount a volume there. Without a mount, the container is deliberately ephemeral. All data is lost when the container is removed, and the EULA state resets on every start.

The container runs as the unprivileged user telegraf-controller (UID and GID 10001). A named volume gets the right ownership automatically; for a bind mount, make the host directory writable by that user first:

mkdir -p ./telegraf-controller-data
sudo chown 10001:10001 ./telegraf-controller-data

⁠Ports

Both ports must be reachable from your Telegraf agents.

⁠Configuration

Arguments appended to docker run are passed to Telegraf Controller directly. For example: --ssl-cert/--ssl-key to serve HTTPS, or --logs-dir to relocate logs. For the full list:

docker run --rm influxdata/telegraf-controller:latest --help

⁠Using PostgreSQL

For production deployments, point DATABASE_URL at a PostgreSQL database. The engine is selected automatically from the URL scheme, and schema migrations are applied at startup:

docker run -d \
  --name telegraf-controller \
  -p 8888:8888 \
  -p 8000:8000 \
  -e TELEGRAF_CONTROLLER_EULA=accept \
  -e DATABASE_URL="postgresql://user:password@db-host:5432/telegraf_controller" \
  -v telegraf-controller:/var/lib/telegraf-controller \
  influxdata/telegraf-controller:latest

Keep the volume mount even with PostgreSQL — the EULA acceptance record and instance identity still live in the data directory.

⁠Docker Compose

services:
  telegraf-controller:
    image: influxdata/telegraf-controller:latest
    ports:
      - "8888:8888"
      - "8000:8000"
    environment:
      TELEGRAF_CONTROLLER_EULA: accept
      DATABASE_URL: postgresql://postgres:postgres@db:5432/telegraf_controller
    volumes:
      - telegraf-controller:/var/lib/telegraf-controller
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: telegraf_controller
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  telegraf-controller:
  postgres-data:

For SQLite instead, delete the db service, the depends_on block, and the DATABASE_URL line.

⁠Health endpoints

Both are unauthenticated, for container orchestration and load balancers:

• GET /health/live — process is up
• GET /health/ready — dependencies (database) are reachable

The image's built-in HEALTHCHECK probes http://localhost:${APP_PORT}/health/ready. If you serve HTTPS with --ssl-cert/--ssl-key, or change the port with --port instead of APP_PORT, override it (for example with --health-cmd or --no-healthcheck).

⁠Learn more

• Telegraf Controller documentation⁠
• Telegraf⁠
• InfluxData⁠