proxmox/docs/04-configuration/REQUIRED_SECRETS_INVENTORY.md

# Required Secrets and Environment Variables Inventory

**Date:** 2025-01-20  
**Status:** 📋 Comprehensive Inventory  
**Purpose:** Track all required secrets and environment variables across the infrastructure

---

## Overview

This document provides a comprehensive inventory of all required secrets and environment variables needed for the Proxmox infrastructure, services, and integrations.

---

## Critical Secrets (High Priority)

### 1. Cloudflare API Credentials

#### Cloudflare API Token (Recommended)
- **Variable:** `CLOUDFLARE_API_TOKEN`
- **Purpose:** Programmatic access to Cloudflare API
- **Used For:**
  - DNS record management
  - Tunnel configuration
  - ACME DNS-01 challenges
  - Automated Cloudflare operations
- **Creation:** https://dash.cloudflare.com/profile/api-tokens
- **Permissions Required:**
  - Zone → DNS → Edit
  - Account → Cloudflare Tunnel → Edit (for tunnel management)
- **Security:** Use API tokens (not Global API Key)
- **Status:** ⚠️ Required

#### Cloudflare Global API Key (Legacy - Not Recommended)
- **Variable:** `CLOUDFLARE_API_KEY`
- **Variable:** `CLOUDFLARE_EMAIL`
- **Purpose:** Legacy API authentication
- **Status:** ⚠️ Deprecated - Use API Token instead

#### Cloudflare Zone ID
- **Variable:** `CLOUDFLARE_ZONE_ID`
- **Purpose:** Identify specific Cloudflare zone
- **Used For:** API operations on specific zones
- **Status:** ⚠️ Required (can be auto-detected with API token)

#### Cloudflare Account ID
- **Variable:** `CLOUDFLARE_ACCOUNT_ID`
- **Purpose:** Identify Cloudflare account
- **Used For:** Tunnel operations, account-level API calls
- **Status:** ⚠️ Required (can be auto-detected with API token)

#### Cloudflare Tunnel Token
- **Variable:** `TUNNEL_TOKEN` or `CLOUDFLARE_TUNNEL_TOKEN`
- **Purpose:** Authenticate cloudflared service
- **Used For:** Cloudflare Tunnel connections
- **Creation:** Cloudflare Zero Trust Dashboard
- **Status:** ⚠️ Required for tunnel services

---

### 2. Proxmox Access Credentials

#### Proxmox Host Passwords
- **Variable:** `PROXMOX_PASS_ML110` or `PROXMOX_HOST_ML110_PASSWORD`
- **Variable:** `PROXMOX_PASS_R630_01` or `PROXMOX_HOST_R630_01_PASSWORD`
- **Variable:** `PROXMOX_PASS_R630_02` or `PROXMOX_HOST_R630_02_PASSWORD`
- **Purpose:** SSH/API access to Proxmox nodes
- **Used For:** Scripted operations, automation
- **Default:** Various (check physical hardware inventory)
- **Status:** ⚠️ Required for automation scripts

#### Proxmox API Tokens
- **Variable:** `PROXMOX_API_TOKEN`
- **Variable:** `PROXMOX_API_SECRET`
- **Purpose:** Proxmox API authentication
- **Used For:** API-based operations
- **Status:** ⚠️ Optional (alternative to passwords)

---

### 3. Service-Specific Secrets

#### Database Credentials
- **Variable:** `POSTGRES_PASSWORD`
- **Variable:** `POSTGRES_USER`
- **Variable:** `DATABASE_URL`
- **Purpose:** Database access
- **Used For:** Database connections
- **Status:** ⚠️ Required for database services

#### Redis Credentials
- **Variable:** `REDIS_PASSWORD`
- **Variable:** `REDIS_URL`
- **Purpose:** Redis cache access
- **Status:** ⚠️ Required if Redis authentication enabled

#### JWT Secrets
- **Variable:** `JWT_SECRET`
- **Variable:** `JWT_PRIVATE_KEY`
- **Purpose:** JWT token signing
- **Used For:** API authentication
- **Status:** ⚠️ Required for services using JWT

---

## Domain and DNS Configuration

### Domain Variables
- **Variable:** `DOMAIN`
- **Variable:** `PRIMARY_DOMAIN`
- **Purpose:** Primary domain name
- **Examples:** `d-bis.org`, `defi-oracle.io`
- **Status:** ⚠️ Required for DNS/SSL operations

### DNS Configuration
- **Variable:** `DNS_PROVIDER`
- **Variable:** `DNS_API_ENDPOINT`
- **Purpose:** DNS provider configuration
- **Status:** ℹ️ Optional (defaults to Cloudflare)

---

## Blockchain/ChainID 138 Specific

### RPC Configuration
- **Variable:** `CHAIN_ID`
- **Variable:** `RPC_ENDPOINT`
- **Variable:** `RPC_NODE_URL`
- **Purpose:** Blockchain RPC configuration
- **Status:** ⚠️ Required for blockchain services

### Private Keys (Critical Security)
- **Variable:** `VALIDATOR_PRIVATE_KEY`
- **Variable:** `NODE_PRIVATE_KEY`
- **Purpose:** Blockchain node/validator keys
- **Security:** 🔒 EXTREMELY SENSITIVE - Use secure storage
- **Status:** ⚠️ Required for validators/nodes

---

## Third-Party Service Integrations

### Azure (if used)
- **Variable:** `AZURE_SUBSCRIPTION_ID`
- **Variable:** `AZURE_TENANT_ID`
- **Variable:** `AZURE_CLIENT_ID`
- **Variable:** `AZURE_CLIENT_SECRET`
- **Status:** ℹ️ Required if using Azure services

### Other Cloud Providers
- **Variable:** `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`
- **Variable:** `GCP_PROJECT_ID` / `GCP_SERVICE_ACCOUNT_KEY`
- **Status:** ℹ️ Required if using respective cloud services

---

## Application-Specific Variables

### DBIS Services
- **Variable:** `DBIS_DATABASE_URL`
- **Variable:** `DBIS_API_KEY`
- **Variable:** `DBIS_SECRET_KEY`
- **Status:** ⚠️ Required for DBIS services

### Blockscout
- **Variable:** `BLOCKSCOUT_DATABASE_URL`
- **Variable:** `BLOCKSCOUT_SECRET_KEY_BASE`
- **Variable:** `BLOCKSCOUT_ETHERSCAN_API_KEY`
- **Status:** ⚠️ Required for Blockscout explorer

### Other Services
- Service-specific variables as documented per service
- Check individual service documentation

---

## Network Configuration

### IP Addresses
- **Variable:** `PROXMOX_HOST_ML110` (192.168.11.10)
- **Variable:** `PROXMOX_HOST_R630_01` (192.168.11.11)
- **Variable:** `PROXMOX_HOST_R630_02` (192.168.11.12)
- **Purpose:** Proxmox node IP addresses
- **Status:** ⚠️ Required for scripts

### Network Credentials
- **Variable:** `OMADA_USERNAME`
- **Variable:** `OMADA_PASSWORD`
- **Purpose:** Omada controller access
- **Status:** ⚠️ Required for network automation

---

## Security and Monitoring

### Monitoring Tools
- **Variable:** `GRAFANA_ADMIN_PASSWORD`
- **Variable:** `PROMETHEUS_BASIC_AUTH_PASSWORD`
- **Status:** ⚠️ Required if monitoring enabled

### Alerting
- **Variable:** `ALERT_EMAIL`
- **Variable:** `SLACK_WEBHOOK_URL`
- **Variable:** `DISCORD_WEBHOOK_URL`
- **Status:** ℹ️ Optional

---

## Environment-Specific Configuration

### Development
- **Variable:** `NODE_ENV=development`
- **Variable:** `DEBUG=true`
- **Status:** ℹ️ Development-specific

### Production
- **Variable:** `NODE_ENV=production`
- **Variable:** `DEBUG=false`
- **Status:** ⚠️ Production configuration

### Staging
- **Variable:** `NODE_ENV=staging`
- **Status:** ℹ️ Staging environment

---

## Required Secrets Checklist

### Critical (Must Have)
- [ ] `CLOUDFLARE_API_TOKEN` - Cloudflare API access
- [ ] `CLOUDFLARE_ZONE_ID` - Cloudflare zone identification
- [ ] `TUNNEL_TOKEN` - Cloudflare Tunnel authentication (if using tunnels)
- [ ] Proxmox node passwords - SSH/API access
- [ ] Database passwords - Service database access
- [ ] Domain configuration - Primary domain name

### High Priority
- [ ] `JWT_SECRET` - API authentication
- [ ] Service-specific API keys
- [ ] Private keys (if applicable)
- [ ] Monitoring credentials

### Medium Priority
- [ ] Third-party service credentials
- [ ] Alerting webhooks
- [ ] Backup storage credentials

### Low Priority / Optional
- [ ] Development-only variables
- [ ] Debug flags
- [ ] Optional integrations

---

## Secret Storage Best Practices

### 1. Secure Storage
- ✅ Use secrets management systems (HashiCorp Vault, AWS Secrets Manager, etc.)
- ✅ Encrypt sensitive values at rest
- ✅ Use environment-specific secret stores
- ❌ Don't commit secrets to git
- ❌ Don't store in plain text files

### 2. Access Control
- ✅ Limit access to secrets (principle of least privilege)
- ✅ Rotate secrets regularly
- ✅ Use separate secrets for different environments
- ✅ Audit secret access

### 3. Documentation
- ✅ Document which services need which secrets
- ✅ Use .env.example files (without real values)
- ✅ Maintain this inventory
- ✅ Document secret rotation procedures

### 4. Development Practices
- ✅ Use different secrets for dev/staging/prod
- ✅ Never use production secrets in development
- ✅ Use placeholder values in templates
- ✅ Validate required secrets on startup

---

## Secret Verification

### Script Available
**Script:** `scripts/check-env-secrets.sh`

**Usage:**
```bash
./scripts/check-env-secrets.sh
```

**What it does:**
- Scans all .env files
- Identifies empty variables
- Detects placeholder values
- Lists all variables found
- Provides recommendations

---

## Environment File Locations

### Expected Locations
- `.env` - Root directory (main configuration)
- `config/.env` - Configuration directory
- `config/production/.env.production` - Production-specific
- Service-specific: `*/config/.env`, `*/.env.local`

### Template Files
- `.env.example` - Template with variable names
- `.env.template` - Alternative template format
- `config/*.template` - Configuration templates

---

## Related Documentation

- [Cloudflare API Setup](../CLOUDFLARE_API_SETUP.md)
- [Physical Hardware Inventory](../../docs/02-architecture/PHYSICAL_HARDWARE_INVENTORY.md)
- [Proxmox ACME Plan](./PROXMOX_ACME_CLOUDFLARE_PLAN.md)
- [Domain Structure](../../docs/02-architecture/DOMAIN_STRUCTURE.md)

---

## Next Steps

1. **Audit Current Secrets**
   - Run `scripts/check-env-secrets.sh`
   - Review this inventory
   - Identify missing secrets

2. **Create/Update .env Files**
   - Use templates as reference
   - Set all required values
   - Remove placeholder values

3. **Secure Storage**
   - Implement secrets management
   - Encrypt sensitive values
   - Set up access controls

4. **Documentation**
   - Update service-specific docs
   - Create .env.example files
   - Document secret rotation

---

**Last Updated:** 2025-01-20  
**Status:** 📋 Comprehensive Inventory  
**Next Review:** After secret audit