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:**
```bash
./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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   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:**
```bash
# Check status
docker compose ps

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

**Authentication failures:**
```bash
# Recreate tokens
./setup-auth-tokens.sh both

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

**Version not found:**
```bash
# 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:
```bash
DEBUG=1 node audit-cli-documentation.js core local
```

## Integration with CI/CD

### GitHub Actions Example

```yaml
- 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

```yaml
- 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
```bash
chmod +x *.sh
```

### Missing Dependencies
```bash
# Node.js dependencies
node --version  # Should be 16 or higher

# Docker Compose
docker compose version
```

### Container Health
```bash
# 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](/influxdb3/core/reference/cli/)
- [InfluxDB 3 Enterprise CLI Reference](/influxdb3/enterprise/reference/cli/)