Run Telegraf Controller in Docker

Use the official influxdata/telegraf-controller Docker image to run Telegraf Controller as a container. The image contains the same signed executable that is attached to each release, supports both linux/amd64 and linux/arm64, and runs as a non-root user.

• Image and supported tags
• Quick start
• Accept the EULA
• Persist your data
• Configure the container
• Set up the owner account
• Use PostgreSQL
• Use Docker Compose
• Container health checks
• Next steps

Image and supported tags

The image is published to Docker Hub as influxdata/telegraf-controller with the following tags:

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

Pin a specific version in production so deployments are reproducible and upgrades are deliberate. The examples in this guide pin the current release.

Quick start

1. Run the Telegraf Controller container:

   docker run --detach \
     --name telegraf-controller \
     --publish 8888:8888 \
     --publish 8000:8000 \
     --env TELEGRAF_CONTROLLER_EULA=accept \
     --volume telegraf-controller:/var/lib/telegraf-controller \
     influxdata/telegraf-controller:1.2.0

2. 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. Telegraf agents fetch configurations from port 8888 and send heartbeats to port 8000, so publish both ports on an interface your agents can reach.

Accept the EULA

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

Acceptance is recorded in the data directory. With a mounted volume, you only need the variable on the first run, or again when you upgrade to a release that updates the EULA (release notes call this out). Without a volume, every container start is a fresh instance and requires the variable. Leaving the variable set permanently, as the examples in this guide do, is safe. Repeated acceptance has no additional effect.

Persist your data

The container stores all of its state in /var/lib/telegraf-controller: the EULA acceptance record, the embedded SQLite database, the audit log, and instance identity. Mount a volume at that path, as every example in this guide does.

The container runs as the unprivileged user telegraf-controller (UID and GID 10001). Named volumes (for example, --volume telegraf-controller:/var/lib/telegraf-controller) get the right ownership automatically. If you bind-mount a host directory instead, make the directory writable by that user first:

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

Configure the container

Pass configuration as environment variables with --env, or append command-line flags after the image name. Flags take precedence over environment variables. For the complete list of options, see Configuration options.

For example, to print the version:

docker run --rm influxdata/telegraf-controller:1.2.0 --version

Inside the container, Telegraf Controller listens on ports 8888 (web interface, API, and agent configuration downloads) and 8000 (agent heartbeats). If you publish a different host port or serve Telegraf Controller behind a reverse proxy, set the public URL options so links and CORS checks use the external address.

Telegraf Controller secures login sessions with a secret that is generated at random on each start, so users are signed out whenever the container restarts. To keep sessions valid across restarts, set SESSION_SECRET to a long random value and pass the same value on every start. See session-secret.

Enable TLS

To serve HTTPS, mount your certificate and key into the container and point the TLS options at them:

docker run --detach \
  --name telegraf-controller \
  --publish 8888:8888 \
  --publish 8000:8000 \
  --env TELEGRAF_CONTROLLER_EULA=accept \
  --env SSL_CERT_PATH=/etc/telegraf-controller/tls/server.crt \
  --env SSL_KEY_PATH=/etc/telegraf-controller/tls/server.key \
  --volume 
HOST_TLS_DIR
:/etc/telegraf-controller/tls:ro \
  --volume telegraf-controller:/var/lib/telegraf-controller \
  influxdata/telegraf-controller:1.2.0

Replace HOST_TLS_DIR with the host directory that contains your TLS certificate (server.crt) and private key (server.key).

The built-in container health check uses plain HTTP, so override it when you serve HTTPS. See Container health checks.

To make agents trust the certificate, see Secure agent connections with TLS.

Set up the owner account

By default, the first visit to the web interface walks you through creating the owner account. For automated deployments, create the owner at startup by passing all three bootstrap variables:

docker run --detach \
  --name telegraf-controller \
  --publish 8888:8888 \
  --publish 8000:8000 \
  --env TELEGRAF_CONTROLLER_EULA=accept \
  --env OWNER_EMAIL=
OWNER_EMAIL_ADDRESS
 \
  --env OWNER_USERNAME=
OWNER_ACCOUNT_USERNAME
 \
  --env OWNER_PASSWORD=
OWNER_ACCOUNT_PASSWORD
 \
  --volume telegraf-controller:/var/lib/telegraf-controller \
  influxdata/telegraf-controller:1.2.0

Replace the following:

• OWNER_EMAIL_ADDRESS: the owner’s email address.
• OWNER_ACCOUNT_USERNAME: the owner’s username.
• OWNER_ACCOUNT_PASSWORD: the owner’s password.

All three variables must be set together. See Owner account options.

Use PostgreSQL

For production deployments, point DATABASE_URL at a PostgreSQL database. Telegraf Controller selects the database engine from the URL scheme and applies schema migrations automatically at startup:

docker run --detach \
  --name telegraf-controller \
  --publish 8888:8888 \
  --publish 8000:8000 \
  --env TELEGRAF_CONTROLLER_EULA=accept \
  --env DATABASE_URL="postgresql://
POSTGRES_USER
:
POSTGRES_PASSWORD
@
POSTGRES_HOST
:5432/telegraf_controller" \
  --volume telegraf-controller:/var/lib/telegraf-controller \
  influxdata/telegraf-controller:1.2.0

Replace the following:

• POSTGRES_USER and POSTGRES_PASSWORD: the credentials for the PostgreSQL database.
• POSTGRES_HOST: the hostname or address of the PostgreSQL database.

Still keep the volume mount when using PostgreSQL. The EULA acceptance record and instance identity live in the data directory.

Use Docker Compose

The following docker-compose.yml runs Telegraf Controller with a PostgreSQL database:

services:
  telegraf-controller:
    image: influxdata/telegraf-controller:1.2.0
    container_name: telegraf-controller
    ports:
      - "8888:8888"
      - "8000:8000"
    environment:
      TELEGRAF_CONTROLLER_EULA: accept
      DATABASE_URL: postgresql://
postgres_user
:
postgres_password
@db:5432/telegraf_controller
    volumes:
      - telegraf-controller:/var/lib/telegraf-controller
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy

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

volumes:
  telegraf-controller:
  postgres-data:

Replace the following:

• postgres_user and postgres_password: the username and password for the PostgreSQL db service. The same values appear in DATABASE_URL so Telegraf Controller can connect to the database.

Start the services:

docker compose up -d

To use the embedded SQLite database instead, remove the db service, the depends_on block, and the DATABASE_URL line.

Container health checks

The image includes a built-in Docker health check that requests http://localhost:${APP_PORT}/health/ready every 30 seconds, with a 5-second timeout and a 30-second start period. Check the container’s health state with the following command:

docker inspect --format '{{.State.Health.Status}}' telegraf-controller

For orchestrators and load balancers, Telegraf Controller exposes two unauthenticated endpoints on the API port:

• GET /health/live: the process is up.
• GET /health/ready: dependencies, including the database, are reachable.

Next steps

• Get started with Telegraf Controller
• Apply a Telegraf Enterprise license
• Upgrade a Docker deployment