Skip to main content
The defaults system provides a three-tier configuration hierarchy that allows you to save and reuse installation settings across container deployments. This eliminates repetitive configuration and ensures consistency across your infrastructure.

​
Understanding the System

​
Three-Tier Configuration Hierarchy

Settings are applied in the following priority order:
1

Environment Variables (Highest Priority)

Variables set in your shell environment before running a script
export var_cpu=8
export var_ram=4096
2

App Defaults

Application-specific saved settings stored in:
/usr/local/community-scripts/defaults/<appname>.vars
3

User Defaults

Your global defaults applied to all containers stored in:
/usr/local/community-scripts/default.vars
4

Built-in Defaults (Lowest Priority)

Hardcoded defaults within each script, providing sensible fallback values

​
Installation Modes

When you run any installation script, you’ll be presented with several options:

​
Default Settings

Quick installation using built-in defaults with no configuration prompts.

Best For

First-time users and quick deployments where default settings are acceptable

​
Advanced Settings

Full customization with 19 configuration steps covering every aspect of the container. Available Settings:
  • CPU cores, RAM amount, disk size
  • Container name and network configuration
  • SSH access, API access, features
  • Password, SSH keys, tags
  • Security options
After completing advanced setup, you’ll be prompted to save these settings as App Defaults for future deployments

​
User Defaults

Use your saved global defaults that apply to all container installations. 
# Run any script and select option 3
bash pihole-install.sh
# Select: 3) User Defaults

​
App Defaults

Use previously saved application-specific defaults for identical deployments.
This option only appears if you’ve previously saved App Defaults for the specific application

​
Saving Defaults

​
During Installation

The easiest way to create defaults: 
# Run installation with Advanced Settings
bash pihole-install.sh

# Select: 2) Advanced Settings
# Configure all options
# At the end, when prompted:
# "Save as App Defaults for PiHole?" → Yes

# Settings saved to:
# /usr/local/community-scripts/defaults/pihole.vars

​
Manual File Creation

For advanced users who want to create defaults without running installation: 
sudo tee /usr/local/community-scripts/default.vars > /dev/null << 'EOF'
# Global User Defaults
var_cpu=4
var_ram=2048
var_disk=20
var_unprivileged=1
var_brg=vmbr0
var_gateway=192.168.1.1
var_timezone=Europe/Berlin
var_ssh=yes
var_container_storage=local
var_template_storage=local
EOF

​
Managing Defaults

​
View Settings

cat /usr/local/community-scripts/default.vars

​
Edit Settings

# Edit User Defaults
sudo nano /usr/local/community-scripts/default.vars

# Edit App Defaults
sudo nano /usr/local/community-scripts/defaults/pihole.vars

​
Update Existing Defaults

Re-run the installation with Advanced Settings: 
bash pihole-install.sh
# Select: Advanced Settings
# Make desired changes
# When asked to save: "Defaults already exist, Update?" → Yes

​
Delete Defaults

Deleting defaults cannot be undone. You’ll need to recreate them manually or through Advanced Settings.
# Delete User Defaults
sudo rm /usr/local/community-scripts/default.vars

# Delete specific App Defaults
sudo rm /usr/local/community-scripts/defaults/pihole.vars

# Delete all App Defaults
sudo rm /usr/local/community-scripts/defaults/*

​
Example Configurations

​
High-Performance Gaming Server

# /usr/local/community-scripts/defaults/gaming.vars
var_cpu=8
var_ram=8192
var_disk=100
var_unprivileged=0
var_fuse=1
var_nesting=1
var_tags=gaming;performance

​
Development Environment

# /usr/local/community-scripts/defaults/development.vars
var_cpu=4
var_ram=4096
var_disk=50
var_unprivileged=1
var_nesting=1
var_ssh=yes
var_tags=development;docker

​
Low-Resource IoT Container

# /usr/local/community-scripts/defaults/iot.vars
var_cpu=1
var_ram=512
var_disk=8
var_unprivileged=1
var_nesting=0
var_fuse=0
var_tun=0
var_tags=iot;monitoring

​
Troubleshooting

You haven’t created App Defaults yet for this application.Solution:
  1. Run the app with “Advanced Settings”
  2. Configure your preferences
  3. When finished, save as App Defaults
  4. Next time, App Defaults will be available
Check the following:
# Verify files exist
ls -la /usr/local/community-scripts/default.vars
ls -la /usr/local/community-scripts/defaults/<app>.vars

# Check file permissions
stat /usr/local/community-scripts/default.vars

# Check for environment variable override
env | grep var_
# If you have var_* set, those override saved defaults
Permission denied when saving defaults.Solution:
# Create the defaults directory if missing
sudo mkdir -p /usr/local/community-scripts/defaults

# Fix permissions
sudo chmod 755 /usr/local/community-scripts
sudo chmod 755 /usr/local/community-scripts/defaults

# Make sure you're running as root
sudo bash pihole-install.sh

​
File Format

Defaults files use a simple key=value format with specific syntax rules
# Comments start with #
var_name=value

# No spaces around =
var_cpu=4              # ✓ Correct
var_cpu = 4            # ✗ Wrong

# String values don't need quotes
var_hostname=mycontainer           # ✓ Correct
var_hostname='mycontainer'         # ✓ Also correct

# Values with spaces or special chars need quotes
var_tags="docker,production,testing"  # ✓ Correct

​
Best Practices

Do

  • Use App Defaults for app-specific settings
  • Use User Defaults for global preferences
  • Edit defaults files directly with nano
  • Keep separate App Defaults for each app
  • Back up your defaults regularly
  • Use environment variables for temporary overrides

Don't

  • Don’t use source on defaults files (security risk)
  • Don’t put sensitive passwords in defaults
  • Don’t modify defaults during installation
  • Don’t delete defaults directory while creating containers
  • Don’t use special characters without escaping

Environment Variables

Complete list of available configuration variables

Unattended Deployment

Automate deployments with defaults and environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us