docs-v2/helper-scripts/influxdb3-monolith/README.md

InfluxDB 3 Monolith (Core and Enterprise) Helper Scripts

This directory contains helper scripts specifically for InfluxDB 3 Core and Enterprise (monolith deployments), as opposed to distributed/clustered deployments.

Overview

These scripts help with documentation workflows for InfluxDB 3 Core and Enterprise, including CLI change detection, authentication setup, API analysis, and release preparation.

Prerequisites

• Docker and Docker Compose: For running InfluxDB 3 containers
• Node.js 16+: For running JavaScript ESM scripts
• Active containers: InfluxDB 3 Core and/or Enterprise containers running via docker compose
• Secret files: Docker Compose secrets for auth tokens (~/.env.influxdb3-core-admin-token and ~/.env.influxdb3-enterprise-admin-token)

Scripts

🔐 Authentication & Setup

setup-auth-tokens.sh

Creates and configures authentication tokens for InfluxDB 3 containers.

Usage:

./setup-auth-tokens.sh [core|enterprise|both]

What it does:

• Checks existing tokens in secret files (~/.env.influxdb3-core-admin-token and ~/.env.influxdb3-enterprise-admin-token)
• Starts containers if not running
• Creates admin tokens using influxdb3 create token --admin
• Updates appropriate secret files with new tokens
• Tests tokens to ensure they work

Example:

# Set up both Core and Enterprise tokens
./setup-auth-tokens.sh both

# Set up only Enterprise
./setup-auth-tokens.sh enterprise

🔍 CLI Documentation Audit

audit-cli-documentation.js

JavaScript ESM script that audits InfluxDB 3 CLI commands against existing documentation to identify missing or outdated content.

Usage:

node audit-cli-documentation.js [core|enterprise|both] [version|local]

Features:

• Compares actual CLI help output with documented commands
• Identifies missing documentation for new CLI options
• Finds documented options that no longer exist in the CLI
• Supports both released versions and local containers
• Generates detailed audit reports with recommendations
• Handles authentication automatically using Docker secrets

Examples:

# Audit Core documentation against local container
node audit-cli-documentation.js core local

# Audit Enterprise documentation against specific version
node audit-cli-documentation.js enterprise v3.2.0

# Audit both products against local containers
node audit-cli-documentation.js both local

Output:

• ../output/cli-audit/documentation-audit-{product}-{version}.md - Detailed audit report
• ../output/cli-audit/parsed-cli-{product}-{version}.md - Parsed CLI structure
• ../output/cli-audit/patches/{product}/ - Generated patches for missing documentation

🛠️ CLI Documentation Updates

apply-cli-patches.js

JavaScript ESM script that applies generated patches to update CLI documentation with missing options.

Usage:

node apply-cli-patches.js [core|enterprise|both] [--dry-run]

Features:

• Applies patches generated by audit-cli-documentation.js
• Updates CLI reference documentation with missing options
• Supports dry-run mode to preview changes
• Maintains existing documentation structure and formatting
• Creates backups before applying changes

Examples:

# Preview changes without applying (dry run)
node apply-cli-patches.js core --dry-run

# Apply patches to Enterprise documentation
node apply-cli-patches.js enterprise

# Apply patches to both products
node apply-cli-patches.js both

Output:

• Updates CLI reference documentation files in place
• Creates backup files with .backup extension
• Logs all changes made to the documentation

Quick Start Guide

1. Initial Setup

# Navigate to the monolith scripts directory
cd helper-scripts/influxdb3-monolith

# Make scripts executable
chmod +x *.sh

# Set up authentication for both products
./setup-auth-tokens.sh both

# Restart containers to load new secrets
docker compose down && docker compose up -d influxdb3-core influxdb3-enterprise

2. CLI Documentation Audit

# Start your containers
docker compose up -d influxdb3-core influxdb3-enterprise

# Audit CLI documentation
node audit-cli-documentation.js core local
node audit-cli-documentation.js enterprise local

# Review the output
ls ../output/cli-audit/

3. Development Workflow

# Audit documentation for both products
node audit-cli-documentation.js both local

# Check the audit results
cat ../output/cli-audit/documentation-audit-core-local.md
cat ../output/cli-audit/documentation-audit-enterprise-local.md

# Apply patches if needed (dry run first)
node apply-cli-patches.js both --dry-run

4. Release Documentation Updates

For release documentation, use the audit and patch workflow:

# Audit against released version
node audit-cli-documentation.js enterprise v3.2.0

# Review missing documentation
cat ../output/cli-audit/documentation-audit-enterprise-v3.2.0.md

# Apply patches to update documentation
node apply-cli-patches.js enterprise

# Verify changes look correct
git diff content/influxdb3/enterprise/reference/cli/

Container Integration

The scripts work with your Docker Compose setup:

Expected container names:

• influxdb3-core (port 8282)
• influxdb3-enterprise (port 8181)

Docker Compose secrets:

• influxdb3-core-admin-token - Admin token for Core (stored in ~/.env.influxdb3-core-admin-token)
• influxdb3-enterprise-admin-token - Admin token for Enterprise (stored in ~/.env.influxdb3-enterprise-admin-token)
• INFLUXDB3_LICENSE_EMAIL - Enterprise license email (set in .env.3ent env_file)

Use Cases

📋 Release Documentation

1. Pre-release audit:

   node audit-cli-documentation.js core v3.2.0
   

2. Review audit results and update documentation

3. Apply patches for missing content

4. Test documented commands work correctly

🔬 Development Testing

1. Audit local development:

   node audit-cli-documentation.js enterprise local
   

2. Verify new features are documented

3. Test authentication setup

4. Apply patches to keep docs current

🚀 Release Preparation

1. Final audit before release:

   node audit-cli-documentation.js both local
   

2. Apply all pending patches

3. Update examples and tutorials

4. Verify all CLI commands work as documented

Output Structure

helper-scripts/
├── output/
│   └── cli-audit/
│       ├── documentation-audit-core-local.md          # CLI documentation audit report
│       ├── documentation-audit-enterprise-v3.2.0.md  # CLI documentation audit report
│       ├── parsed-cli-core-local.md                   # Parsed CLI structure
│       ├── parsed-cli-enterprise-v3.2.0.md           # Parsed CLI structure  
│       └── patches/
│           ├── core/                                  # Generated patches for Core
│           │   ├── influxdb3-cli-patch-001.md
│           │   └── influxdb3-cli-patch-002.md
│           └── enterprise/                            # Generated patches for Enterprise
│               ├── influxdb3-cli-patch-001.md
│               └── influxdb3-cli-patch-002.md
└── influxdb3-monolith/
    ├── README.md                            # This file
    ├── setup-auth-tokens.sh                 # Auth setup
    ├── audit-cli-documentation.js           # CLI documentation audit
    └── apply-cli-patches.js                 # CLI documentation patches

Error Handling

Common Issues

Container not running:

# Check status
docker compose ps

# Start specific service
docker compose up -d influxdb3-core

Authentication failures:

# Recreate tokens
./setup-auth-tokens.sh both

# Test manually
docker exec influxdb3-core influxdb3 create token --admin

Version not found:

# Check available versions
docker pull influxdb:3-core:3.2.0
docker pull influxdb:3-enterprise:3.2.0

Debug Mode

Enable debug output for troubleshooting:

DEBUG=1 node audit-cli-documentation.js core local

Integration with CI/CD

GitHub Actions Example

- name: Audit CLI Documentation
  run: |
    cd helper-scripts/influxdb3-monolith
    node audit-cli-documentation.js core ${{ env.VERSION }}
        
- name: Upload CLI Audit Results
  uses: actions/upload-artifact@v3
  with:
    name: cli-audit
    path: helper-scripts/output/cli-audit/

CircleCI Example

- run:
    name: CLI Documentation Audit
    command: |
      cd helper-scripts/influxdb3-monolith
      node audit-cli-documentation.js enterprise v3.2.0
            
- store_artifacts:
    path: helper-scripts/output/cli-audit/

Best Practices

🔒 Security

• Secret files (~/.env.influxdb3-*-admin-token) are stored in your home directory and not in version control
• Rotate auth tokens regularly by re-running setup-auth-tokens.sh
• Use minimal token permissions when possible

📚 Documentation

• Run audits early in release cycle
• Review all audit reports for missing content
• Apply patches to keep documentation current
• Test all documented commands work correctly

🔄 Workflow

• Use local version for development testing
• Audit against released versions for release prep
• Generate patches before documentation updates
• Validate changes with stakeholders

Troubleshooting

Script Permissions

chmod +x *.sh

Missing Dependencies

# Node.js dependencies
node --version  # Should be 16 or higher

# Docker Compose
docker compose version

Container Health

# Check container logs
docker logs influxdb3-core
docker logs influxdb3-enterprise

# Test basic connectivity
docker exec influxdb3-core influxdb3 --version

Contributing

When adding new scripts to this directory:

1. Follow naming conventions: Use lowercase with hyphens
2. Add usage documentation: Include help text in scripts
3. Handle errors gracefully: Use proper exit codes
4. Test with both products: Ensure Core and Enterprise compatibility
5. Update this README: Document new functionality

Related Documentation

• InfluxDB 3 Core CLI Reference
• InfluxDB 3 Enterprise CLI Reference