Does InfluxDB's Docker init mode skip setup when the volume already has data?

Yes, the InfluxDB 2.7.x Docker image skips the DOCKER_INFLUXDB_INIT_MODE=setup process if it detects an existing database in the mounted volume. This mechanism is designed to prevent overwriting user data or regenerating administrative credentials during container restarts.

How the Init Check Works

The entrypoint script checks for the existence of specific metadata within the data directory (typically /var/lib/influxdb). Specifically, it looks for the internal BoltDB file and the storage engine directory structure. If these are present, the script assumes the instance has already been initialized and exits the setup logic immediately, ignoring all DOCKER_INFLUXDB_INIT_* environment variables.

API Behavior and Idempotency

If you attempt to call the /api/v2/setup endpoint programmatically on an instance that is already initialized, the behavior is as follows:

• Status Code: The API will return a 400 Bad Request.
n
• Token Behavior: It will not create duplicate operator tokens or overwrite the existing configuration. The request simply fails because the setup state (organization, user, and bucket) for that specific configuration is already locked.

Recommended Pattern for Integration Tests

For repeatable integration tests where you use persistent volumes between runs, relying solely on the container's init mode can be brittle if tests fail midway. Instead, use the following idempotency pattern:

1. Start the container and wait for the /health endpoint to return success.
2. Attempt a GET request to /api/v2/buckets using your pre-seeded or environment-defined admin token.
3. If the request returns 200 OK, the instance is ready; skip the setup step.
4. If the request returns 401 Unauthorized or 404, invoke your /api/v2/setup logic.

Security Note for CI Environments

The /api/v2/setup endpoint is unauthenticated to allow for first-run configuration. In a shared CI network, this is a security risk as any entity with network access could potentially initialize an empty-DB instance. It is recommended to ensure the container is only exposed to internal CI networks or protected by a firewall once the setup is complete.