Renaming everying everest to genome

1 files changed, 483 insertions, 0 deletions

diff --git a/genome-docs/genome-docs-1.0.0/en-US/Tooling.xml b/genome-docs/genome-docs-1.0.0/en-US/Tooling.xml
new file mode 100644
index 0000000..33d8b8a
--- /dev/null
+++ b/genome-docs/genome-docs-1.0.0/en-US/Tooling.xml
@@ -0,0 +1,483 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter id="genome-Tooling">
+	<title>Tooling</title>
+	<para>
+		One of the goals of &PRODUCT; is not to event new tools but
+		rather to leverage and contribute to existing Open Source
+		projects.  This section presents the user with links to many
+		technologies that can be considered prerequisites for
+		contributing to &PRODUCT;.
+	</para>
+
+	<section id="genome-replace-self">
+		<title>genome-replace-self</title> 
+		<para>
+		      To avoid many "chicken and the egg" sorts of provisioning
+		      problems the &PRODUCT; tooling provides a RPM and script
+		      called <application>genome-replace-self</application>.
+		      As the name suggests this tool is a quick way to
+		      completely replace a machine.  The term
+		      <emphasis>replace-self</emphasis> is borrowed from
+		      <application>koan</application> and under the covers that
+		      is basically all that is really happening.  The script does
+		      includes some helpful logic to properly install koan on
+		      whatever Red Hat based system was previously running on
+		      the system in question.
+		</para>
+
+		<important>
+			<title>Important</title>
+			<para>
+				Machines setup via
+				<application>genome-replace-self</application>
+				are not always controlled by
+				<application>puppet</application>.  They tend to be treated
+				more like appliances.
+			</para>
+		</important>
+
+		<section id="genome-replace-self-usage">
+			<title>Usage</title> 
+			<para>
+				To use this tool the user must know the profile
+				that will be used to
+				<emphasis>replace-self</emphasis>.  This can be
+				obtained easily with
+				<application>koan</application>.
+			</para>
+
+			<screen> 
+genome-replace-self --help
+
+# Select a profile from the list this command returns
+koan -s [Your &PRODUCT; Repo machine] --list-profiles 
+
+# Only certain types of machines require the -m (metadata) flag
+genome-replace-self -c [Your &PRODUCT; Repo machine] -p [Profile selected in previous step]
+		        </screen>
+
+			<note>
+				<title>Note</title>
+				<para>
+					Ideally which profile to select should
+					be obvious based on the names.  A good
+					practice is to have the profiles
+					include both the architecture and
+					operating system in the name.
+				</para>
+			</note>
+		</section>
+	</section>
+
+	<section id="genome-GenomeBootstrap">
+		<title>genome-bootstrap</title> 
+
+		<section id="genome-GenomeBootstrap-Background">
+			<title>Background</title> 
+			<para>   
+				With the introduction of virtualization, we are able to
+				easily rebuild entire environments quickly; however
+				there is a fair amount of complexity involved in doing
+				so. We've created a tool called
+				<application>genome-bootstrap</application> that
+				automates the process of wiring a machine up to puppet. 
+			</para>
+
+			<para>
+				There are essentially two ways of using
+				<application>genome-bootstrap</application>.  One way,
+				which does not require root privileges, is to run with
+				the <emphasis>--config-only</emphasis> option.  This configures everything
+				on &PRODUCT; repo to prepare for an installation.
+				Obvously this can also be used to update a machine's
+				configuration.
+			</para>
+
+			<para> 
+				The second way to use the tool requires root privileges
+				since it kicks of a <application>Koan</application>
+				process.  
+			</para>
+
+			<note>
+				<title>Note</title>
+				<para>
+					The <emphasis>--config-only</emphasis> option
+					is especially useful for bootstrapping Host
+					machines.  Quite often a machine that will be
+					turned into a Host does not even have
+					<application>genome-bootstrap</application>
+					installed.  It's easy to run
+					<application>genome-bootstrap</application>
+					with <emphasis>--config-only</emphasis> from
+					another machine and then procede with Koan on
+					the soon-to-be Host.
+				</para>
+			</note>
+		</section>
+
+		<section id="genome-GenomeBootstrap-features">
+			<title>Features</title>
+			<orderedlist>
+				<listitem>
+					<para>
+						Creates DDNS entries for your
+						machines during the bootstrap
+						process
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						Creates a
+						<application>Cobbler</application>
+						system record for provisioning
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						Guides the user through the
+						process of setting parameters
+						to be used by
+						<application>Puppet</application>
+						for configuration
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						Optionally starts the
+						<application>Koan</application>
+						process
+					</para>
+				</listitem>
+			</orderedlist>
+
+			<important>
+				<title>Important</title>
+				<para>
+					As of version 0.4.0 we are not longer tied to using
+					Red Hat's internal DDNS solution.  This is great for users with stricter
+					networking requirements.
+				</para>
+			</important>
+
+		</section>
+
+		<section id="genome-GenomeBootstrap-installation">
+			<title>Installation</title>
+			<para>
+				The required RPMs should already be installed
+				on any machine already bootstrapped in the
+				&PRODUCT; environment.  This is useful for the
+				<emphasis>--config-only</emphasis> mode.  If
+				you want to install &PRODUCT; machines in a
+				virtualized environment you will need to setup
+				a <link linkend="genome-cloud-appliance">Cloud
+					Appliance </link>.  That machine 
+				comes with
+				<application>genome-bootstrap</application>
+				already installed.
+			</para>
+
+			<para>
+				Should you need to install
+				<application>genome-bootstrap</application> manually,
+				yum can be configured to point to the
+				<application>Cobbler</application> server running on
+				your &PRODUCT; Repo.  Once yum is properly setup you
+				can run:
+				<screen>
+# <userinput>yum install rubygem-genome-bootstrap</userinput>
+				</screen>
+			</para>
+		</section>
+
+		<section>
+			<title>Usage</title>
+			<para>
+				<application>genome-bootstrap</application> does not
+				need any parameters.  Simply run the program and you
+				will be guided through the bootstrap process.
+				<note>
+					<title>Note</title>
+					<para>
+						Originally
+						<application>genome-bootstrap</application>
+						had all sorts of complicated command
+						line flags.  While this was nice for
+						scripting it was not a very pleasant
+						UI.  Switching to a wizard was the
+						simplist way to keep the documentation
+						up to speed with the tool.  For
+						scripting be sure to checkout the <link
+							linkend="genome-GenomeBootstrap-Advanced">Advanced
+							Mode</link> for
+						<application>genome-bootstrap</application>.
+					</para>
+				</note>
+				&JBOSSDEVBOOTSTRAPEXAMPLE;
+			</para>
+		</section>
+
+		<section id="genome-GenomeBootstrap-Advanced">
+			<title>Advanced Mode</title>
+			<important>
+				<title>Important</title>
+				<para>
+					Most casual users of the
+					<application>genome-bootstrap</application> tool will
+					not require this feature and can simply skip this
+					section.
+				</para>
+			</important>
+
+			<para>
+				The advanced mode is most useful for scripting.  It
+				also allows for more complicated use cases which
+				operate outside of a normal Red Hat internal network.
+				The only required input are the
+				<emphasis>--fqdn</emphasis> and
+				<emphasis>--repo</emphasis> flags.  The yaml
+				configuration can either be specified as another flag
+				or it can be piped to stdin.  If a
+				<emphasis>--virt-path</emphasis> is provided then a
+				<application>Koan</application> process will be
+				started. See the <emphasis>--help</emphasis> for more
+				information.
+			</para>
+
+			<screen>
+# genome-bootstrap advanced --help
+			</screen>
+
+			<note>
+				<title>Note</title>
+				<para>
+					The yaml fed to
+					<application>genome-bootstrap</application>
+					must be in the same format the Puppet expects
+					for its external nodes.  You must know exactly
+					which parameters are required for a given
+					&PRODUCT; machine.  The nice thing is that this
+					yaml can be obtained from <link
+						linkend="genome-Genomed">Genomed</link>.
+				</para>
+			</note>
+		</section>
+
+		<section>
+			<title>Bootstrap Parameters</title>
+			<para>
+				When using the
+				<application>genome-bootstrap</application> wizard the
+				user will be asked a series of questions.  The answers
+				are used as parameters for configuring &PRODUCT;
+				machines.  These parameters live server side and are
+				accessible via <link
+					linkend="genome-Genomed">Genomed</link>
+			</para>
+
+			<para>
+				The
+				nice thing about these parameters is that they can be used
+				anywhere a normal variable can be used in Puppet
+				manifests and templates. Some values are client
+				specific such as:
+				<itemizedlist>
+					<listitem>
+						<para>What cobbler server a node looks to for dependencies</para>
+					</listitem>
+					<listitem>
+						<para>What machines a particular apache will proxy</para>
+					</listitem>
+					<listitem>
+						<para>What server should be considered it's upstream git repo</para>
+					</listitem>
+				</itemizedlist>
+			</para>
+
+			<para>
+				Often you will want to change a parameter post bootstrap.
+				This is usually because you want to point your machine
+				at a different Puppetmaster or Cobbler server.  For
+				help on this process see <link
+					linkend="genome-ChangingAMachineParameter">the
+					cookbook</link>.
+			</para>
+		</section>
+
+		<section id="genome-PostBootstrapping">
+			<title>Post bootstrapping</title>
+			<para>
+				After successfully running
+				<application>genome-bootstrap</application> a
+				<application>Koan</application> process will be started
+				(that is, unless you specify
+				<emphasis>--config-only</emphasis>).  You can watch the
+				installation the same way you watch any Xen guest.  See
+				the <link linkend="genome-Tooling-Xen">Xen
+					documentation</link> for more details.
+			</para>
+
+			<para>
+				Once it's finished start the guest back up to allow the
+				<filename>/usr/sbin/genome-firstboot</filename> script
+				to run.  This behaves exactly like the normal firstboot
+				script on a Red Hat based system.
+			</para>
+
+			<note>
+				<title>Note</title>
+				<para>
+					See <link linkend="genome-LoggingIn">the
+						appendix</link> for information about
+					logging in to koan'ed machines.
+				</para>
+			</note>
+
+			<important>
+				<title>Important</title>
+				<para>
+					It's also possible to bootstrap a machine that
+					already has an OS.  See <link
+						linkend="genome-NoKoanBootstrap">the
+						cookbook</link> to see how this is
+					done.
+				</para>
+			</important>
+
+			<important>
+				<title>Important</title>
+				<para>
+					Consistent machine provisioning in the
+					&PRODUCT; is vital for efficient team
+					collaboration.  There should be no post
+					provisioning instructions needed to bring up a
+					working machine.  The proces for creating a
+					Jboss ESB machine should be the same as a node
+					on the Selenium grid.
+				</para>
+			</important>
+		</section>
+	</section>
+
+	<section id="genome-Genomed">
+		<title>genomed</title>
+		<para> 
+			The <application>genomed</application> service is a
+			simple web app that serves as the canonical source of
+			&PRODUCT; machine information used in compiling
+			<application>puppet</application> configurations.  It's
+			really quite simple so it's probably best explained by
+			simply showing the the a link: http://[your
+			repo hostname]/genome/nodes.html.  From there
+			it should be simple to browse find the other features
+			by exploration.
+		</para>
+
+		<para>
+			It's also worth noting that most of the resources (this
+			is a RESTful service) have several representations.
+			Try changing the urls to end with
+			<literal>xml</literal> or <literal>yaml</literal>.
+		</para>
+
+		<section id="genomed-configuration">
+			<title>Configuration</title>
+			<para>
+				<application>genomed</application> has two
+				configuration files.  One is located at
+				<filename>/etc/genomed/config.yml</filename>
+				and the other is at
+				<filename>/etc/genome/machine_types.rb</filename>.
+				The later of the two is the only one that
+				deserves special attention.  This file is a
+				traditional <emphasis>Domain Specific
+					Language</emphasis> that gets executed
+				by the <application>ruby</application>
+				interpreter.  A documented sample configuration
+				ships with the &REPORPM; which should be
+				sufficient to get up and running quickly.  If
+				changes are made to this file the
+				<application>genomed</application> must be
+				restarted.
+			</para>
+		</section>
+	</section>
+
+	<section id="genome-sync">
+		<title>genome-sync</title>
+		<para>
+			The goal of
+			<application>genome-sync</application> is to
+			make the process of syncronizing git
+			repositories from one &PRODUCT; Repo to another
+			as easy as possible.  The main mode
+			<emphasis>start</emphasis> guides the
+			user through the process. 
+		</para>
+
+		<para> 
+			In the <emphasis>start</emphasis> mode work
+			will be performed in a working directory.  The
+			app will then iterate over each repository,
+			asking the user what work to perform.  After
+			this process has completed the user can publish
+			their changes with the
+			<emphasis>save</emphasis> mode.
+		</para>
+
+		<section id="genome-sync-usage">
+			<title>Usage</title>
+			<para>
+				The following oneliners are in no particular order.
+				<screen>
+# Start the syncronization wizard
+genome-sync start --repo=[remote Repo machine]
+				</screen>
+
+				<screen>
+# Hard reset to a given repositories state (This is the fastest way to 
+# get up and running with a newly created repo machine).
+genome-sync start quick --repo=[remote Repo machine]
+				</screen>
+
+				<screen>
+# Push content where it needs to go.  If puppet modules are updated the
+# puppetmaster may need to be bounced.
+genome-sync save
+				</screen>
+
+				<screen>
+# Remove the working directory  
+genome-sync clean
+				</screen>
+
+			</para>
+			<important>
+				<title>Important</title>
+				<para>
+					<application>genome-sync</application>
+					must be run as the
+					<emphasis>genome</emphasis>
+					user.
+				</para>
+			</important>
+
+			<note>
+				<title>Note</title>
+				<para>
+					All
+					<application>genome-sync</application>
+					modes take the
+					<emphasis>--help</emphasis>,
+					<emphasis>--verbose</emphasis> and
+					<emphasis>--workingdir</emphasis>
+					flags.
+				</para>
+			</note>
+		</section>
+	</section>
+</chapter>