📚 Guides

In-depth guides for working with Itamae.

🧠 Core Concepts

Guide	Description
Writing Recipes	Recipe DSL, including recipes, guards, node access
Node Attributes	Loading, accessing, and validating host-specific data
Definitions	Grouping resources into reusable parameterized blocks
Notifications	Triggering actions between resources with notifies/subscribes
run_command	Executing commands and capturing output in recipes

🏗️ Infrastructure

Guide	Description
Backends	Local, SSH, Docker, and Jail execution
CLI Reference	All commands, options, and exit codes
Handlers	Event handlers for logging and monitoring

🔌 Extending Itamae

Guide	Description
Plugins	Creating and using recipe and resource plugins
Best Practices	Recommended project structure and patterns

🌍 Real-World Examples

Example	Description
Nginx Web Server	Install and configure Nginx with virtual hosts and SSL
PostgreSQL Database	Set up PostgreSQL with users, databases, and backups
Ruby App Deployment	Deploy a Ruby app with Puma and systemd
Docker Host	Provision a Docker host with daemon configuration
User Management	Manage users, groups, SSH keys, and sudoers
Monitoring Stack	Deploy monitoring agents with health checks
Security Hardening	SSH hardening, firewall rules, and audit logging
Redis Cache	In-memory data store with persistence and kernel tuning
Let’s Encrypt SSL	TLS certificates with certbot and auto-renewal
Log Management	Centralized rsyslog forwarding and logrotate
MySQL Database	MySQL server with users, backups, and tuning
HAProxy Load Balancer	Reverse proxy with health checks and stats dashboard
Jenkins CI	CI/CD server with Java, plugins, and Nginx proxy
Multi-Tier Application	Compose roles for a full web + app + db stack

See all examples for complete recipes with directory structures, node attributes, and templates.

❓ FAQ

Common questions and answers about Itamae – see the full FAQ page.

⚡ Quick Reference

📋 Resource Cheat Sheet

# Files & directories
file '/path'          do content 'data'; mode '0644' end
directory '/path'     do mode '0755'; owner 'user' end
template '/path'      do source 'tmpl.erb'; variables(k: 'v') end
remote_file '/path'   do source 'files/src'; mode '0644' end
link '/path'          do to '/target' end

# Packages & services
package 'name'        do version '1.0' end
gem_package 'name'    do version '1.0' end
service 'name'        do action [:enable, :start] end

# Commands
execute 'name'        do command 'echo hi'; not_if 'test -f /done' end

# Users & groups
user 'name'           do uid 1000; home '/home/name'; shell '/bin/bash' end
group 'name'          do gid 1000 end

# Other
git '/path'           do repository 'url'; revision 'main' end
http_request '/path'  do url 'https://example.com/file' end
remote_directory '/p' do source 'dir' end
local_ruby_block 'n'  do block { puts 'hi' } end

🔄 Common Patterns

# Notify service on config change
template '/etc/app.conf' do
  source 'app.conf.erb'
  notifies :restart, 'service[app]'
end

# Conditional execution
execute 'setup' do
  command '/opt/bin/setup'
  not_if 'test -f /opt/.done'
end

# Multiple node files
# itamae local -j base.json -j env.json roles/web.rb