proxmox/docs/04-configuration/ENV_STANDARDIZATION.md

# Environment Variable Standardization

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

All scripts and configurations now use a **single standardized `.env` file location**: `~/.env`

## Standard Variable Names

All scripts use these consistent variable names from `~/.env`:

- `PROXMOX_HOST` - Proxmox host IP or hostname
- `PROXMOX_PORT` - Proxmox API port (default: 8006)
- `PROXMOX_USER` - Proxmox API user (e.g., root@pam)
- `PROXMOX_TOKEN_NAME` - API token name
- `PROXMOX_TOKEN_VALUE` - API token secret value

## Backwards Compatibility

For backwards compatibility with existing code that uses `PROXMOX_TOKEN_SECRET`, the scripts automatically map:
- `PROXMOX_TOKEN_SECRET = PROXMOX_TOKEN_VALUE` (if TOKEN_SECRET is not set)

## Files Updated

1. **MCP Server** (`mcp-proxmox/index.js`)
   - Now loads from `~/.env` instead of `../.env`
   - Falls back to `../.env` for backwards compatibility

2. **Deployment Scripts** (`smom-dbis-138-proxmox/lib/common.sh`)
   - `load_config()` now automatically loads `~/.env` first
   - Then loads `config/proxmox.conf` which can override or add settings

3. **Proxmox API Library** (`smom-dbis-138-proxmox/lib/proxmox-api.sh`)
   - `init_proxmox_api()` now loads from `~/.env` first
   - Maps `PROXMOX_TOKEN_VALUE` to `PROXMOX_TOKEN_SECRET` for compatibility

4. **Configuration File** (`smom-dbis-138-proxmox/config/proxmox.conf`)
   - Updated to reference `PROXMOX_TOKEN_VALUE` from `~/.env`
   - Maintains backwards compatibility with `PROXMOX_TOKEN_SECRET`

5. **Standard Loader** (`load-env.sh`)
   - New utility script for consistent .env loading
   - Can be sourced by any script: `source load-env.sh`

**Config validation (CI/pre-deploy):** Run `scripts/validation/validate-config-files.sh` to check required config files and optional env; see [README.md](README.md) and project root `.env.example`.

## Usage

### In Bash Scripts

```bash
# Option 1: Use load_env_file() from common.sh (recommended)
source lib/common.sh
load_config  # Automatically loads ~/.env first

# Option 2: Use standalone loader
source load-env.sh
load_env_file
```

### In Node.js (MCP Server)

The MCP server automatically loads from `~/.env` on startup.

### Configuration Files

The `config/proxmox.conf` file will:
1. First load values from `~/.env` (via `load_env_file()`)
2. Then apply any overrides or additional settings from the config file

## Example ~/.env File

```bash
# Proxmox MCP Server Configuration
PROXMOX_HOST=192.168.11.10
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=your-actual-token-secret-here
PROXMOX_PORT=8006
PROXMOX_ALLOW_ELEVATED=false
```

## Validation

All validation scripts use the same `~/.env` file:
- `validate-ml110-deployment.sh`
- `test-connection.sh`
- `verify-setup.sh`

## Benefits

1. **Single Source of Truth**: One `.env` file for all scripts
2. **Consistency**: All scripts use the same variable names
3. **Easier Management**: Update credentials in one place
4. **Backwards Compatible**: Existing code using `PROXMOX_TOKEN_SECRET` still works