LiveTemplate supports configuration via environment variables following the 12-factor app methodology. All configuration variables use the LVT_ prefix.

# Set connection limits
export LVT_MAX_CONNECTIONS=10000
export LVT_MAX_CONNECTIONS_PER_GROUP=100

# Configure allowed origins for WebSocket connections
export LVT_ALLOWED_ORIGINS="https://example.com,https://app.example.com"

# Set shutdown timeout
export LVT_SHUTDOWN_TIMEOUT=30s

# Configure logging
export LVT_LOG_LEVEL=info

package main

import (
    "log"
    "github.com/livetemplate/livetemplate"
)

func main() {
    // Load configuration from environment variables
    envConfig, err := livetemplate.LoadEnvConfig()
    if err != nil {
        log.Fatal("Failed to load config:", err)
    }

    // Validate configuration
    if err := envConfig.Validate(); err != nil {
        log.Fatal("Invalid config:", err)
    }

    // Create template with environment-based configuration
    tmpl := livetemplate.New("app", envConfig.ToOptions()...)

    // ... rest of your application
}

Maximum number of concurrent WebSocket connections across all users.

• Type: Integer
• Default: 0 (unlimited)
• Example: LVT_MAX_CONNECTIONS=10000
• Validation: Must be >= 0

Use case: Prevent resource exhaustion and OOM kills by limiting total connections.

Maximum number of connections per session group (user/session).

• Type: Integer
• Default: 0 (unlimited)
• Example: LVT_MAX_CONNECTIONS_PER_GROUP=100
• Validation: Must be >= 0

Use case: Prevent a single user from exhausting all connection slots (DoS protection).

Comma-separated list of allowed WebSocket origins for CORS.

• Type: String (comma-separated URLs)
• Default: Empty (allow all in dev mode, restrict in production)
• Example: LVT_ALLOWED_ORIGINS="https://example.com,https://app.example.com"
• Validation: None

Use case: Security - prevent unauthorized domains from connecting to your WebSocket endpoint.

Note: Whitespace around commas is automatically trimmed.

Disable WebSocket connections (HTTP-only mode).

• Type: Boolean
• Default: false
• Example: LVT_WEBSOCKET_DISABLED=true
• Accepted values: true, false, 1, 0, yes, no, on, off (case-insensitive)

Use case: Testing or deployments where WebSocket is not available.

WebSocket send buffer size per connection (async message queuing).

• Type: Integer
• Default: 50
• Example: LVT_WS_BUFFER_SIZE=100
• Validation: Must be > 0 (invalid values log a warning and fall back to the default — no error is returned)

Use case: Tune WebSocket backpressure behavior. Larger buffers handle burst traffic; smaller buffers reduce memory per connection.

Recommended values:

• Low traffic / memory constrained: 10-25
• Normal traffic: 50 (default)
• High traffic / burst heavy: 100-1000

Note: This variable is loaded directly in New(), not via LoadEnvConfig().

Enable development mode.

• Type: Boolean
• Default: false
• Example: LVT_DEV_MODE=true
• Accepted values: true, false, 1, 0, yes, no, on, off (case-insensitive)

Features when enabled:

• Uses local client library instead of CDN
• More verbose logging
• Less strict origin checking

Use case: Local development and debugging.

Disable the automatic loading indicator on page load.

• Type: Boolean
• Default: false
• Example: LVT_LOADING_DISABLED=true
• Accepted values: true, false, 1, 0, yes, no, on, off (case-insensitive)

Use case: Custom loading indicators or SSR scenarios.

Enable non-JS form submission support via POST-Redirect-GET pattern.

• Type: Boolean
• Default: true
• Example: LVT_PROGRESSIVE_ENHANCEMENT=false
• Accepted values: true, false, 1, 0, yes, no, on, off (case-insensitive)
• Validation: Invalid values cause a startup error via LoadEnvConfig()

Use case: When enabled, HTTP form submissions from non-JavaScript clients receive full HTML page responses. Disable if you only support WebSocket-capable clients.

Base directory for template auto-discovery.

• Type: String (file path)
• Default: Empty (uses runtime.Caller detection)
• Example: LVT_TEMPLATE_BASE_DIR=./templates

Use case: Override automatic template directory detection. Useful in containerized deployments where runtime.Caller may resolve to an unexpected path.

Maximum duration to wait for graceful shutdown before forcing close.

• Type: Duration
• Default: 30s
• Example: LVT_SHUTDOWN_TIMEOUT=45s
• Format: Go duration format (30s, 1m, 500ms, 1h30m)
• Validation: Must be positive

Use case: Control how long to wait for active connections to close during deployment.

Recommended values:

• Development: 10s
• Production: 30s - 60s
• Long-running operations: 2m - 5m

Logging verbosity level.

• Type: String
• Default: info
• Example: LVT_LOG_LEVEL=debug
• Accepted values: debug, info, warn, error (case-insensitive)
• Validation: Must be one of the accepted values

Levels:

• debug: Verbose logging for development
• info: Standard operational logging (default)
• warn: Warnings and errors
• error: Errors only

Enable Prometheus metrics export.

• Type: Boolean
• Default: true
• Example: LVT_METRICS_ENABLED=false
• Accepted values: true, false, 1, 0, yes, no, on, off (case-insensitive)

Use case: Disable metrics in development or testing environments.

Note: When disabled, the /metrics endpoint will still exist but return empty results.

export LVT_DEV_MODE=true
export LVT_LOG_LEVEL=debug
export LVT_SHUTDOWN_TIMEOUT=10s

export LVT_MAX_CONNECTIONS=10000
export LVT_MAX_CONNECTIONS_PER_GROUP=100
export LVT_ALLOWED_ORIGINS="https://example.com,https://app.example.com"
export LVT_SHUTDOWN_TIMEOUT=30s
export LVT_LOG_LEVEL=info
export LVT_METRICS_ENABLED=true
export LVT_WS_BUFFER_SIZE=100

export LVT_MAX_CONNECTIONS=5000
export LVT_MAX_CONNECTIONS_PER_GROUP=50
export LVT_ALLOWED_ORIGINS="https://secure.example.com"
export LVT_SHUTDOWN_TIMEOUT=45s
export LVT_LOG_LEVEL=warn

export LVT_WEBSOCKET_DISABLED=true
export LVT_LOADING_DISABLED=true
export LVT_METRICS_ENABLED=false
export LVT_LOG_LEVEL=error

version: '3.8'
services:
  app:
    image: myapp:latest
    environment:
      LVT_MAX_CONNECTIONS: "10000"
      LVT_MAX_CONNECTIONS_PER_GROUP: "100"
      LVT_ALLOWED_ORIGINS: "https://example.com"
      LVT_SHUTDOWN_TIMEOUT: "30s"
      LVT_LOG_LEVEL: "info"
      LVT_METRICS_ENABLED: "true"
      LVT_WS_BUFFER_SIZE: "100"
    ports:
      - "8080:8080"

apiVersion: v1
kind: ConfigMap
metadata:
  name: livetemplate-config
data:
  LVT_MAX_CONNECTIONS: "10000"
  LVT_MAX_CONNECTIONS_PER_GROUP: "100"
  LVT_ALLOWED_ORIGINS: "https://example.com,https://app.example.com"
  LVT_SHUTDOWN_TIMEOUT: "30s"
  LVT_LOG_LEVEL: "info"
  LVT_METRICS_ENABLED: "true"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: app
        image: myapp:latest
        envFrom:
        - configMapRef:
            name: livetemplate-config

You can also configure LiveTemplate programmatically using options:

tmpl := livetemplate.New("app",
    livetemplate.WithMaxConnections(10000),
    livetemplate.WithMaxConnectionsPerGroup(100),
    livetemplate.WithAllowedOrigins([]string{"https://example.com"}),
    livetemplate.WithDevMode(false),
)

Note: Programmatic configuration takes precedence over environment variables.

Configuration is automatically validated when loaded:

envConfig, err := livetemplate.LoadEnvConfig()
if err != nil {
    // Handle invalid environment variable format
    log.Fatal(err)
}

// Explicit validation
if err := envConfig.Validate(); err != nil {
    // Handle invalid configuration values
    log.Fatal(err)
}

Common validation errors:

• Negative connection limits
• Invalid duration format
• Invalid log level
• Negative shutdown timeout

1. Use environment variables in production: Never hardcode configuration in source code
2. Set connection limits: Always set LVT_MAX_CONNECTIONS to prevent OOM
3. Configure allowed origins: Set LVT_ALLOWED_ORIGINS in production for security
4. Use appropriate shutdown timeout: Balance between graceful shutdown and deployment speed
5. Enable metrics in production: Keep LVT_METRICS_ENABLED=true for observability
6. Use ConfigMaps in Kubernetes: Centralize configuration management
7. Validate on startup: Always call Validate() before running your application

Cause: Value is not a valid integer or is negative.

Solution: Use a non-negative integer: LVT_MAX_CONNECTIONS=10000

Cause: Value is not in Go duration format.

Solution: Use Go duration format: LVT_SHUTDOWN_TIMEOUT=30s

Cause: Origin not in LVT_ALLOWED_ORIGINS.

Solution: Add your domain to allowed origins or set LVT_DEV_MODE=true for development.

Cause: LVT_METRICS_ENABLED=false

Solution: Set LVT_METRICS_ENABLED=true (default)

• ROADMAP.md - Project roadmap
• OBSERVABILITY.md - Logging and metrics guide
• SCALING.md - Scaling recommendations