ChristianLempa_Boilerplates/.wiki/Core-Concepts-Variables.md

Variables

Variables are the configurable parameters that customize your templates. This page explains variable types, sections, dependencies, and how to work with them effectively.

What are Variables?

Variables are parameters that control template generation. They can be:

• Simple values (strings, numbers, booleans)
• Selections from options (enums)
• Validated inputs (emails, URLs, hostnames)

Example:

service_name: my-app        # String
container_port: 8080        # Integer
traefik_enabled: true       # Boolean
restart_policy: unless-stopped  # Enum (selection from options)

Variable Types

String (str)

Text values with optional constraints:

service_name:
  type: str
  description: Service name
  default: my-service

Usage:

• Service names
• Hostnames
• Paths
• General text

Integer (int)

Whole numbers:

container_port:
  type: int
  description: Container port
  default: 8080

Usage:

• Port numbers
• UIDs/GIDs
• Counts and limits

Float (float)

Decimal numbers:

cpu_limit:
  type: float
  description: CPU limit in cores
  default: 1.5

Usage:

• Resource limits
• Ratios and percentages

Boolean (bool)

True/false values:

traefik_enabled:
  type: bool
  description: Enable Traefik integration
  default: false

Usage:

• Feature toggles
• Conditional configuration
• Enable/disable options

Enum (enum)

Selection from predefined options:

restart_policy:
  type: enum
  description: Container restart policy
  options: [unless-stopped, always, on-failure, no]
  default: unless-stopped

Usage:

• Network modes (bridge, host, macvlan)
• Log levels (debug, info, warn, error)
• Policies and strategies

Email (email)

Email addresses with validation:

admin_email:
  type: email
  description: Administrator email
  default: admin@example.com

Validation:

• Must match email format (user@domain.com)
• Rejects invalid email addresses

URL (url)

Full URLs with scheme validation:

api_endpoint:
  type: url
  description: API endpoint URL
  default: https://api.example.com

Validation:

• Must include scheme (http://, https://)
• Must have valid host

Hostname (hostname)

Domain names or hostnames:

traefik_host:
  type: hostname
  description: Service hostname
  default: app.example.com

Validation:

• Valid DNS hostname format
• Accepts subdomains and domains

Variable Properties

Every variable can have these properties:

variable_name:
  type: str                    # Variable type (required)
  description: Description     # Help text
  default: value               # Default value
  prompt: Custom prompt text   # Override description in prompts
  extra: Additional help       # Extended help text
  sensitive: false             # Mask input (for passwords)
  autogenerated: false         # Auto-generate if empty
  needs: condition             # Dependency constraint

Sensitive Variables

Mask input for passwords and secrets:

admin_password:
  type: str
  description: Administrator password
  sensitive: true

Behavior:

• Input is masked in prompts (********)
• Displayed as *** in output
• Suitable for passwords, API keys, tokens

Autogenerated Variables

Automatically generate values if not provided:

secret_key:
  type: str
  description: Secret key
  autogenerated: true

Behavior:

• Shows *auto placeholder in prompts
• Generates value during rendering if empty
• Press Enter to accept auto-generation

Custom Prompts

Override the description text in interactive prompts:

service_name:
  description: Service name (used in docker-compose)
  prompt: Enter service name

Variable Sections

Variables are organized into sections that group related configuration:

spec:
  general:        # Required by default
    title: General Settings
    vars:
      service_name: {...}
      container_port: {...}
  
  networking:     # Optional section
    title: Network Configuration
    toggle: networking_enabled
    vars:
      network_name: {...}
      network_mode: {...}

Required Sections

Sections marked as required: true must be configured:

general:
  title: General
  required: true
  vars:
    service_name: {...}

Behavior:

• Users must provide values
• No way to skip
• general section is implicitly required

Optional Sections

Sections with a toggle variable:

traefik:
  title: Traefik
  toggle: traefik_enabled
  vars:
    traefik_host: {...}
    traefik_network: {...}

Behavior:

• User chooses whether to enable
• If disabled, section variables are skipped
• Toggle variable is auto-created as boolean

Section Dependencies

Sections can depend on other sections:

traefik_tls:
  title: Traefik TLS/SSL
  needs: traefik
  vars:
    traefik_tls_enabled: {...}

Behavior:

• Only shown if dependency section is enabled
• Supports multiple dependencies: needs: [traefik, networking]
• Automatically sorted in dependency order

Variable Dependencies

Variables can depend on other variables using needs constraints:

Simple Constraint

Variable only visible when condition is met:

network_name:
  type: str
  description: Network name
  needs: network_mode=bridge

Behavior:

• Only shown when network_mode equals bridge
• Hidden for other network modes

Multiple Values (OR)

Variable visible for multiple values:

network_name:
  type: str
  description: Network name
  needs: network_mode=bridge,macvlan

Behavior:

• Shown when network_mode is bridge OR macvlan
• Hidden when network_mode is host

Multiple Constraints (AND)

Variable requires multiple conditions:

traefik_tls_certresolver:
  type: str
  description: Certificate resolver
  needs: traefik_enabled=true;network_mode=bridge

Behavior:

• Requires ALL conditions to be true
• Semicolon (;) separates conditions
• Comma (,) within a condition is OR

Variable Precedence

Variables are resolved in priority order (lowest to highest):

1. Module spec - Default values for all templates
2. Template spec - Template-specific overrides
3. User config - Saved defaults in ~/.config/boilerplates/config.yaml
4. CLI arguments - --var flags

Example:

# Module default: restart_policy=unless-stopped
# Template override: restart_policy=always
# User config: restart_policy=on-failure
# CLI override: --var restart_policy=no

# Result: restart_policy=no (CLI wins)

Setting Default Values

Save frequently used values:

# Set a default
boilerplates compose defaults set container_timezone="America/New_York"

# View all defaults
boilerplates compose defaults list

# Remove a default
boilerplates compose defaults rm container_timezone

# Clear all defaults
boilerplates compose defaults clear

Interactive Prompts

When generating templates interactively, the CLI prompts for each variable:

Text Input

Service name: |my-app|

• Type your value or press Enter for default
• Default shown in brackets

Boolean Input

Enable Traefik? (y/n) [n]:

• y or yes for true
• n or no for false
• Press Enter for default

Enum Selection

Restart policy:
  1) unless-stopped (default)
  2) always
  3) on-failure
  4) no
Select [1]:

• Enter number to select
• Press Enter for default

Sensitive Input

Admin password: ********

• Input is masked
• Not echoed to terminal

Non-Interactive Mode

Skip prompts entirely using --no-interactive:

boilerplates compose generate nginx ./output \
  --var service_name=my-nginx \
  --var container_port=8080 \
  --no-interactive

Behavior:

• Uses defaults for all variables
• No user interaction required
• Suitable for automation and CI/CD

Variable Validation

At Prompt Time

Variables are validated during prompts:

• Type checking (int must be number)
• Format validation (email, URL, hostname)
• Option validation (enum must be in options list)

Example:

Container port: abc
Error: Must be a valid integer
Container port:

At Template Load

Templates are validated when loaded:

• Check for undefined variables used in templates
• Verify variable dependencies are valid
• Ensure no circular dependencies

Advanced Features

Template Variable Inheritance

Templates inherit ALL variables from their module schema. You only override what's different:

Module defines:

general:
  vars:
    service_name:
      type: str
    container_port:
      type: int
      default: 8080

Template overrides:

spec:
  general:
    vars:
      service_name:
        default: nginx  # Only override default
      # container_port inherits 8080

Dynamic Visibility

Variables with needs constraints are dynamically shown/hidden based on other values:

# If user selects network_mode=host
# → Network name prompt is skipped (needs: network_mode=bridge)

# If user selects network_mode=bridge
# → Network name prompt is shown

Dependency Resolution

The CLI automatically:

• Topologically sorts sections based on dependencies
• Validates no circular dependencies exist
• Reports errors for missing dependencies

Best Practices

Naming Conventions

• Use snake_case for variable names
• Group related variables with common prefixes:
  • traefik_* for Traefik variables
  • network_* for networking variables
  • ports_* for port configuration

Provide Good Defaults

• Choose sensible defaults for common use cases
• Use empty defaults when user input is required
• Document why a default was chosen

Use Descriptions

• Clear, concise descriptions
• Explain what the variable controls
• Include examples if helpful

Good:

traefik_host:
  description: Service subdomain or full hostname (e.g., 'app' or 'app.example.com')

Bad:

traefik_host:
  description: Host

Group Related Variables

Use sections to organize configuration:

spec:
  general:        # Core configuration
  network:        # Network settings
  traefik:        # Reverse proxy
  traefik_tls:    # TLS/SSL configuration

Use Dependencies Wisely

• Keep dependency chains short
• Avoid overly complex conditions
• Test dependency behavior thoroughly

Next Steps

• Configuration - Managing default values
• Variable Reference - Complete variable list for each module
• Templates - How variables are used in templates

See Also

• Getting Started - Your first template generation
• Developer Guide - Creating templates with variables