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 and project root .env.example.

Usage

In Bash Scripts

# 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

# 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