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.

1. Create a Compose project directory.

   $ mkdir -p ~/influxdb-v2/secrets

2. Change into the Compose project directory.

   $ cd ~/influxdb-v2

3. Create the initial admin username secret.

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

4. 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.

5. 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.

6. Restrict the secret file permissions.

   $ chmod 0600 secrets/influxdb2-admin-*

7. 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

8. Confirm that Compose resolves the service name.

   $ docker compose config --services
   influxdb2

9. Confirm that Compose resolves the persistent volumes.

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

10. 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.

11. 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

12. 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.

13. 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"}

14. 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

15. 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.

16. Restart the Compose service.

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

17. 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

18. 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.

19. Clear the token variable from the terminal.

    $ unset INFLUX_TOKEN