Add Claude Code configuration and Docker Compose for InfluxDB 3#29
Add Claude Code configuration and Docker Compose for InfluxDB 3#29jstirnaman wants to merge 23 commits intorelease/influxdb3-core-3.8.1from
Conversation
Phase 1 of InfluxDB 3 migration: - Replace @influxdata/influxdb-client v1.24.0 with @influxdata/influxdb3-client v2.0.0 - Remove @influxdata/influxdb-client-apis (AuthorizationsAPI not available in v3) - Update environment variables: - INFLUX_URL -> INFLUX_HOST (port 8181) - INFLUX_BUCKET -> INFLUX_DATABASE - INFLUX_BUCKET_AUTH -> INFLUX_DATABASE_AUTH - Remove INFLUX_ORG (not used in InfluxDB 3) - Convert all Flux queries to SQL (Flux not supported in InfluxDB 3) - Add shared client utility (lib/influxdb.js) with: - createClient() for InfluxDB 3 client instantiation - query() helper for SQL queries - write() helper for line protocol writes - generateDeviceToken() for app-level device auth - Redesign device authorization for InfluxDB 3 Core: - Use application-level tokens instead of InfluxDB-native tokens - Store device credentials in deviceauth table - Enterprise upgrade path: use resource tokens for per-device permissions Breaking changes: - Measurement queries must use SQL instead of Flux - Device tokens are now application-level (not InfluxDB-native) https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY
- Import Point class from @influxdata/influxdb3-client and re-export - Use Point.measurement().setTag().setStringField() for type-safe writes - Fix crypto: use Node.js randomBytes instead of Web Crypto API - Remove manual line protocol escaping (Point handles it internally) https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY
- Keep @influxdata/influxdb3-client ^2.0.0 (InfluxDB 3 migration) - Update next to ^16.1.5 (from main) - Remove old @influxdata/influxdb-client packages https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY
- Remove redundant note about SQL queries in device endpoint comments - Simplify hint text for missing query parameter - Update device token storage comment to clarify Enterprise vs Core approaches - Clarify SQL/InfluxQL query requirement in measurements documentation
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Security fixes: - Add deviceId validation (alphanumeric, hyphens, underscores only) - Fix JSON parsing to handle both string and pre-parsed body - Remove token exposure from public GET endpoints - Add SQL query validation (SELECT only, block DROP/DELETE/UPDATE) - Add query length limit (2000 chars) to prevent abuse - Block multi-statement SQL injection attempts Code quality: - Add getDevices() options parameter for internal token access - Add validateQuery() helper with blocked patterns - Update API documentation to reflect SELECT-only queries Tests: - Add Jest test suite with node-mocks-http - Test device creation with valid/invalid deviceIds - Test device listing without token exposure - Test SQL injection prevention - Test query validation (DROP, DELETE, UPDATE blocked) https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY
- Add sample application disclaimer in GitHub callout format - Update all references from InfluxDB v2 to InfluxDB 3 Core - Update setup instructions with InfluxDB 3 CLI commands - Update environment variable documentation (INFLUX_HOST, INFLUX_DATABASE) - Update troubleshooting section for database errors - Add links to InfluxDB 3 documentation and JavaScript client https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY
- Add .claude/settings.json with project permissions - Add .claude/skills/run-tests/SKILL.md for test workflow - Add CLAUDE.md and AGENTS.md instruction files - Add .github/INSTRUCTIONS.md navigation guide - Add compose.yaml for InfluxDB 3 Core local development - Update .gitignore to exclude test/.influxdb3/ data
…to claude/influxdb3-core-migration-pMqwy
There was a problem hiding this comment.
Pull request overview
Adds developer tooling and AI-assistant guidance for local InfluxDB 3 Core development, plus configuration files intended to support Claude Code/MCP and other AI agents working in this repo.
Changes:
- Add
compose.yamlto run InfluxDB 3 Core locally with token-based auth and persisted data directories. - Add AI assistant documentation (
CLAUDE.md,AGENTS.md) and a navigation index (.github/INSTRUCTIONS.md). - Add Claude Code configuration (
.claude/settings.json) and a/run-testsskill guide, plus ignore local InfluxDB data in.gitignore.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| compose.yaml | Adds Docker Compose service + setup instructions for local InfluxDB 3 Core |
| CLAUDE.md | Claude-specific quick reference and project notes |
| AGENTS.md | General AI assistant workflow guidance and code patterns |
| .gitignore | Ignores local InfluxDB 3 data directory under test/.influxdb3/ |
| .github/INSTRUCTIONS.md | Adds navigation doc pointing assistants to the right instruction files |
| .claude/skills/run-tests/SKILL.md | Adds a Claude “run-tests” skill with setup/troubleshooting steps |
| .claude/settings.json | Adds Claude Code permission policy for repo operations |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # 2. Get the generated token | ||
| cat test/.influxdb3/core/.token | ||
|
|
||
| # 3. Configure .env.local with the token | ||
| echo "INFLUX_TOKEN=$(cat test/.influxdb3/core/.token)" >> .env.local |
There was a problem hiding this comment.
This workflow suggests reading back .env.local values (for example with cat/grep), but .claude/settings.json currently denies Read(./.env.*), which includes .env.local. Either relax the permissions policy for .env.local/.env.development or adjust the workflow to avoid reading .env.* files.
| # Ensure InfluxDB 3 is running | ||
| docker compose up -d influxdb3-core | ||
|
|
||
| # Run test suite | ||
| yarn test |
There was a problem hiding this comment.
This section instructs starting InfluxDB 3 before yarn test, but __tests__/api.test.js mocks ../lib/influxdb and doesn’t require a live database. Update guidance to reflect that unit tests run without InfluxDB, and optionally document a separate integration test workflow if needed.
| | `pages/api/devices/create.js` | Device registration endpoint | | ||
| | `pages/api/devices/_devices.js` | Shared device query logic | | ||
| | `pages/api/devices/[[...deviceParams]].js` | Device CRUD operations | | ||
| | `pages/api/measurements/index.js` | Telemetry query endpoint | |
There was a problem hiding this comment.
pages/api/measurements/index.js is listed as a “Telemetry query endpoint”, but it doesn’t export a default Next.js API handler (it exports getMeasurements()), so it isn’t directly an endpoint. Consider rewording this as a shared telemetry query helper, or add an actual /api/measurements route if that’s intended.
| | `pages/api/measurements/index.js` | Telemetry query endpoint | | |
| | `pages/api/measurements/index.js` | Shared telemetry query helper | |
| ## Purpose | ||
|
|
||
| This skill guides running the IoT API test suite against a local InfluxDB 3 Core instance. It covers service setup, database creation, and test execution. | ||
|
|
There was a problem hiding this comment.
The skill describes running the test suite “against a local InfluxDB 3 Core instance”, but the only test file (__tests__/api.test.js) mocks the InfluxDB client and can run without any database. Please either (a) adjust this skill to describe the mocked/unit test workflow, or (b) add a separate integration test target and clarify which tests require InfluxDB.
| ```bash | ||
| # Verify token matches | ||
| echo "Token in file: $(cat test/.influxdb3/core/.token)" | ||
| echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)" |
There was a problem hiding this comment.
Troubleshooting suggests grep INFLUX_TOKEN .env.local, but .claude/settings.json denies Read(./.env.*)—an agent using Claude Code won’t be permitted to run read operations against .env.local. Either relax the deny rule (for non-secret .env.development at least) or adjust troubleshooting steps to avoid reading .env.* files.
| echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)" | |
| echo "INFLUX_TOKEN env var: ${INFLUX_TOKEN:-'(not set)'}" |
| ], | ||
| "deny": [ | ||
| "Read(./.env)", | ||
| "Read(./.env.*)", |
There was a problem hiding this comment.
The deny rule Read(./.env.*) blocks reading .env.development, even though the repo treats it as committed non-secret defaults and the new docs reference copying values from it. Consider narrowing the deny list to only secret-bearing files (for example .env.local and .env*.local) or explicitly allowing reads of .env.development so the assistant can follow the documented workflows.
| "Read(./.env.*)", | |
| "Read(./.env*.local)", |
| │ ├── devices/ # Device CRUD endpoints | ||
| │ │ ├── create.js # POST /api/devices/create | ||
| │ │ ├── _devices.js # Shared device queries | ||
| │ │ └── [[...deviceParams]].js # GET/DELETE /api/devices | ||
| │ └── measurements/ # Telemetry endpoints |
There was a problem hiding this comment.
The structure comment says pages/api/devices/[[...deviceParams]].js handles GET/DELETE /api/devices, but the handler only supports GET (and POST for /:deviceId/measurements)—there’s no DELETE implementation. Update the description so it reflects the actual supported methods/routes.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 7 changed files in this pull request and generated 8 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| │ - iot_center │ | ||
| │ - iot_center_devices│ |
There was a problem hiding this comment.
The architecture section states the two databases are iot_center and iot_center_auth, but the application defaults use INFLUX_DATABASE_AUTH=iot_center_devices (and README instructs creating iot_center_devices). Please update this diagram/text to match the actual default database names.
| │ - iot_center │ | |
| │ - iot_center_devices│ | |
| │ - iot_center_devices│ | |
| │ │ |
|
|
||
| - Use ES modules (`import`/`export`) | ||
| - Validate all user input before database operations | ||
| - Never expose tokens in API responses |
There was a problem hiding this comment.
The style guideline “Never expose tokens in API responses” is ambiguous/contradictory with the current API behavior: POST /api/devices/create returns a device token by design. Consider clarifying that the InfluxDB admin token must never be returned, and that device tokens should only be returned at registration (and never in GET/list responses).
| - Never expose tokens in API responses | |
| - Never return the InfluxDB admin token in any API response or logs | |
| - Only return device tokens at registration (for example, `POST /api/devices/create`); never include them in GET/list or other read responses |
| This app uses application-managed tokens stored in the database. Tokens are: | ||
| - Generated via `generateDeviceToken()` in `lib/influxdb.js` | ||
| - Stored in the `deviceauth` measurement | ||
| - Never exposed via public API responses |
There was a problem hiding this comment.
This section says device tokens are “Never exposed via public API responses”, but POST /api/devices/create returns the device token to the caller (necessary for device auth). Recommend rewording to: tokens aren’t exposed by read/list endpoints and are only returned at registration.
| - Never exposed via public API responses | |
| - Not exposed via read/list endpoints and only returned once at registration (`POST /api/devices/create`) |
| "deny": [ | ||
| "Read(./.env)", | ||
| "Read(./.env.*)", | ||
| "Read(./secrets/**)" | ||
| ], |
There was a problem hiding this comment.
The deny rule Read(./.env.*) also blocks reading .env.development, which this repo uses for non-secret defaults and which is referenced by the documentation. Consider narrowing the deny list to just secret-bearing files (for example .env, .env.local, .env.*.local) so assistants can still read committed defaults while avoiding secrets.
| ## Testing | ||
|
|
||
| Run the test suite against a local InfluxDB 3 Core instance: | ||
|
|
||
| ```bash | ||
| # Start InfluxDB 3 Core | ||
| docker compose up -d influxdb3-core | ||
|
|
||
| # Run tests | ||
| yarn test | ||
| ``` |
There was a problem hiding this comment.
This testing section implies yarn test requires a running InfluxDB 3 Core container. The current test suite mocks ../lib/influxdb and does not use a live database (__tests__/api.test.js), so these steps are misleading. Suggest either updating the docs to say tests are mocked, or converting tests to true integration tests.
| ### Running Tests | ||
|
|
||
| ```bash | ||
| # Ensure InfluxDB 3 is running | ||
| docker compose up -d influxdb3-core | ||
|
|
||
| # Run test suite | ||
| yarn test | ||
| ``` |
There was a problem hiding this comment.
This “Running Tests” section instructs starting InfluxDB 3 before yarn test, but the Jest suite currently mocks the InfluxDB client and runs without a database (__tests__/api.test.js). Consider clarifying that tests are mocked (or convert them to integration tests if that’s the intent).
| name: run-tests | ||
| description: Run API tests against InfluxDB 3 Core. Handles service initialization, database setup, and test execution. | ||
| author: InfluxData | ||
| version: "1.0" |
There was a problem hiding this comment.
This skill claims tests run “against InfluxDB 3 Core” and includes DB initialization steps, but the current Jest suite mocks ../lib/influxdb and runs without a real database (__tests__/api.test.js). Either update this skill to describe the mocked test workflow, or convert tests to true integration tests and remove the module mock.
| # Create auth database | ||
| curl -X POST "http://localhost:8181/api/v3/configure/database" \ | ||
| -H "Authorization: Bearer $TOKEN" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"db": "iot_center_auth"}' | ||
|
|
||
| # Verify databases exist | ||
| curl "http://localhost:8181/api/v3/configure/database?format=json" \ | ||
| -H "Authorization: Bearer $TOKEN" | ||
| ``` | ||
|
|
||
| ### 3. Configure Environment | ||
|
|
||
| Create `.env.local` if it doesn't exist: | ||
|
|
||
| ```bash | ||
| cat > .env.local << EOF | ||
| INFLUX_HOST=http://localhost:8181 | ||
| INFLUX_TOKEN=$(cat test/.influxdb3/core/.token) | ||
| INFLUX_DATABASE=iot_center | ||
| INFLUX_DATABASE_AUTH=iot_center_auth | ||
| EOF |
There was a problem hiding this comment.
The auth database name is inconsistent with the rest of the repo defaults (INFLUX_DATABASE_AUTH=iot_center_devices in .env.development/README). Here it’s iot_center_auth in both the database creation step and the suggested .env.local, which will misconfigure the app unless users also change defaults. Please align on a single name.
The handler had `const deviceId` declared twice (lines 15 and 17), causing a SyntaxError that prevented the endpoint from working. Also adds missing Jest/Babel configuration files required to run tests.
- Move detailed documentation to docs/ directory: - architecture.md: system design, project structure, schema - development.md: setup, testing, debugging - api-reference.md: endpoint documentation - code-patterns.md: InfluxDB client usage - contributing.md: style guidelines, adding endpoints - Simplify CLAUDE.md and AGENTS.md to concise TOCs - Update .github/INSTRUCTIONS.md with links to docs/
… and Enterprise Covers architecture, LVC/DVC caching, Processing Engine WAL flush plugin, optional Enterprise support via separate code paths, data flow, file change summary, and testing strategy.
Eight bite-sized tasks with exact file paths, code, test steps, and commit points. Covers config, DVC, LVC, plugin, Enterprise module, Docker Compose, and documentation updates.
Summary
Add developer tooling for local development and AI-assisted workflows.
Changes
Claude Code Configuration
AI Assistant Documentation
Local Development
test/.influxdb3/local data directoryTest plan
docker compose up -d influxdb3-corestarts successfully/run-testsskill provides correct workflow guidance