How to set up InfluxDB OSS v2 with Docker Compose

Setting up InfluxDB OSS v2 with Docker Compose starts a containerized time-series server with repeatable service configuration, named volumes, and startup credentials kept outside the Compose file. Use it for lab services, development stacks, or small deployments where Compose already manages the local container runtime.

The official influxdb:2 image initializes a v2 instance when DOCKER_INFLUXDB_INIT_MODE is set to setup. In this setup, Compose secrets provide the initial username, password, and operator token through files mounted under /run/secrets, while the organization and bucket names stay visible in the service environment.

Named volumes hold /var/lib/influxdb2 and /etc/influxdb2 so the initialized metadata, bucket, and configuration survive container recreation. Keep the operator token in a secret manager before the first start, because newer InfluxDB OSS v2 releases store API tokens as hashes and cannot recover plaintext token values from disk.

Steps to set up InfluxDB OSS v2 with Docker Compose:

Create a Compose project directory.
```
$ mkdir -p ~/influxdb-v2/secrets
```
Change into the Compose project directory.
```
$ cd ~/influxdb-v2
```

Create the initial admin username secret.

$ printf '%s\n' 'admin' > secrets/influxdb2-admin-username

Generate the initial admin password secret.
```
$ openssl rand -base64 32 > secrets/influxdb2-admin-password
```
Use a password manager or another approved secret generator when operations policy controls initial service passwords.
Generate the initial operator token secret.
```
$ openssl rand -base64 48 > secrets/influxdb2-admin-token
```
The operator token can administer the InfluxDB v2 instance. Store it in a secret manager and keep it out of shared terminals, transcripts, screenshots, and source control.
Restrict the secret file permissions.
```
$ chmod 0600 secrets/influxdb2-admin-*
```

Save the Compose file.

$ vi compose.yaml

compose.yaml

services:
  influxdb2:
    image: influxdb:2
    ports:
      - "8086:8086"
    environment:
      DOCKER_INFLUXDB_INIT_MODE: setup
      DOCKER_INFLUXDB_INIT_USERNAME_FILE: /run/secrets/influxdb2-admin-username
      DOCKER_INFLUXDB_INIT_PASSWORD_FILE: /run/secrets/influxdb2-admin-password
      DOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE: /run/secrets/influxdb2-admin-token
      DOCKER_INFLUXDB_INIT_ORG: ops
      DOCKER_INFLUXDB_INIT_BUCKET: app-metrics
    secrets:
      - influxdb2-admin-username
      - influxdb2-admin-password
      - influxdb2-admin-token
    volumes:
      - influxdb2-data:/var/lib/influxdb2
      - influxdb2-config:/etc/influxdb2
    healthcheck:
      test: ["CMD", "influx", "ping", "--host", "http://localhost:8086"]
      interval: 10s
      timeout: 5s
      retries: 6
      start_period: 30s

secrets:
  influxdb2-admin-username:
    file: ./secrets/influxdb2-admin-username
  influxdb2-admin-password:
    file: ./secrets/influxdb2-admin-password
  influxdb2-admin-token:
    file: ./secrets/influxdb2-admin-token

volumes:
  influxdb2-data:
  influxdb2-config:

Use a tested, specific v2 image tag instead of latest when release control matters. The influxdb:2 tag keeps the deployment on the v2 image track.
Tool: Docker Compose Healthchecks Checker

Confirm that Compose resolves the service name.
```
$ docker compose config --services
influxdb2
```

Confirm that Compose resolves the persistent volumes.

$ docker compose config --volumes
influxdb2-data
influxdb2-config

Start InfluxDB and wait for the healthcheck.

$ docker compose up --detach --wait influxdb2
Network influxdb-v2_default Created
Volume influxdb-v2_influxdb2-data Created
Volume influxdb-v2_influxdb2-config Created
Container influxdb-v2-influxdb2-1 Created
Container influxdb-v2-influxdb2-1 Started
Container influxdb-v2-influxdb2-1 Healthy

Initialization variables run only when the mounted v2 data and configuration volumes do not already contain initialized metadata. Use a new project or backed-up volumes when testing different first-start credentials.

Check the Compose service state.

$ docker compose ps influxdb2
NAME                     IMAGE        COMMAND                  SERVICE     STATUS                    PORTS
influxdb-v2-influxdb2-1  influxdb:2   "/entrypoint.sh infl..."  influxdb2   Up 5 seconds (healthy)    0.0.0.0:8086->8086/tcp

Ping the server from inside the Compose service.
```
$ docker compose exec influxdb2 influx ping --host http://localhost:8086
OK
```
influx ping checks the /health endpoint and does not require an API token.

Check the published HTTP health endpoint from the host.

$ curl --silent --show-error http://localhost:8086/health
{"name":"influxdb","message":"ready for queries and writes","status":"pass","checks":[],"version":"v2.9.1","commit":"d4fa1941fd"}

Load the operator token into the current terminal.
```
$ export INFLUX_TOKEN="$(cat secrets/influxdb2-admin-token)"
```
Keep the shell session private while the token variable is set. Use a scoped token for day-to-day clients after the server is running.
Related: How to create a scoped InfluxDB v2 API token

List the initialized bucket from inside the container.

$ docker compose exec influxdb2 influx bucket list --org ops --token "$INFLUX_TOKEN" --name app-metrics
ID                 Name          Retention   Shard group duration   Organization ID      Schema Type
44aa4dbf8c577228   app-metrics   infinite    168h0m0s               f72f39af626d8b29     implicit

The bucket row confirms that first-start setup created the organization, operator token, and initial bucket.

Restart the Compose service.

$ docker compose restart influxdb2
Container influxdb-v2-influxdb2-1 Restarting
Container influxdb-v2-influxdb2-1 Started

Confirm the service returns to a healthy state after restart.

$ docker compose ps influxdb2
NAME                     IMAGE        COMMAND                  SERVICE     STATUS                    PORTS
influxdb-v2-influxdb2-1  influxdb:2   "/entrypoint.sh infl..."  influxdb2   Up 10 seconds (healthy)   0.0.0.0:8086->8086/tcp

List the bucket again after restart.

$ docker compose exec influxdb2 influx bucket list --org ops --token "$INFLUX_TOKEN" --name app-metrics
ID                 Name          Retention   Shard group duration   Organization ID      Schema Type
44aa4dbf8c577228   app-metrics   infinite    168h0m0s               f72f39af626d8b29     implicit

The same bucket after restart confirms the v2 metadata stayed on the named volumes instead of being recreated in a disposable container layer.

Clear the token variable from the terminal.
```
$ unset INFLUX_TOKEN
```