Environment Variables

Override any YAML configuration using environment variables for flexible, environment-specific deployments.

Overview

Environment variables enable:

✅ Configuration without file changes: Adjust settings per environment
✅ Secret management: Keep sensitive values out of version control
✅ Container orchestration: Easy Kubernetes/Docker configuration
✅ CI/CD integration: Dynamic configuration in pipelines
✅ 12-Factor compliance: Externalized configuration

Priority Order

Configuration is loaded in this order (later overrides earlier):

Default values - Built-in defaults
YAML configuration file - cbox-init.yaml
Environment variables - Runtime overrides

# YAML has log_level: info
# ENV overrides to debug
CBOX_INIT_GLOBAL_LOG_LEVEL=debug ./cbox-init

Naming Convention

Global Settings

Pattern: CBOX_INIT_GLOBAL_<SETTING_NAME>

CBOX_INIT_GLOBAL_SHUTDOWN_TIMEOUT=60
CBOX_INIT_GLOBAL_LOG_LEVEL=debug
CBOX_INIT_GLOBAL_LOG_FORMAT=json
CBOX_INIT_GLOBAL_METRICS_ENABLED=true
CBOX_INIT_GLOBAL_METRICS_PORT=9090
CBOX_INIT_GLOBAL_API_ENABLED=true
CBOX_INIT_GLOBAL_API_PORT=8080

Process-Specific Settings

Pattern: CBOX_INIT_PROCESS_<PROCESS_NAME>_<SETTING_NAME>

CBOX_INIT_PROCESS_NGINX_ENABLED=true
CBOX_INIT_PROCESS_NGINX_PRIORITY=20
CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE=5
CBOX_INIT_PROCESS_HORIZON_RESTART=always

Important: Process names are converted to uppercase and hyphens to underscores.

Process Name	Environment Prefix
`nginx`	`CBOX_INIT_PROCESS_NGINX_`
`queue-default`	`CBOX_INIT_PROCESS_QUEUE_DEFAULT_`
`php-fpm`	`CBOX_INIT_PROCESS_PHP_FPM_`

PHP-FPM Auto-Tuning

Pattern: PHP_FPM_AUTOTUNE_PROFILE

PHP_FPM_AUTOTUNE_PROFILE=medium
PHP_FPM_AUTOTUNE_PROFILE=heavy

See PHP-FPM Auto-Tuning for complete guide.

Global Settings Reference

Shutdown Configuration

# Shutdown timeout (seconds)
CBOX_INIT_GLOBAL_SHUTDOWN_TIMEOUT=60

Logging Configuration

# Log format (json|text)
CBOX_INIT_GLOBAL_LOG_FORMAT=json

# Log level (debug|info|warn|error)
CBOX_INIT_GLOBAL_LOG_LEVEL=info

# Multiline logging
CBOX_INIT_GLOBAL_LOG_MULTILINE_ENABLED=true
CBOX_INIT_GLOBAL_LOG_MULTILINE_TIMEOUT=500

# Log redaction
CBOX_INIT_GLOBAL_LOG_REDACTION_ENABLED=true

Metrics Configuration

# Enable Prometheus metrics
CBOX_INIT_GLOBAL_METRICS_ENABLED=true

# Metrics HTTP port
CBOX_INIT_GLOBAL_METRICS_PORT=9090

# Metrics URL path
CBOX_INIT_GLOBAL_METRICS_PATH=/metrics

Restart Configuration

# Exponential backoff (Go duration strings)
CBOX_INIT_GLOBAL_RESTART_BACKOFF_INITIAL=5s
CBOX_INIT_GLOBAL_RESTART_BACKOFF_MAX=60s

# Maximum automatic restart attempts (0 = unlimited)
CBOX_INIT_GLOBAL_MAX_RESTART_ATTEMPTS=5

API Configuration

# Enable Management API
CBOX_INIT_GLOBAL_API_ENABLED=true

# API HTTP port
CBOX_INIT_GLOBAL_API_PORT=8080

# API authentication token
CBOX_INIT_GLOBAL_API_AUTH=your-secure-token-here

Process Settings Reference

Basic Process Settings

# Enable/disable process
CBOX_INIT_PROCESS_<NAME>_ENABLED=true

# Command (JSON array)
CBOX_INIT_PROCESS_<NAME>_COMMAND='["php-fpm","-F","-R"]'

# Priority (startup order)
CBOX_INIT_PROCESS_<NAME>_PRIORITY=10

# Restart policy (always|on-failure|never)
CBOX_INIT_PROCESS_<NAME>_RESTART=always

# Scale (number of instances)
CBOX_INIT_PROCESS_<NAME>_SCALE=3

# Working directory
CBOX_INIT_PROCESS_<NAME>_WORKING_DIR=/var/www/html

Process Environment Variables

# Set environment variable for process
CBOX_INIT_PROCESS_<NAME>_ENV_<VAR_NAME>=value

# Examples:
CBOX_INIT_PROCESS_QUEUE_ENV_QUEUE_CONNECTION=redis
CBOX_INIT_PROCESS_QUEUE_ENV_REDIS_HOST=localhost
CBOX_INIT_PROCESS_APP_ENV_DEBUG=true

Complete Examples

Docker Compose

version: '3.8'

services:
  app:
    image: myapp:latest
    environment:
      # Global settings
      CBOX_INIT_GLOBAL_LOG_LEVEL: "info"
      CBOX_INIT_GLOBAL_METRICS_ENABLED: "true"
      CBOX_INIT_GLOBAL_API_ENABLED: "true"

      # PHP-FPM auto-tuning
      PHP_FPM_AUTOTUNE_PROFILE: "medium"

      # Process-specific
      CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE: "5"
      CBOX_INIT_PROCESS_HORIZON_ENABLED: "true"

    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2'

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: laravel-app
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: app
        image: myapp:v1.2.3
        env:
          # Global config
          - name: CBOX_INIT_GLOBAL_LOG_FORMAT
            value: "json"

          - name: CBOX_INIT_GLOBAL_METRICS_ENABLED
            value: "true"

          # PHP-FPM auto-tuning from ConfigMap
          - name: PHP_FPM_AUTOTUNE_PROFILE
            valueFrom:
              configMapKeyRef:
                name: cbox-config
                key: php_fpm_profile

          # API token from Secret
          - name: CBOX_INIT_GLOBAL_API_AUTH
            valueFrom:
              secretKeyRef:
                name: cbox-secrets
                key: api-token

          # Process scaling
          - name: CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE
            value: "5"

        resources:
          limits:
            memory: "2Gi"
            cpu: "2"

Dockerfile

FROM php:8.3-fpm-alpine

# Copy application
COPY . /var/www/html

# Copy cbox-init
COPY --from=builder /app/cbox-init /usr/local/bin/cbox-init

# Default environment variables
ENV CBOX_INIT_GLOBAL_LOG_FORMAT=json \
    CBOX_INIT_GLOBAL_LOG_LEVEL=info \
    PHP_FPM_AUTOTUNE_PROFILE=medium

# Run as PID 1
ENTRYPOINT ["/usr/local/bin/cbox-init"]

Shell Script

#!/bin/bash

# Production environment
export CBOX_INIT_GLOBAL_LOG_LEVEL=info
export CBOX_INIT_GLOBAL_METRICS_ENABLED=true
export CBOX_INIT_GLOBAL_API_ENABLED=true
export CBOX_INIT_GLOBAL_API_AUTH=$(cat /secrets/api-token)

# PHP-FPM configuration
export PHP_FPM_AUTOTUNE_PROFILE=heavy

# Process configuration
export CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE=10
export CBOX_INIT_PROCESS_HORIZON_ENABLED=true

# Run cbox-init
exec /usr/local/bin/cbox-init

Environment-Specific Patterns

Development

# development.env
CBOX_INIT_GLOBAL_LOG_LEVEL=debug
CBOX_INIT_GLOBAL_LOG_FORMAT=text  # Human-readable
CBOX_INIT_GLOBAL_METRICS_ENABLED=false
PHP_FPM_AUTOTUNE_PROFILE=dev
CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE=1

# Run with development settings
set -a; source development.env; set +a
./cbox-init

Staging

# staging.env
CBOX_INIT_GLOBAL_LOG_LEVEL=info
CBOX_INIT_GLOBAL_LOG_FORMAT=json
CBOX_INIT_GLOBAL_METRICS_ENABLED=true
PHP_FPM_AUTOTUNE_PROFILE=medium
CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE=3

Production

# production.env
CBOX_INIT_GLOBAL_LOG_LEVEL=warn
CBOX_INIT_GLOBAL_LOG_FORMAT=json
CBOX_INIT_GLOBAL_LOG_REDACTION_ENABLED=true
CBOX_INIT_GLOBAL_METRICS_ENABLED=true
CBOX_INIT_GLOBAL_API_ENABLED=true
CBOX_INIT_GLOBAL_API_AUTH=$(vault read -field=token secret/cbox-api)
PHP_FPM_AUTOTUNE_PROFILE=heavy
CBOX_INIT_PROCESS_QUEUE_DEFAULT_SCALE=10

Secret Management

HashiCorp Vault

#!/bin/bash
# Load secrets from Vault

export CBOX_INIT_GLOBAL_API_AUTH=$(vault kv get -field=api_token secret/cbox)
export DATABASE_PASSWORD=$(vault kv get -field=password secret/database)

exec /usr/local/bin/cbox-init

AWS Secrets Manager

#!/bin/bash
# Load secrets from AWS Secrets Manager

export CBOX_INIT_GLOBAL_API_AUTH=$(aws secretsmanager get-secret-value \
  --secret-id cbox-api-token \
  --query SecretString \
  --output text)

exec /usr/local/bin/cbox-init

Kubernetes Secrets

apiVersion: v1
kind: Secret
metadata:
  name: cbox-secrets
type: Opaque
data:
  api-token: <base64-encoded-token>
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: app
        env:
          - name: CBOX_INIT_GLOBAL_API_AUTH
            valueFrom:
              secretKeyRef:
                name: cbox-secrets
                key: api-token

Verification

Check Active Configuration

# Start with verbose logging
CBOX_INIT_GLOBAL_LOG_LEVEL=debug ./cbox-init

# Check which values are being used (in logs)
# Look for "Configuration loaded" messages

Validate Environment Variables

#!/bin/bash
# validate-env.sh

required_vars=(
    "CBOX_INIT_GLOBAL_LOG_LEVEL"
    "PHP_FPM_AUTOTUNE_PROFILE"
    "CBOX_INIT_GLOBAL_API_AUTH"
)

for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "ERROR: Required variable $var is not set"
        exit 1
    fi
done

echo "All required variables are set"

Troubleshooting

Environment Variable Not Working

Check variable name format:

# ❌ Wrong
CBOX_INIT_process_nginx_enabled=true

# ✅ Correct
CBOX_INIT_PROCESS_NGINX_ENABLED=true

Verify it's exported:

# Check if variable is exported
env | grep CBOX_INIT

# Export if needed
export CBOX_INIT_GLOBAL_LOG_LEVEL=debug

Complex Values (JSON Arrays)

# Process command as JSON array
CBOX_INIT_PROCESS_APP_COMMAND='["./my-app","--port=8080","--host=0.0.0.0"]'

# Escape quotes properly in shell
CBOX_INIT_PROCESS_APP_COMMAND="[\"./my-app\",\"--port=8080\"]"

Boolean Values

# All these are treated as true
CBOX_INIT_GLOBAL_METRICS_ENABLED=true
CBOX_INIT_GLOBAL_METRICS_ENABLED=1
CBOX_INIT_GLOBAL_METRICS_ENABLED=yes

# All these are treated as false
CBOX_INIT_GLOBAL_METRICS_ENABLED=false
CBOX_INIT_GLOBAL_METRICS_ENABLED=0
CBOX_INIT_GLOBAL_METRICS_ENABLED=no

Environment Variables

Environment Variables

Overview

Priority Order

Naming Convention

Global Settings

Process-Specific Settings

PHP-FPM Auto-Tuning

Global Settings Reference

Shutdown Configuration

Logging Configuration

Metrics Configuration

Restart Configuration

API Configuration

Process Settings Reference

Basic Process Settings

Process Environment Variables

Complete Examples

Docker Compose

Kubernetes Deployment

Dockerfile

Shell Script

Environment-Specific Patterns

Development

Staging

Production

Secret Management

HashiCorp Vault

AWS Secrets Manager

Kubernetes Secrets

Verification

Check Active Configuration

Validate Environment Variables

Troubleshooting

Environment Variable Not Working

Complex Values (JSON Arrays)

Boolean Values

See Also