Skip to content

Commit a32b566

Browse files
jstirnamanCopilot
jstirnaman
and
Copilot
authored
test(influxdb3): Improve InfluxDB 3 Core and Enterprise Docker services (#6750)
* test(influxdb3): Improve InfluxDB 3 Core and Enterprise Docker services Improve Docker Compose services and initialization script for testing InfluxDB 3 Core and Enterprise endpoints. compose.yaml changes: - Add influxdb3-core service with per-worktree data isolation - Add influxdb3-core-noauth service for endpoint testing without auth - Add influxdb3-enterprise service with trial license configuration - Fix env_file handling (use optional path, remove variable override) - Add detailed usage comments for each service New files: - test/scripts/init-influxdb3.sh: Helper script to initialize services, create directories, and validate configuration - Enterprise configuration uses shared data at ~/influxdata-docs/.influxdb3/ to persist license and data across worktrees. - .claude/skills/influxdb3-test-setup/SKILL.md. It covers: 1. Architecture overview - Shows the directory structure for shared vs per-worktree data 2. Quick reference - Common commands table 3. Setup workflows - Core only, Enterprise only, or both 4. Worktree-specific databases - How to create isolated databases named after the worktree 5. Test environment configuration - Setting up .env.test files for code block tests 6. Troubleshooting - Common issues (license, auth, ports) 7. Service comparison - Core vs Enterprise differences The skill references the init script but keeps database creation as a separate workflow step, allowing flexibility for different testing scenarios. * docs(copilot): Document influxdb3-test-setup skill in Copilot instructions (#6751) * Initial plan * docs(copilot): Add influxdb3-test-setup skill documentation to instructions - Add InfluxDB 3 Test Setup subsection under Testing section with quick reference commands - Add Skills section under Specialized Instructions with all available skills - Document influxdb3-test-setup skill alongside existing skills (cypress-e2e-testing, docs-cli-workflow, hugo-template-dev) - Include links to skill files and brief descriptions for discoverability Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com> * chore(ci): Refactor InfluxDB 3 token handling to use JSON secrets - Store Core and Enterprise tokens as JSON files with metadata - Update SKILL.md instructions for jq-based token extraction - Use Docker secrets for secure token mounting in compose.yaml - Update init-influxdb3.sh to generate JSON token files - Refactor compose.yaml to mount token files as secrets, not binds - Standardize API examples and environment setup for new token format * docs(influxdb3): Update token documentation for Docker Compose and CI/CD (#6756) - Add 'description' field to offline admin token schema alongside 'expiry_millis' - Add new section for Docker Compose with preconfigured admin tokens - Document Docker secrets for secure token management - Add CI/CD setup instructions using environment variables - Standardize on INFLUXDB3_AUTH_TOKEN environment variable Both 'description' and 'expiry_millis' are optional fields supported by the InfluxDB 3 server when reading preconfigured token files. * Revert "docs(influxdb3): Update token documentation for Docker Compose and CI…" (#6757) This reverts commit 5c786ac. --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
1 parent 6ae06a3 commit a32b566

File tree

4 files changed

+622
-38
lines changed

4 files changed

+622
-38
lines changed

‎.claude/skills/influxdb3-test-setup/SKILL.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
---
2+
name: influxdb3-test-setup
3+
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.
4+
author: InfluxData
5+
version: "1.0"
6+
---
7+
8+
# InfluxDB 3 Test Setup Skill
9+
10+
## Purpose
11+
12+
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.
13+
14+
## Architecture Overview
15+
16+
```
17+
~/influxdata-docs/.influxdb3/ # Shared across all worktrees
18+
├── enterprise/
19+
│ ├── .env # License email (INFLUXDB3_ENTERPRISE_LICENSE_EMAIL)
20+
│ └── data/ # Enterprise data (persists license)
21+
└── plugins/ # Shared plugins
22+
23+
<worktree>/test/.influxdb3/ # Per-worktree (gitignored)
24+
├── core/
25+
│ ├── .token # Core auth token
26+
│ ├── data/ # Core data
27+
│ └── plugins/ # Custom plugins
28+
└── .env.test # Test credentials
29+
```
30+
31+
**Key Design Decisions:**
32+
33+
- **Core**: Per-worktree instance (port 8282) - data isolated to worktree
34+
- **Enterprise**: Shared instance (port 8181) - license persists across worktrees
35+
- **Databases**: Create worktree-named databases for test isolation on shared Enterprise
36+
37+
## Quick Reference
38+
39+
| Task | Command |
40+
| ----------------------- | ---------------------------------------------------------------------- |
41+
| Initialize Core | `./test/scripts/init-influxdb3.sh core` |
42+
| Initialize Enterprise | `./test/scripts/init-influxdb3.sh enterprise` |
43+
| Initialize both | `./test/scripts/init-influxdb3.sh all` |
44+
| Check Core status | `curl -i http://localhost:8282/ping` |
45+
| Check Enterprise status | `curl -i http://localhost:8181/ping -H "Authorization: Bearer $TOKEN"` |
46+
| Run code block tests | `yarn test:codeblocks:v2` |
47+
48+
## Setup Workflows
49+
50+
### Workflow 1: Core Only (Per-Worktree)
51+
52+
Use when testing Core-specific documentation or when you need complete isolation.
53+
54+
```bash
55+
# 1. Initialize Core
56+
./test/scripts/init-influxdb3.sh core
57+
58+
# 2. Verify it's running
59+
curl -i http://localhost:8282/ping
60+
61+
# 3. Get your token (JSON format)
62+
jq -r .token test/.influxdb3/core/.token
63+
64+
# 4. Create a database for testing
65+
curl -X POST "http://localhost:8282/api/v3/configure/database" \
66+
-H "Authorization: Bearer $(jq -r .token test/.influxdb3/core/.token)" \
67+
-H "Content-Type: application/json" \
68+
-d '{"db": "test_db"}'
69+
```
70+
71+
### Workflow 2: Enterprise (Shared Instance)
72+
73+
Use when testing Enterprise-specific documentation. Creates worktree-named database for isolation.
74+
75+
```bash
76+
# 1. First-time only: Create .env file with license email
77+
mkdir -p ~/influxdata-docs/.influxdb3/enterprise
78+
echo 'INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=your-email@example.com' > \
79+
~/influxdata-docs/.influxdb3/enterprise/.env
80+
81+
# 2. Initialize Enterprise (generates admin token and starts service)
82+
./test/scripts/init-influxdb3.sh enterprise
83+
84+
# 3. Get admin token from the generated file
85+
ADMIN_TOKEN=$(jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json)
86+
87+
# 4. Verify it's running
88+
curl -i http://localhost:8181/ping \
89+
-H "Authorization: Bearer $ADMIN_TOKEN"
90+
91+
# 5. Create worktree-named database for test isolation
92+
WORKTREE_NAME=$(basename "$(pwd)" | tr '-' '_')
93+
curl -X POST "http://localhost:8181/api/v3/configure/database" \
94+
-H "Authorization: Bearer $ADMIN_TOKEN" \
95+
-H "Content-Type: application/json" \
96+
-d "{\"db\": \"${WORKTREE_NAME}_db\"}"
97+
```
98+
99+
### Workflow 3: Both Services
100+
101+
Use when testing documentation that covers both Core and Enterprise.
102+
103+
```bash
104+
# Initialize both
105+
./test/scripts/init-influxdb3.sh all
106+
107+
# Verify both are running
108+
curl -i http://localhost:8282/ping # Core (no auth by default)
109+
curl -i http://localhost:8181/ping -H "Authorization: Bearer $TOKEN" # Enterprise
110+
```
111+
112+
## Creating Worktree-Specific Databases
113+
114+
When using the shared Enterprise instance, create databases named after the worktree to isolate test data:
115+
116+
```bash
117+
# Get worktree name (converts hyphens to underscores for valid DB names)
118+
WORKTREE_NAME=$(basename "$(pwd)" | tr '-' '_')
119+
echo "Database name: ${WORKTREE_NAME}_db"
120+
121+
# Create database
122+
curl -X POST "http://localhost:8181/api/v3/configure/database" \
123+
-H "Authorization: Bearer $ADMIN_TOKEN" \
124+
-H "Content-Type: application/json" \
125+
-d "{\"db\": \"${WORKTREE_NAME}_db\"}"
126+
127+
# List databases to verify
128+
curl "http://localhost:8181/api/v3/configure/database" \
129+
-H "Authorization: Bearer $ADMIN_TOKEN"
130+
```
131+
132+
**Naming Convention:**
133+
134+
- Worktree: `docs-v2-influxdb3-version-detection-headers`
135+
- Database: `docs_v2_influxdb3_version_detection_headers_db`
136+
137+
## Test Environment Configuration
138+
139+
### Configure .env.test for Code Block Tests
140+
141+
Create `content/<product>/.env.test` with test credentials:
142+
143+
```bash
144+
# For Enterprise testing
145+
ADMIN_TOKEN=$(jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json)
146+
cat > content/influxdb3/enterprise/.env.test << EOF
147+
INFLUX_HOST=http://localhost:8181
148+
INFLUX_TOKEN=$ADMIN_TOKEN
149+
INFLUX_DATABASE=YOUR_WORKTREE_DB
150+
EOF
151+
152+
# For Core testing
153+
cat > content/influxdb3/core/.env.test << EOF
154+
INFLUX_HOST=http://localhost:8282
155+
INFLUX_TOKEN=$(jq -r .token test/.influxdb3/core/.token)
156+
INFLUX_DATABASE=test_db
157+
EOF
158+
```
159+
160+
### Run Code Block Tests
161+
162+
```bash
163+
# Test specific product
164+
yarn test:codeblocks:v2
165+
166+
# Or run pytest directly
167+
docker compose run --rm v2-pytest
168+
```
169+
170+
## Troubleshooting
171+
172+
### Enterprise Won't Start
173+
174+
**Symptom:** Container exits immediately
175+
176+
**Check:**
177+
178+
```bash
179+
# View container logs
180+
docker logs influxdb3-enterprise
181+
182+
# Common issues:
183+
# 1. Missing .env file
184+
ls -la ~/influxdata-docs/.influxdb3/enterprise/.env
185+
186+
# 2. Wrong env var name (must be INFLUXDB3_ENTERPRISE_LICENSE_EMAIL)
187+
cat ~/influxdata-docs/.influxdb3/enterprise/.env
188+
189+
# 3. Missing admin-token.json (run init script to generate)
190+
ls -la ~/influxdata-docs/.influxdb3/enterprise/admin-token.json
191+
```
192+
193+
### Core Token Not Working
194+
195+
**Symptom:** 401 Unauthorized
196+
197+
**Check:**
198+
199+
```bash
200+
# Verify token file exists and is valid JSON
201+
cat test/.influxdb3/core/.token
202+
jq . test/.influxdb3/core/.token # Should parse without errors
203+
204+
# Verify token is accessible in container (as secret)
205+
docker exec influxdb3-core cat /run/secrets/influxdb3-core-token
206+
```
207+
208+
### Port Already in Use
209+
210+
**Symptom:** "port is already allocated"
211+
212+
**Fix:**
213+
214+
```bash
215+
# Find what's using the port
216+
lsof -i :8181 # Enterprise
217+
lsof -i :8282 # Core
218+
219+
# Stop existing containers
220+
docker compose down influxdb3-enterprise influxdb3-core
221+
```
222+
223+
### Getting the Admin Token
224+
225+
The init script generates and saves admin tokens to JSON files for both Core and Enterprise:
226+
227+
```bash
228+
# Core token
229+
cat test/.influxdb3/core/.token
230+
jq -r .token test/.influxdb3/core/.token
231+
232+
# Enterprise token
233+
cat ~/influxdata-docs/.influxdb3/enterprise/admin-token.json
234+
jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json
235+
236+
# Export for use in commands
237+
export INFLUXDB3_CORE_TOKEN=$(jq -r .token test/.influxdb3/core/.token)
238+
export INFLUXDB3_ENTERPRISE_TOKEN=$(jq -r .token ~/influxdata-docs/.influxdb3/enterprise/admin-token.json)
239+
240+
# Use in API calls
241+
curl -i http://localhost:8282/ping -H "Authorization: Bearer $INFLUXDB3_CORE_TOKEN"
242+
curl -i http://localhost:8181/ping -H "Authorization: Bearer $INFLUXDB3_ENTERPRISE_TOKEN"
243+
```
244+
245+
**Token File Format** (both Core and Enterprise):
246+
```json
247+
{
248+
"token": "64-character-hexadecimal-token",
249+
"description": "Admin token for InfluxDB 3 Core/Enterprise"
250+
}
251+
```
252+
253+
## Service Comparison
254+
255+
| Aspect | Core | Enterprise |
256+
| ------------- | ---------------- | -------------------------------- |
257+
| Port | 8282 | 8181 |
258+
| Data location | Per-worktree | Shared |
259+
| Auth default | Optional | Required |
260+
| License | None | Trial/Paid |
261+
| Use case | Isolated testing | Shared testing with worktree DBs |
262+
263+
## Related Files
264+
265+
- **Init script**: `test/scripts/init-influxdb3.sh`
266+
- **Docker Compose**: `compose.yaml` (services: influxdb3-core, influxdb3-enterprise)
267+
- **Test config**: `content/<product>/.env.test`
268+
269+
## Related Skills
270+
271+
- **cypress-e2e-testing** - For running E2E tests on documentation UI
272+
- **docs-cli-workflow** - For creating/editing documentation content

‎.github/copilot-instructions.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,30 @@ For comprehensive testing procedures, see **[DOCS-TESTING.md](../DOCS-TESTING.md
131131
- **Style**: `docker compose run -T vale content/**/*.md` (30-60 seconds)
132132
- **Pre-commit**: `yarn lint` (or skip with `--no-verify`)
133133

134+
#### InfluxDB 3 Test Setup
135+
136+
For setting up InfluxDB 3 Core and Enterprise instances for testing code blocks:
137+
138+
**Quick setup commands:**
139+
```bash
140+
# Initialize Core (per-worktree, port 8282)
141+
./test/scripts/init-influxdb3.sh core
142+
143+
# Initialize Enterprise (shared, port 8181)
144+
./test/scripts/init-influxdb3.sh enterprise
145+
146+
# Initialize both
147+
./test/scripts/init-influxdb3.sh all
148+
```
149+
150+
**Key features:**
151+
- Core: Per-worktree data isolation at `test/.influxdb3/core/`
152+
- Enterprise: Shared data at `~/influxdata-docs/.influxdb3/enterprise/` (persists license)
153+
- Worktree-specific databases for test isolation on shared Enterprise instance
154+
- Auto-configured `.env.test` files for pytest-codeblocks
155+
156+
For detailed workflows and troubleshooting, see the **[influxdb3-test-setup skill](.claude/skills/influxdb3-test-setup/SKILL.md)** or invoke the `influxdb3-test-setup` skill.
157+
134158
### Validation
135159

136160
Test these after changes:
@@ -364,6 +388,17 @@ Use these agents for specialized tasks:
364388
|-------|------|----------|
365389
| **TypeScript & Hugo Dev** | [typescript-hugo-agent.md](agents/typescript-hugo-agent.md) | TypeScript migration, Hugo asset pipeline, component architecture |
366390

391+
### Skills
392+
393+
Specialized skills that can be invoked using the `skill` tool for specific workflows:
394+
395+
| Skill | File | Description |
396+
|-------|------|-------------|
397+
| **cypress-e2e-testing** | [.claude/skills/cypress-e2e-testing/SKILL.md](../.claude/skills/cypress-e2e-testing/SKILL.md) | Run, validate, and analyze Cypress E2E tests for the InfluxData documentation site |
398+
| **docs-cli-workflow** | [.claude/skills/docs-cli-workflow/SKILL.md](../.claude/skills/docs-cli-workflow/SKILL.md) | Guides when to use docs create/edit CLI tools versus direct file editing |
399+
| **hugo-template-dev** | [.claude/skills/hugo-template-dev/SKILL.md](../.claude/skills/hugo-template-dev/SKILL.md) | Hugo template development with proper build and runtime testing |
400+
| **influxdb3-test-setup** | [.claude/skills/influxdb3-test-setup/SKILL.md](../.claude/skills/influxdb3-test-setup/SKILL.md) | Set up InfluxDB 3 Core and Enterprise instances for running documentation code block tests |
401+
367402
### General Documentation
368403

369404
| Topic | File | Description |

0 commit comments

Comments
 (0)