Updating the machine type instructions

2 files changed, 91 insertions, 12 deletions

diff --git a/genome-docs/genome-docs-1.0.0/en-US/Cookbook.xml b/genome-docs/genome-docs-1.0.0/en-US/Cookbook.xml
index 2931157..66b9441 100644
--- a/genome-docs/genome-docs-1.0.0/en-US/Cookbook.xml
+++ b/genome-docs/genome-docs-1.0.0/en-US/Cookbook.xml
@@ -441,22 +441,101 @@ puppetd --test
 			There are several tools and config files that need to
 			know what types of machines are available for
 			provisioning on a particular <link
-				linkend="genome-appliance">Repo
+				linkend="genome-appliance">Genome Appliance
 				machine</link>.  To simplify this process
 			&PRODUCT; includes a DSL (Domain Specific Language) for
 			describing the machines available.
 		</para>
 
-		<para> 
-			At a very high level the only thing that needs to be
-			done is edit
-			<filename>/etc/genome/machine_types.rb</filename> on a
-			Repo Appliance.  The comments are the best documentation
-			for the details.  The trick is that this file is
-			typically <link
-				linkend="genome-repo-machine-customization">controlled
-				by puppet</link>.  
-			
+		<para>
+			Let's start with an example for creating a new developer
+			workstation machine type.  It's important to get all the
+			wiring setup to make puppet and your machine aware of the
+			new module before adding too much function.
+		</para>
+
+		<para>
+			The first step is usually to create a stubbed out module
+			on the &PRODUCT; Appliance and use <link linkend="genome-sync">genome-sync</link>
+			to setup the right information.  To do this, run these steps (on
+			the &PRODUCT; Appliance):
+			<screen>
+# Switch to the genome user
+su - genome
+
+# Create a working directory (the 'puppet' directory is important)
+mkdir -p /tmp/working/puppet/dev_workstation/manifests
+cd /tmp/working/puppet/dev_workstation
+
+# Create a simple puppet configuration
+# The name of the class must match the directory name
+echo """
+class dev_workstation {
+  package { "vim-enhanced":
+    ensure => latest;
+  }
+}
+""" > manifests/init.pp
+
+# Make the directory a git repository
+git config --global user.email "you@example.com"
+git config --global user.name "Your Name"
+git init
+git add .
+git commit -m "Priming the dev_workstation module"
+
+# Run genome-sync to publish this module
+# This sets up the 'public' git repositories
+# and the puppet working directory
+genome-sync save --workingdir=/tmp/working
+			</screen>
+		</para>
+		<para>
+			At this point, you should see the git repositories listed
+			on your &PRODUCT; Appliance at http://$GENOME/git/gitweb.cgi
+		</para>
+		<para>
+			The next step is to update the &PRODUCT; DSL file to make
+			it aware of a new 'machine' that contains this new puppet
+			class.  Machines can consist of multiple puppet classes,
+			but in this case, we are starting simple.  To do this, run 
+			these steps (on the &PRODUCT; Appliance):
+			<screen>
+# Make sure the permissions are okay on the machine_types.rb file
+su -
+chown genome:genome /etc/genome/machine_types.rb
+chown -R genome:genome /etc/puppet/modules/main
+exit
+
+# Switch to the genome user to update the machine_types.rb file
+su - genome
+
+# Clone the repo_extensions repository
+git clone /pub/git/puppet/repo_extensions /tmp/repo_extensions
+cd /tmp/repo_extensions
+
+# Add the new machine consisting of your new puppet module
+echo """
+newmachine('developer-workstation') do
+   set_classes 'dev_workstation'
+end
+""" >> files/machine_types.rb
+
+# Commit and push the change
+git add .
+git commit -m "Adding the new developer-workstation machine"
+git push
+
+# Update as root to make the &PRODUCT; Appliance
+# aware of the module you just synced.
+su -
+service puppetmaster restart
+puppetd --test
+			</screen>
+		</para>
+		<para>
+			At this point, you should see your new machine type listed
+                        on your &PRODUCT; Appliance at http://$GENOME/genome/machine_types.html
 		</para>
 
 		<para>
diff --git a/genome-docs/genome-docs.spec b/genome-docs/genome-docs.spec
index 8f0f7a7..c19ac68 100644
--- a/genome-docs/genome-docs.spec
+++ b/genome-docs/genome-docs.spec
@@ -1,6 +1,6 @@
 Name:           genome-docs
 Version:        1.0.0
-Release:        31%{?dist}
+Release:        32%{?dist}
 Summary:        Genome documentation 
 
 Group:          Applications/System