add quickstart examples directory and link from README

3 files changed, 44 insertions, 0 deletions

diff --git a/examples/rake/Gemfile b/examples/rake/Gemfile
new file mode 100644
index 0000000..b1f79ad
--- /dev/null
+++ b/examples/rake/Gemfile
@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Point at the local rcm checkout; change to gem 'rcm' once published.
+gem 'rcm', path: '../../'
diff --git a/examples/rake/Rakefile b/examples/rake/Rakefile
new file mode 100644
index 0000000..27b7e7a
--- /dev/null
+++ b/examples/rake/Rakefile
@@ -0,0 +1,36 @@
+# Example: Using RCM with Rake (from a project directory).
+#
+# Run with:
+#   rake setup -- --dry      # dry run, no changes made
+#   rake setup -- --debug    # verbose output
+#   rake setup               # apply configuration
+#
+# This example assumes rcm is available via bundler (see Gemfile),
+# or you can swap the require for: require_relative '../../lib/dsl'
+require 'rcm'
+
+desc 'Apply system configuration'
+task :setup do
+  configure do
+    # Only run on host named 'earth'
+    given { hostname is :earth }
+
+    # Create a WireGuard config from an inline ERB template.
+    # The 'manage directory' directive creates /tmp/example/wg/ if it is missing.
+    file '/tmp/example/wg/wg0.conf' do
+      manage directory
+      from template
+
+      <<~TEMPLATE
+        [Interface]
+        Address = <%= "10.0.0.1/24" %>
+        ListenPort = 51820
+      TEMPLATE
+    end
+
+    # Ensure a specific line is present in a hosts file (idempotent).
+    file '/tmp/example/hosts.txt' do
+      line '192.168.1.101 earth.local'
+    end
+  end
+end
diff --git a/examples/rake/config.toml b/examples/rake/config.toml
new file mode 100644
index 0000000..5a21958
--- /dev/null
+++ b/examples/rake/config.toml
@@ -0,0 +1,4 @@
+[hostgroups]
+
+# Define groups of hosts that share configuration
+webservers = ["earth", "mars"]