Getting Started

Welcome to Boilerplates! This guide will help you get up and running in just a few minutes.

Overview

Boilerplates provides two main components:

Template Library

A collection of ready-to-use templates for common infrastructure components:

Docker Compose: Containerized applications (Nginx, Traefik, Grafana, etc.)
Terraform: Cloud infrastructure (AWS, Azure, GCP)
Ansible: Configuration management and automation
Kubernetes: Container orchestration deployments
Packer: Machine image builders

Templates include:

Pre-configured defaults for common use cases
Documentation and usage examples
Variable specifications for customization
Best practices baked in

Management CLI

A Python-based command-line tool to work with templates:

Browse and search the template library
Interactive configuration with validation
Generate customized templates
Manage multiple template libraries (official + custom)
Sync updates from repositories

Prerequisites

Before you begin, ensure you have:

Python 3.10 or higher installed
Git installed (for syncing template libraries)
Basic command-line knowledge
Internet connection (for downloading templates)

Installation

The quickest way to install the management CLI is using the automated installer:

curl -fsSL https://raw.githubusercontent.com/christianlempa/boilerplates/main/scripts/install.sh | bash

This installs the boilerplates command and configures access to the official template library.

For detailed installation instructions including platform-specific guidance, see the Installation page.

Your First Template

Once installed, let's generate your first template!

1. Sync the Template Library

Download the latest templates from the library:

boilerplates repo update

This syncs the official template library to ~/.config/boilerplates/libraries/default/.

2. Browse the Template Library

Explore available Docker Compose templates:

boilerplates compose list

You'll see a table showing available templates from the library with their descriptions.

3. Inspect a Template

Before generating, preview a template's structure and variables:

boilerplates compose show nginx

This shows:

Template metadata (name, version, author, description)
Available configuration variables and defaults
Template file structure
Variable dependencies and sections

4. Generate Files from Template

Now, let's use the CLI to generate customized files from a template! You have two options:

Interactive Mode (Recommended for beginners):

boilerplates compose generate nginx

The tool prompts you for each variable. You can:

Press Enter to accept defaults from the template
Type custom values
Navigate with arrow keys for selections
Skip optional sections

Non-Interactive Mode (For automation):

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

This uses template defaults and provided variables without prompts.

5. Review Generated Files

After generation, you'll find:

my-nginx/
├── docker-compose.yml
└── .env

Review the files and adjust as needed for your environment.

Basic Commands

Here are the essential commands you'll use regularly:

Library Management

Manage template library repositories:

# Sync official template library
boilerplates repo update

# List all configured libraries
boilerplates repo list

# Add a custom template library
boilerplates repo add my-templates https://github.com/user/templates \
  --directory library \
  --branch main

Working with Templates

Discover and use templates from the library:

# Browse available templates
boilerplates compose list

# Search the library
boilerplates compose search nginx

# Inspect template structure
boilerplates compose show nginx

# Generate files from template
boilerplates compose generate nginx ./output

# Validate template syntax
boilerplates compose validate

Working with Defaults

Save frequently used values to avoid repetitive typing:

# Set a default value
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

Common Workflows

Workflow 1: Quick Generation with Defaults

Use template defaults without customization:

boilerplates compose generate portainer --no-interactive

Workflow 2: Interactive Customization

Customize template variables interactively:

boilerplates compose show traefik         # Review template structure
boilerplates compose generate traefik     # Customize via prompts

Workflow 3: Automation

For scripts and CI/CD pipelines:

boilerplates compose generate authentik ./auth \
  --var service_name=authentik \
  --var traefik_enabled=true \
  --var traefik_host=auth.example.com \
  --no-interactive \
  --dry-run  # Preview first

Advanced Features

Dry Run

Preview generated files without writing them:

boilerplates compose generate nginx --dry-run

Debug Mode

Enable detailed logging for troubleshooting:

boilerplates --log-level DEBUG compose generate nginx

Variable Override

Override specific variables without interactive prompts:

boilerplates compose generate grafana \
  --var service_name=monitoring-grafana \
  --var grafana_port=3000

Next Steps

Now that you know the basics, explore more:

Templates - Learn how templates work
Variables - Understand variable types and dependencies
Configuration - Customize your setup
Variable Reference - Complete variable documentation

Troubleshooting

CLI Command Not Found

If the boilerplates command is not found after installation:

# Ensure pipx binaries are in PATH
export PATH="$HOME/.local/bin:$PATH"

# Add to your shell profile (.bashrc, .zshrc, etc.)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Templates Not Available

If templates aren't showing up after installation:

# Sync the template library
boilerplates repo update

# Verify library is configured
boilerplates repo list

Permission Issues

If you encounter permission errors:

# Ensure output directory is writable
chmod +w ./output-directory

# Or generate to a different location
boilerplates compose generate nginx ~/my-projects/nginx

Getting Help

Documentation: Browse the Wiki for comprehensive guides
Discord: Join the community for real-time help
GitHub Issues: Report bugs or request features
YouTube: Watch video tutorials

Happy templating!

Getting-Started.md 6.9 KB Permalink History Raw