# 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:**
```yaml
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:

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

**Usage:**
- Service names
- Hostnames
- Paths
- General text

### Integer (`int`)

Whole numbers:

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

**Usage:**
- Port numbers
- UIDs/GIDs
- Counts and limits

### Float (`float`)

Decimal numbers:

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

**Usage:**
- Resource limits
- Ratios and percentages

### Boolean (`bool`)

True/false values:

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

**Usage:**
- Feature toggles
- Conditional configuration
- Enable/disable options

### Enum (`enum`)

Selection from predefined options:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

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

## Variable Sections

Variables are organized into **sections** that group related configuration:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:**

```bash
# 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:

```bash
# 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`:

```bash
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:**
```yaml
general:
  vars:
    service_name:
      type: str
    container_port:
      type: int
      default: 8080
```

**Template overrides:**
```yaml
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:

```bash
# 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:**
```yaml
traefik_host:
  description: Service subdomain or full hostname (e.g., 'app' or 'app.example.com')
```

**Bad:**
```yaml
traefik_host:
  description: Host
```

### Group Related Variables

Use sections to organize configuration:

```yaml
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](Core-Concepts-Defaults) - Managing default values
- [Variable Reference](Variables-Compose) - Complete variable list for each module
- [Templates](Core-Concepts-Templates) - How variables are used in templates

## See Also

- [Getting Started](Getting-Started) - Your first template generation
- [Developer Guide](Developers-Templates) - Creating templates with variables