🚀 Getting Started

📥 Installation

Add Itamae to your Gemfile:

gem 'itamae'

Then run:

bundle install

Or install directly:

gem install itamae

✨ Your First Recipe

Create a file called recipe.rb:

package 'nginx' do
  action :install
end

service 'nginx' do
  action [:enable, :start]
end

▶️ Running Recipes

Local Execution

Apply the recipe on the local machine:

itamae local recipe.rb

Sample output:

 INFO : Starting Itamae...
 INFO : Recipe: /path/to/recipe.rb
 INFO :   package[nginx] installed will change from 'false' to 'true'
 INFO :   service[nginx] enabled will change from 'false' to 'true'
 INFO :   service[nginx] running will change from 'false' to 'true'

Remote Execution via SSH

Apply to a remote host:

itamae ssh --host host001.example.jp recipe.rb

Connect to a Vagrant VM:

itamae ssh --vagrant --host vm_name recipe.rb

Docker Execution

Build a Docker image with your recipes applied:

itamae docker --image ubuntu:22.04 --tag myapp:latest recipe.rb

🔍 Dry Run

Preview changes without applying them — see exactly what would change without risk:

itamae local --dry-run recipe.rb
itamae ssh -n -h web01.example.com recipe.rb  # -n is the short flag

💡 Dry-run shows full diffs for file/template changes and attribute comparisons for all resources. See the Dry-Run Mode guide for details on what each resource type shows.

📋 Node Attributes

Pass host-specific data via JSON or YAML files:

{
  "hostname": "web01",
  "app": {
    "port": 3000
  }
}

itamae local --node-json node.json recipe.rb

Access in recipes:

execute "hostname #{node[:hostname]}"

template '/etc/app.conf' do
  variables(port: node[:app][:port])
end

🏗️ Project Scaffolding

Generate a new project:

itamae init myproject

Generate a cookbook:

itamae generate cookbook nginx

Generate a role:

itamae generate role web

🎯 Next Steps