influxdb3-test-setup

name	influxdb3-test-setup
description	Set up InfluxDB 3 Core and Enterprise instances for running documentation code block tests. Handles service initialization, worktree-specific databases, and test environment configuration. Use when preparing to run InfluxDB 3 code block tests, starting Core or Enterprise instances, or configuring .env.test and worktree-specific test databases.

InfluxDB 3 Test Setup Skill

Purpose

This skill guides agents through setting up InfluxDB 3 Core and Enterprise instances for testing documentation code blocks. It covers service initialization, creating worktree-specific databases for test isolation, and configuring the test environment.

Architecture Overview

~/influxdata-docs/.influxdb3/          # Shared across all worktrees
├── enterprise/
│   ├── .env                           # License email (INFLUXDB3_ENTERPRISE_LICENSE_EMAIL)
│   └── data/                          # Enterprise data (persists license)
└── plugins/                           # Shared plugins

<worktree>/test/.influxdb3/            # Per-worktree (gitignored)
├── core/
│   ├── .token                         # Core auth token
│   ├── data/                          # Core data
│   └── plugins/                       # Custom plugins
└── .env.test                          # Test credentials

Key Design Decisions:

• Core: Per-worktree instance (port 8282) - data isolated to worktree
• Enterprise: Shared instance (port 8181) - license persists across worktrees
• Databases: Create worktree-named databases for test isolation on shared Enterprise

Quick Reference

Task	Command
Initialize Core	./test/scripts/init-influxdb3.sh core
Initialize Enterprise	./test/scripts/init-influxdb3.sh enterprise
Initialize both	./test/scripts/init-influxdb3.sh all
Check Core status	curl -i http://localhost:8282/ping
Check Enterprise status	curl -i http://localhost:8181/ping -H "Authorization: Bearer $TOKEN"
Run code block tests	yarn test:codeblocks:v2

Setup Workflows

Workflow 1: Core Only (Per-Worktree)

Use when testing Core-specific documentation or when you need complete isolation.

# 1. Initialize Core
./test/scripts/init-influxdb3.sh core

# 2. Verify it's running
curl -i http://localhost:8282/ping

# 3. Get your token (JSON format)
jq -r .token test/.influxdb3/core/.token

# 4. Create a database for testing
curl -X POST "http://localhost:8282/api/v3/configure/database" \
  -H "Authorization: Bearer $(jq -r .token test/.influxdb3/core/.token)" \
  -H "Content-Type: application/json" \
  -d '{"db": "test_db"}'

Workflow 2: Enterprise (Shared Instance)

Use when testing Enterprise-specific documentation. Creates worktree-named database for isolation.

# 1. First-time only: Create .env file with license email
mkdir -p ~/influxdata-docs/.influxdb3/enterprise
echo 'INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=[e-mail]' > \
  ~/influxdata-docs/.influxdb3/enterprise/.env

# 2. Initialize Enterprise (generates admin token and starts service)
./test/scripts/init-influxdb3.sh enterprise

# 3. Get admin token from the generated file
ADMIN_TOKEN=$(jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json)

# 4. Verify it's running
curl -i http://localhost:8181/ping \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 5. Create worktree-named database for test isolation
WORKTREE_NAME=$(basename "$(pwd)" | tr '-' '_')
curl -X POST "http://localhost:8181/api/v3/configure/database" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"db\": \"${WORKTREE_NAME}_db\"}"

Workflow 3: Both Services

Use when testing documentation that covers both Core and Enterprise.

# Initialize both
./test/scripts/init-influxdb3.sh all

# Verify both are running
curl -i http://localhost:8282/ping  # Core (no auth by default)
curl -i http://localhost:8181/ping -H "Authorization: Bearer $TOKEN"  # Enterprise

Creating Worktree-Specific Databases

When using the shared Enterprise instance, create databases named after the worktree to isolate test data:

# Get worktree name (converts hyphens to underscores for valid DB names)
WORKTREE_NAME=$(basename "$(pwd)" | tr '-' '_')
echo "Database name: ${WORKTREE_NAME}_db"

# Create database
curl -X POST "http://localhost:8181/api/v3/configure/database" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"db\": \"${WORKTREE_NAME}_db\"}"

# List databases to verify
curl "http://localhost:8181/api/v3/configure/database?format=json" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Naming Convention:

• Worktree: docs-v2-influxdb3-version-detection-headers
• Database: docs_v2_influxdb3_version_detection_headers_db

Test Environment Configuration

Configure .env.test for Code Block Tests

Create content/<product>/.env.test with test credentials:

# For Enterprise testing
ADMIN_TOKEN=$(jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json)
cat > content/influxdb3/enterprise/.env.test << EOF
INFLUX_HOST=http://localhost:8181
INFLUX_TOKEN=$ADMIN_TOKEN
INFLUX_DATABASE=YOUR_WORKTREE_DB
EOF

# For Core testing
cat > content/influxdb3/core/.env.test << EOF
INFLUX_HOST=http://localhost:8282
INFLUX_TOKEN=$(jq -r .token test/.influxdb3/core/.token)
INFLUX_DATABASE=test_db
EOF

Run Code Block Tests

# Test specific product
yarn test:codeblocks:v2

# Or run pytest directly
docker compose run --rm v2-pytest

Troubleshooting

Enterprise Won't Start

Symptom: Container exits immediately

Check:

# View container logs
docker logs influxdb3-enterprise

# Common issues:
# 1. Missing .env file
ls -la ~/influxdata-docs/.influxdb3/enterprise/.env

# 2. Wrong env var name (must be INFLUXDB3_ENTERPRISE_LICENSE_EMAIL)
cat ~/influxdata-docs/.influxdb3/enterprise/.env

# 3. Missing admin-token.json (run init script to generate)
ls -la ~/influxdata-docs/.influxdb3/enterprise/admin-token.json

Core Token Not Working

Symptom: 401 Unauthorized

Check:

# Verify token file exists and is valid JSON
cat test/.influxdb3/core/.token
jq . test/.influxdb3/core/.token  # Should parse without errors

# Verify token is accessible in container (as secret)
docker exec influxdb3-core cat /run/secrets/influxdb3-core-token

When Enterprise Is Unavailable

If Enterprise won't start (license expired, port conflict, Docker issue):

1. Fix the root cause first — check container logs, verify the license email is valid (not a placeholder), and re-run the init script.
2. Use Core for non-Enterprise features — Core requires no license and can verify most shared InfluxDB 3 behavior (queries, writes, databases, tables).
3. Flag Enterprise-only gaps — if the feature under test is Enterprise-only (clustering, RBAC, table/database retention, read replicas), state explicitly that runtime verification was not possible and why. Do not guess at behavior.

Port Already in Use

Symptom: "port is already allocated"

Fix:

# Find what's using the port
lsof -i :8181  # Enterprise
lsof -i :8282  # Core

# Stop existing containers
docker compose down influxdb3-enterprise influxdb3-core

Getting the Admin Token

The init script generates and saves admin tokens to JSON files for both Core and Enterprise:

# Core token
cat test/.influxdb3/core/.token
jq -r .token test/.influxdb3/core/.token

# Enterprise token
cat ~/influxdata-docs/.influxdb3/enterprise/admin-token.json
jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json

# Export for use in commands
export INFLUXDB3_CORE_TOKEN=$(jq -r .token test/.influxdb3/core/.token)
export INFLUXDB3_ENTERPRISE_TOKEN=$(jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json)

# Use in API calls
curl -i http://localhost:8282/ping -H "Authorization: Bearer $INFLUXDB3_CORE_TOKEN"
curl -i http://localhost:8181/ping -H "Authorization: Bearer $INFLUXDB3_ENTERPRISE_TOKEN"

Token File Format (both Core and Enterprise):

{
  "token": "64-character-hexadecimal-token",
  "description": "Admin token for InfluxDB 3 Core/Enterprise"
}

Service Comparison

Aspect	Core	Enterprise
Port	8282	8181
Data location	Per-worktree	Shared
Auth default	Optional	Required
License	None	Trial/Paid
Use case	Isolated testing	Shared testing with worktree DBs

Related Files

• Init script: test/scripts/init-influxdb3.sh
• Docker Compose: compose.yaml (services: influxdb3-core, influxdb3-enterprise)
• Test config: content/<product>/.env.test

Related Skills

• cypress-e2e-testing - For running E2E tests on documentation UI
• docs-cli-workflow - For creating/editing documentation content