snaps-guide/src/installing.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="installation">
	<title>Installing @snaps.product.name@</title>
	
	<section id="installation-zip">
		<title>Installing from the Zip Download</title>
		<para>
			@snaps.product.name.short@ is distributed as a Zip file. This can be downloaded from 
			<ulink url="http://www.eclipse.org/virgo/download/">here</ulink>.
		</para>
		<para>
			Once the Zip file is unpacked you will find several things inside, including a copy of this documentation in the 
			<literal>docs</literal> folder. The layout is shown below.
		</para>
		<para>
			<imagedata fileref="images/snapsZipFile.png" align="center" width="12cm"/>
		</para>
		<para>
			Take the bundles and plan in the <literal>dist</literal> folder and place them in either the <literal>/repository/usr</literal> 
			or <literal>/repository/ext</literal> folder of your Virgo install. Later you need the bundles in the <literal>sample</literal> 
			folder. If you wish to view the source for @snaps.product.name.short@ or its sample, then these are in the <literal>src</literal> 
			folder.
		</para>
		<para>
			In order to start the Snaps system as a part of your @tomcat.product.name@, the Snaps plan needs to be referenced 
			from the <literal>initialArtifacts</literal> property. This is located in the config file at 
			<literal>${SERVER_HOME}/config/org.eclipse.virgo.kernel.userregion.properties</literal>. The property should be 
			extended like this.
		</para>
		<screen>initialArtifacts=repository:plan/org.eclipse.virgo.kernel.userregion.springdm, 
		repository:plan/org.eclipse.virgo.web.tomcat, 
		<emphasis>repository:plan/org.eclipse.virgo.snaps</emphasis></screen>
		<para>
			Now you are ready to check that Snaps is working.
		</para>
	</section>
	
	<section id="installation-post">
		<title>Verifying it's working</title>
		<para>
			The sample application in the Zip file demonstrates all of the features of Snaps. You will cover this application in 
			detail later, but for now install it to verify that you have a working Snaps install. Start the server up and check 
			the output it produces contains the following:
		</para>
		<screen>&#60;DE0004I&#62; Starting plan 'org.eclipse.virgo.snaps' version '3.0.0'. 
&#60;DE0004I&#62; Starting bundle 'org.eclipse.virgo.snaps.api' version '@bundle.version@'. 
&#60;DE0005I&#62; Started bundle 'org.eclipse.virgo.snaps.api' version '@bundle.version@'. 
&#60;DE0004I&#62; Starting bundle 'org.eclipse.virgo.snaps.core' version '@bundle.version@'. 
&#60;DE0005I&#62; Started bundle 'org.eclipse.virgo.snaps.core' version '@bundle.version@'. 
&#60;DE0005I&#62; Started plan 'org.eclipse.virgo.snaps' version '3.0.0'.</screen>
		<para>
			Open up the @project.name@ Admin Console by navigating to <literal>http://localhost:8080/admin</literal> and then go 
			to the artifacts tab to deploy some new bundles. The first bundle to deploy is located at 
			<literal>/sample/org.eclipse.virgo.snaps.sample.animal-@bundle.version@.jar</literal>, select it in the browser and 
			upload. In the terminal window you started the @tomcat.product.name@ in you should see the usual messages about the 
			bundle starting and this message:
		</para>
		<screen>&#60;SN0000I&#62; Host created for path '/animal-menu-bar'</screen>
		<para>
			This shows that the host has been registered and is ready for Snaps to attach to it. To view the application take 
			your browser to <literal>http://localhost:8080/animal-menu-bar/</literal>. You should be presented with a green looking 
			page that has a menu bar with two links on it. One will take you to the page you are currently on while the other goes 
			back to the admin page.
		</para>
		<para>
			This is all very nice, but it's time to deploy another snap that will dynamicaly add some extra content to the app. The next bundle
			to deploy is located at <literal>/sample/org.eclipse.virgo.snaps.sample.dog-@bundle.version@.jar</literal>. Deploy it the same way 
			as the last one using the admin console and check the messages to verify it has been bound to the host:
		</para>
		<screen>&#60;SN0010I&#62; Snap bound to path '/animal-menu-bar/dog' </screen>
		<para>
			In your browser, go back to the application and refresh the page and a new menu item should now be present. If you click it a new 
			page will load with content from the newly installed snap. In this case a picture of a dog.
		</para>
		<para>	
			<imagedata fileref="images/sampleDog.png"/>
		</para>
		<para>
			You have now verified that your install is working and can continue on to learn how Snaps works and how you can use it to break up 
			your web applications.
		</para>
	</section>
	
</chapter>