# Investibook Configuration Guide

This guide explains how to configure Investibook using YAML files and environment variables.

## Configuration Priority

Settings are loaded with the following priority (highest to lowest):

1. **Environment variables** (prefixed with `INVESTIBOOK_`)
2. **YAML configuration file**
3. **Default values**

## Configuration File Locations

The system checks for configuration files in this order:

1. Path specified in `INVESTIBOOK_CONFIG_FILE` environment variable
2. `../config.yaml` (parent directory - useful when running from `backend/`)
3. `../investibook.yaml` (parent directory)
4. `./investibook.yaml` (current directory)
5. `./config/investibook.yaml`
6. `~/.investibook/config.yaml` (user home directory)

## Quick Start

### Option 1: Using YAML File

1. Copy the example file:
   ```bash
   cp investibook.yaml.example investibook.yaml
   ```

2. Edit `investibook.yaml` with your settings:
   ```yaml
   aiops_api_url: "http://localhost:9090"
   clinic_api_key: "your-api-key-here"
   ```

3. Start the backend:
   ```bash
   cd backend
   uv run uvicorn main:app --host 0.0.0.0 --port 8000
   ```

### Option 2: Using Environment Variables

```bash
export INVESTIBOOK_AIOPS_API_URL="http://localhost:9090"
export INVESTIBOOK_CLINIC_API_KEY="your-api-key-here"
cd backend
uv run uvicorn main:app --host 0.0.0.0 --port 8000
```

### Option 3: Using Custom Config File

```bash
export INVESTIBOOK_CONFIG_FILE="/path/to/your/config.yaml"
cd backend
uv run uvicorn main:app --host 0.0.0.0 --port 8000
```

## Configuration Options

### Guardian API Settings

| Setting | Env Variable | Default | Description |
|---------|--------------|---------|-------------|
| `aiops_api_url` | `INVESTIBOOK_AIOPS_API_URL` | `""` | Guardian API base URL for fetching analysis data |

**Example:**
```yaml
aiops_api_url: "http://localhost:9090"
```

### S3 Settings

| Setting | Env Variable | Default | Description |
|---------|--------------|---------|-------------|
| `s3_bucket` | `INVESTIBOOK_S3_BUCKET` | `tidbcloud-aiops-assets-dev` | S3 bucket containing analysis files |
| `aws_region` | `INVESTIBOOK_AWS_REGION` | `us-west-2` | AWS region where the S3 bucket is located |

**Example:**
```yaml
s3_bucket: "my-analysis-bucket"
aws_region: "us-east-1"
```

**AWS Credentials:**

AWS credentials are not configured in Investibook. They are read by boto3 using standard AWS methods:

- Environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
- AWS credentials file: `~/.aws/credentials`
- AWS profile: `AWS_PROFILE` environment variable
- IAM role (when running on EC2/ECS)

### Clinic API Settings

| Setting | Env Variable | Default | Description |
|---------|--------------|---------|-------------|
| `clinic_endpoint` | `INVESTIBOOK_CLINIC_ENDPOINT` | `https://clinic.pingcap.com` | Clinic HTTP API endpoint |
| `clinic_api_key` | `INVESTIBOOK_CLINIC_API_KEY` | `""` | API key for Clinic authentication |
| `clinic_cookie` | `INVESTIBOOK_CLINIC_COOKIE` | `""` | Clinic cookie for local debugging |
| `clinic_csrf_token` | `INVESTIBOOK_CLINIC_CSRF_TOKEN` | `""` | Clinic CSRF token for local debugging |

**Production Example (API Key):**
```yaml
clinic_endpoint: "https://clinic.pingcap.com"
clinic_api_key: "sk-clinic-xxxxxxxxxxxxx"
```

**Local Debugging Example (Cookie + CSRF Token):**

For local debugging, you can use browser cookies instead of an API key:

1. Log into Clinic in your browser (https://clinic.pingcap.com)
2. Open Browser DevTools → Network tab
3. Find any API request to Clinic
4. Copy the `Cookie` header value and `X-CSRF-Token` header value

```yaml
clinic_endpoint: "https://clinic.pingcap.com"
clinic_cookie: "session=eyJ...; _csrf=abc..."
clinic_csrf_token: "xyz123..."
```

**Note:** Cookie and CSRF token are alternatives to the API key for local development. The API key takes precedence if both are provided.

### OpenAI Settings for Comment Summary

These settings control the direct OpenAI call used to summarize Jira comments into `comments_summary_ai.md`.

| Setting | Env Variable | Default | Description |
|---------|--------------|---------|-------------|
| `openai_api_key` | `INVESTIBOOK_OPENAI_API_KEY` | `""` | OpenAI API key for comment summarization (gpt-4o) |
| `openai_model` | `INVESTIBOOK_OPENAI_MODEL` | `gpt-4o` | OpenAI model name used for comment summarization |

**Example:**

```yaml
openai_api_key: "sk-your-openai-key"
openai_model: "gpt-4o"
```

### Jira API Settings

| Setting | Env Variable | Default | Description |
|---------|--------------|---------|-------------|
| `jira_base_url` | `INVESTIBOOK_JIRA_BASE_URL` | `https://pingcap.atlassian.net` | Jira base URL |
| `jira_username` | `INVESTIBOOK_JIRA_USERNAME` | `""` | Jira username (email address) |
| `jira_api_token` | `INVESTIBOOK_JIRA_API_TOKEN` | `""` | Jira API token for authentication |

**How to Get Jira API Token:**

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a label (e.g., "Investibook")
4. Copy the token and save it securely

**Example:**
```yaml
jira_base_url: "https://pingcap.atlassian.net"
jira_username: "your-email@pingcap.com"
jira_api_token: "ATATT3xFfGF0..."
```

### Auth0 SSO Settings (Google Login)

Auth0 is optional — the email-only login still works when these variables are not set.

**Backend environment variable:**

| Env Variable | Default | Description |
|--------------|---------|-------------|
| `AUTH0_DOMAIN` | `""` | Your Auth0 tenant domain, e.g. `your-tenant.auth0.com` |

**Frontend environment variables (set in `.env.local` or deployment environment):**

| Env Variable | Default | Description |
|--------------|---------|-------------|
| `NEXT_PUBLIC_AUTH0_DOMAIN` | `""` | Same as `AUTH0_DOMAIN` above |
| `NEXT_PUBLIC_AUTH0_CLIENT_ID` | `""` | Auth0 Application Client ID (SPA type) |

**Setup steps:**

1. Create an Auth0 account at https://auth0.com and create a new **Single Page Application**.
2. Under **Connections**, enable "google-oauth2".
3. Under **Application URIs**, add:
   - Allowed Callback URLs: `http://localhost:3000/auth/callback` (and your production URL)
   - Allowed Logout URLs: `http://localhost:3000` (and your production URL)
   - Allowed Web Origins: `http://localhost:3000` (and your production URL)
4. Set the environment variables:

**Backend (`backend/.env` or shell):**
```bash
export AUTH0_DOMAIN="your-tenant.auth0.com"
```

**Frontend (`.env.local` in `platform/investibook/`):**
```bash
NEXT_PUBLIC_AUTH0_DOMAIN=your-tenant.auth0.com
NEXT_PUBLIC_AUTH0_CLIENT_ID=your-auth0-client-id
```

## Data Pipeline Flow

Investibook fetches Jira issue source data using the following pipeline:

1. **Fetch Issue from Jira** (Required)
   - Gets issue details by issue_id (e.g., "O11Y-1956041")
   - Extracts: `cluster_id`, `tenant_id`, `org_id` from custom fields

2. **Fetch Cluster Metadata from Clinic** (Required)
   - Uses `cluster_id` from Step 1
   - Gets cluster details: version, org_id, etc.

3. **Fetch Analysis Insights from Guardian + S3** (Optional)
   - If `tenant_id` and `cluster_id` are available
   - Downloads insight.json and diagnostic_package.json from S3
   - Skipped if Guardian API not configured or no analysis found

4. **Write Metadata and Copy Templates**
   - Writes cluster_meta.json
   - Copies .opencode/ and toolset/ directories from template

## Examples

### Development Environment

```yaml
# investibook.yaml
# Guardian API (optional - for analysis insights)
aiops_api_url: "http://localhost:9090"

# S3 (for analysis insights)
s3_bucket: "tidbcloud-aiops-assets-dev"
aws_region: "us-west-2"

# Clinic (required - for cluster metadata)
clinic_endpoint: "https://clinic.pingcap.com"
clinic_cookie: "session=eyJ..."  # Get from browser DevTools
clinic_csrf_token: "abc123..."

# Jira (required - for alert details)
jira_base_url: "https://pingcap.atlassian.net"
jira_username: "your-email@pingcap.com"
jira_api_token: "ATATT3xFfGF0..."

# LLM for comment summary (direct OpenAI call, no ACP agent)
openai_api_key: "sk-your-openai-key"
openai_model: "gpt-4o"
```

### Production Environment

For production, use environment variables instead of committing secrets to YAML:

```bash
# Guardian API (optional)
export INVESTIBOOK_AIOPS_API_URL="https://guardian.prod.example.com"

# S3
export INVESTIBOOK_S3_BUCKET="tidbcloud-aiops-assets-prod"
export INVESTIBOOK_AWS_REGION="us-west-2"

# Clinic (required)
export INVESTIBOOK_CLINIC_ENDPOINT="https://clinic.pingcap.com"
export INVESTIBOOK_CLINIC_API_KEY="${SECRET_CLINIC_API_KEY}"

# Jira (required)
export INVESTIBOOK_JIRA_BASE_URL="https://pingcap.atlassian.net"
export INVESTIBOOK_JIRA_USERNAME="${JIRA_USERNAME}"
export INVESTIBOOK_JIRA_API_TOKEN="${SECRET_JIRA_API_TOKEN}"

# LLM for comment summary (optional, but required if you want AI comment summaries)
export INVESTIBOOK_OPENAI_API_KEY="${OPENAI_API_KEY}"
export INVESTIBOOK_OPENAI_MODEL="gpt-4o"

```

### Mixed Configuration

You can use YAML for non-sensitive defaults and environment variables for secrets:

**investibook.yaml:**
```yaml
aiops_api_url: "http://localhost:9090"
s3_bucket: "tidbcloud-aiops-assets-dev"
aws_region: "us-west-2"
clinic_endpoint: "https://clinic.pingcap.com"
# Don't put API key in version control
```

**Environment:**
```bash
export INVESTIBOOK_CLINIC_API_KEY="your-secret-key"
```

### Local Debugging with Browser Cookies

For local development, you can use browser cookies instead of an API key:

**Step 1: Get Cookie and CSRF Token from Browser**

1. Open https://clinic.pingcap.com and log in
2. Open Browser DevTools (F12)
3. Go to Network tab
4. Refresh the page or make any request
5. Click on any request to Clinic API
6. In Request Headers, find and copy:
   - `Cookie` header value
   - `X-CSRF-Token` header value (if present)

**Step 2: Configure in YAML**

```yaml
# investibook.yaml
aiops_api_url: "http://localhost:9090"
s3_bucket: "tidbcloud-aiops-assets-dev"
aws_region: "us-west-2"
clinic_endpoint: "https://clinic.pingcap.com"
# Use browser cookie for local debugging
clinic_cookie: "session=eyJhbGciOi...; _csrf=abc123..."
clinic_csrf_token: "def456..."
```

**Note:** Browser cookies expire periodically, so you'll need to refresh them when they expire.

## Troubleshooting

### Configuration Not Loading

Check if the configuration file is being found:

```python
# In backend directory
uv run python -c "from services.config import settings; print(settings.model_dump())"
```

### Environment Variables Not Working

Make sure you're using the correct prefix:

```bash
# ✅ Correct
export INVESTIBOOK_CLINIC_API_KEY="key"

# ❌ Wrong
export CLINIC_API_KEY="key"
```

### AWS Credentials Issues

Test AWS credentials separately:

```bash
aws s3 ls s3://tidbcloud-aiops-assets-dev/ --region us-west-2
```

## Security Best Practices

1. **Never commit secrets** to version control
   - `investibook.yaml` is already in `.gitignore`
   - Use `investibook.yaml.example` for templates

2. **Use environment variables** for production secrets
   - Integrate with your secret management system (AWS Secrets Manager, Vault, etc.)

3. **Restrict file permissions** for config files with secrets:
   ```bash
   chmod 600 investibook.yaml
   ```

4. **Use different configs** for different environments
   - Don't share production credentials with development