user-guide/src/installing.xml - virgo/org.eclipse.virgo.documentation - Git at Google

 <?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 @tomcat.product.name@</title>
 	<section id="installation-prereqs">
 		<title>Prerequisites</title>
 		<para>
 			The @tomcat.product.name@, or @tomcat.product.name.short@ for short, requires Java SE 6 or later to be installed. Java is available from
 			<ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.
 		</para>
 		<para>
 			In case you are installing via a p2 director you'll need to get it. The easiest way is to download Eclipse from <ulink url="http://www.eclipse.org/downloads/">here</ulink>.
 			It has built-in p2 director and other p2 applications.
 		</para>
 	</section>
 	<section id="installation-zip">
 		<title>Installing from the ZIP Download</title>
 		<section>
 			<title>Downloading the ZIP file</title>
 			<para>
 				@tomcat.product.name@ is distributed as a ZIP file. This can be downloaded from
 				<ulink url="http://www.eclipse.org/virgo/download/">here</ulink>.
 			</para>
 		</section>
 		<section id="installation-zip-installing">
 			<title>Installing</title>
 			<section  id="installation-zip-installing-linux">
 				<title>Linux</title>
 				<para>
 					To install @tomcat.product.name@ on Linux, unzip the distribution package to the desired installation directory.
 					For example, to install into <literal>/opt</literal>:
 				</para>
 				<screen>prompt$ unzip virgo-web-server-@bundle.version@.zip -d /opt</screen>
 				<para>
 					This creates a directory called <literal>virgo-web-server-@bundle.version@</literal> under <literal>/opt</literal>.
 				</para>
 				<para>
 					@tomcat.product.name@ requires write access to the installation directory, in this case <literal>/opt/virgo-web-server-@bundle.version@</literal>.
 					Typically this means it must be run as the user that installed it, or the installation directory&rsquo;s ownership must be changed.
 				</para>
 			</section>
 			<section  id="installation-zip-installing-win">
 				<title>Microsoft Windows</title>
 				<para>
 					To install the @tomcat.product.name@ on Windows, unzip the distribution package to the desired installation directory.
 					You should use a zip application such as 7zip, not the built-in folder decompression.  Note that both Windows and
 					Java have some issues with long file names and file paths, so we recommend installing to the root directory of
 					your chosen drive.
 				</para>
 			</section>
 		</section>
 	</section>

 	<section id="installation-updatesite">
 		<title>Installing from an update site</title>
 		<section>
 			<title>The repository location</title>
 			<para>
 				Virgo has a single p2 repository that contains all Virgo distributions. The repository for version @bundle.version@ can be found <ulink url="@p2repo@">here</ulink>.
 				There is a repository for each released version.
 			</para>
 		</section>
 		<section>
 			<title>Using the p2 director</title>
 			<para>
 				As shown in <xref linkend="using-director"/> you can easily install @tomcat.product.name.short@ in a desired destination.
 				The only director argument that needs to be adjusted is <emphasis>-installIU</emphasis>.
 			</para>
 			<para>
 				For @tomcat.product.name.short@ the right value is <emphasis>tomcat-server.product</emphasis>.
 			</para>
 		</section>
 	</section>

 	<section id="installation-post">
 		<title>Post-installation steps</title>
 		<section id="installation-post-env">
 			<title>Set environment variable variables</title>
 			<section id="installation-post-env-java">
 				<title>JAVA_HOME</title>
 				<para>
 					@tomcat.product.name@ uses the <literal>JAVA_HOME</literal> environment variable to locate the <literal>java</literal>
 					executable. Configure this environment variable to point to the home directory of the Java 6 installation on your computer.
 				</para>
 			</section>
 			<section id="installation-post-env-server">
 				<title>SERVER_HOME</title>
 				<para>
 					As a convenience it is recommended that you create an environment variable that points
 					to the @tomcat.product.name@ installation directory. Note that the @tomcat.product.name@ does not require that
 					such an environment variable has been set. This variable may have any name of your
 					choosing. The @tomcat.product.name@&rsquo;s documentation assumes that the variable is named
 					<literal>SERVER_HOME</literal>.
 				</para>
 			</section>
 			<section id="installation-post-env-server-linux">
 				<title>Linux</title>
 				<para>
 					Edit the <literal>.profile</literal> file in your home directory to
 					add the <literal>SERVER_HOME</literal> and <literal>JAVA_HOME</literal> environment variables. For
 					example, if you installed into <literal>/opt</literal>:
 				</para>
 				<screen>export SERVER_HOME=/opt/virgo-web-server-@bundle.version@/
 export JAVA_HOME=/user/java/jdk1.6.0_17
 export PATH=$JAVA_HOME/bin:$PATH</screen>
 				<para>
 				To verify the setting of <literal>JAVA_HOME</literal>, issue the command <literal>$JAVA_HOME/bin/java -version</literal> from a new terminal window
 				and ensure that the command completes successfully and reports
 				a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
 				</para>
 			</section>
 			<section id="installation-post-env-server-win">
 				<title>Microsoft Windows</title>
 				<para>
 					This section shows how to add <literal>SERVER_HOME</literal> as a system variable on Windows.  Follow the same procedure to add or update the <literal>JAVA_HOME</literal> environment variable.
 				</para>
 				<para>
 					From the Start menu, open the Control Panel and double-click on &lsquo;System&rsquo;.
 				</para>
 				<para>
 					<imagedata fileref="images/system-props.png"/>
 				</para>
 				<para>
 					Click the &lsquo;Advanced&rsquo; tab and select &lsquo;Environment Variables&rsquo;. Next,
 					click the &lsquo;New&rsquo; button in the &lsquo;System Variables&rsquo; section.
 				</para>
 				<para>
 					<imagedata fileref="images/env-variables.png"/>
 				</para>
 				<para>
 					This will display the &lsquo;New System Variable&rsquo; window.  Enter
 					<literal>SERVER_HOME</literal> as the &lsquo;Variable name&rsquo; and
 					the installation directory as the &lsquo;Variable value&rsquo;. Click OK.
 				</para>
 				<para>
 					<imagedata fileref="images/system-variable.png"/>
 				</para>
 				<para>
 					To verify the setting of <literal>JAVA_HOME</literal>, issue the command <literal>"%JAVA_HOME%"\bin\java -version</literal> from
 					a new command prompt and ensure that the command completes successfully and reports
 					a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
 				</para>
 			</section>
 		</section>
 		<section id="installation-post-env-server-win-troubleshooting">
 			<title>Microsoft Windows - Troubleshooting Security Permissions</title>
 			<para>
 				When starting @tomcat.product.name@ on some variants of Windows you might encounter a problem with file permissions.
 				The error looks like this.
 			</para>
 			<screen>WARNING: jmxPermissions.vbs did not update the permissions of C:\virgo\configuration\org.eclipse.virgo.kernel.jmxremote.access.properties. Check the file has the correct permissions.</screen>
 			<para>
 				If @tomcat.product.name.short@ starts correctly (see <xref linkend="starting-stopping"/>) you can skip this section and carry on. However to secure your
 				installation you have to set correct permissions. To do so, go to the &lsquo;configuration&rsquo; directory of the installation
 				in Windows Explorer.
 			</para>
 			<para>
 				<imagedata fileref="images/install-windows-1-FileListing.png" />
 			</para>
 			<para>
 				Right click on the &lsquo;org.eclipse.virgo.kernel.jmxremote.access.properties&rsquo; file and view its properties,
 				then select the &lsquo;Security&rsquo; tab. Remove all groups and users from the list and select &lsquo;Apply&rsquo;.
 			</para>
 			<para>
 				<imagedata fileref="images/install-windows-2-SecuritySettings.png" />
 			</para>
 			<para>
 				Within the security page select the &lsquo;Advanced&rsquo; options. On the &lsquo;Owner&rsquo; tab, choose the owner
 				that you are trying to run the @tomcat.product.name.short@ as and select &lsquo;Apply&rsquo;.
 			</para>
 			<para>
 				<imagedata fileref="images/install-windows-3-AdvanceSettingsOwner.png" />
 			</para>
 			<para>
 				Once this is done select &lsquo;OK&rsquo; to return to the &lsquo;Security&rsquo; tab
 				and now add the owner to the list of groups and users that have permission to access the file.
 			</para>
 			<para>
 				<imagedata fileref="images/install-windows-4-AllSetReadAndExecute.png" />
 			</para>
 			<para>
 				Once all these steps are complete you can proceed to start the @tomcat.product.name.short@.
 			</para>
 			<screen>C:\dev\virgo-web-server-@bundle.version@>bin\startup.bat
 [2009-12-08 13:09:09.545] startup-tracker              &lt;KE0001I&gt; Kernel starting.</screen>
 		</section>
 	</section>
 </chapter>
	<?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 @tomcat.product.name@</title>
	<section id="installation-prereqs">
	<title>Prerequisites</title>
	<para>
	The @tomcat.product.name@, or @tomcat.product.name.short@ for short, requires Java SE 6 or later to be installed. Java is available from
	<ulink url="http://www.java.com/">http://www.java.com/</ulink> and elsewhere.
	</para>
	<para>
	In case you are installing via a p2 director you'll need to get it. The easiest way is to download Eclipse from <ulink url="http://www.eclipse.org/downloads/">here</ulink>.
	It has built-in p2 director and other p2 applications.
	</para>
	</section>
	<section id="installation-zip">
	<title>Installing from the ZIP Download</title>
	<section>
	<title>Downloading the ZIP file</title>
	<para>
	@tomcat.product.name@ is distributed as a ZIP file. This can be downloaded from
	<ulink url="http://www.eclipse.org/virgo/download/">here</ulink>.
	</para>
	</section>
	<section id="installation-zip-installing">
	<title>Installing</title>
	<section id="installation-zip-installing-linux">
	<title>Linux</title>
	<para>
	To install @tomcat.product.name@ on Linux, unzip the distribution package to the desired installation directory.
	For example, to install into <literal>/opt</literal>:
	</para>
	<screen>prompt$ unzip virgo-web-server-@bundle.version@.zip -d /opt</screen>
	<para>
	This creates a directory called <literal>virgo-web-server-@bundle.version@</literal> under <literal>/opt</literal>.
	</para>
	<para>
	@tomcat.product.name@ requires write access to the installation directory, in this case <literal>/opt/virgo-web-server-@bundle.version@</literal>.
	Typically this means it must be run as the user that installed it, or the installation directory’s ownership must be changed.
	</para>
	</section>
	<section id="installation-zip-installing-win">
	<title>Microsoft Windows</title>
	<para>
	To install the @tomcat.product.name@ on Windows, unzip the distribution package to the desired installation directory.
	You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and
	Java have some issues with long file names and file paths, so we recommend installing to the root directory of
	your chosen drive.
	</para>
	</section>
	</section>
	</section>

	<section id="installation-updatesite">
	<title>Installing from an update site</title>
	<section>
	<title>The repository location</title>
	<para>
	Virgo has a single p2 repository that contains all Virgo distributions. The repository for version @bundle.version@ can be found <ulink url="@p2repo@">here</ulink>.
	There is a repository for each released version.
	</para>
	</section>
	<section>
	<title>Using the p2 director</title>
	<para>
	As shown in <xref linkend="using-director"/> you can easily install @tomcat.product.name.short@ in a desired destination.
	The only director argument that needs to be adjusted is <emphasis>-installIU</emphasis>.
	</para>
	<para>
	For @tomcat.product.name.short@ the right value is <emphasis>tomcat-server.product</emphasis>.
	</para>
	</section>
	</section>

	<section id="installation-post">
	<title>Post-installation steps</title>
	<section id="installation-post-env">
	<title>Set environment variable variables</title>
	<section id="installation-post-env-java">
	<title>JAVA_HOME</title>
	<para>
	@tomcat.product.name@ uses the <literal>JAVA_HOME</literal> environment variable to locate the <literal>java</literal>
	executable. Configure this environment variable to point to the home directory of the Java 6 installation on your computer.
	</para>
	</section>
	<section id="installation-post-env-server">
	<title>SERVER_HOME</title>
	<para>
	As a convenience it is recommended that you create an environment variable that points
	to the @tomcat.product.name@ installation directory. Note that the @tomcat.product.name@ does not require that
	such an environment variable has been set. This variable may have any name of your
	choosing. The @tomcat.product.name@’s documentation assumes that the variable is named
	<literal>SERVER_HOME</literal>.
	</para>
	</section>
	<section id="installation-post-env-server-linux">
	<title>Linux</title>
	<para>
	Edit the <literal>.profile</literal> file in your home directory to
	add the <literal>SERVER_HOME</literal> and <literal>JAVA_HOME</literal> environment variables. For
	example, if you installed into <literal>/opt</literal>:
	</para>
	<screen>export SERVER_HOME=/opt/virgo-web-server-@bundle.version@/
	export JAVA_HOME=/user/java/jdk1.6.0_17
	export PATH=$JAVA_HOME/bin:$PATH</screen>
	<para>
	To verify the setting of <literal>JAVA_HOME</literal>, issue the command <literal>$JAVA_HOME/bin/java -version</literal> from a new terminal window
	and ensure that the command completes successfully and reports
	a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
	</para>
	</section>
	<section id="installation-post-env-server-win">
	<title>Microsoft Windows</title>
	<para>
	This section shows how to add <literal>SERVER_HOME</literal> as a system variable on Windows. Follow the same procedure to add or update the <literal>JAVA_HOME</literal> environment variable.
	</para>
	<para>
	From the Start menu, open the Control Panel and double-click on ‘System’.
	</para>
	<para>
	<imagedata fileref="images/system-props.png"/>
	</para>
	<para>
	Click the ‘Advanced’ tab and select ‘Environment Variables’. Next,
	click the ‘New’ button in the ‘System Variables’ section.
	</para>
	<para>
	<imagedata fileref="images/env-variables.png"/>
	</para>
	<para>
	This will display the ‘New System Variable’ window. Enter
	<literal>SERVER_HOME</literal> as the ‘Variable name’ and
	the installation directory as the ‘Variable value’. Click OK.
	</para>
	<para>
	<imagedata fileref="images/system-variable.png"/>
	</para>
	<para>
	To verify the setting of <literal>JAVA_HOME</literal>, issue the command <literal>"%JAVA_HOME%"\bin\java -version</literal> from
	a new command prompt and ensure that the command completes successfully and reports
	a Java version <literal>1.6.</literal><emphasis>x</emphasis> (denoting Java 6) or greater.
	</para>
	</section>
	</section>
	<section id="installation-post-env-server-win-troubleshooting">
	<title>Microsoft Windows - Troubleshooting Security Permissions</title>
	<para>
	When starting @tomcat.product.name@ on some variants of Windows you might encounter a problem with file permissions.
	The error looks like this.
	</para>
	<screen>WARNING: jmxPermissions.vbs did not update the permissions of C:\virgo\configuration\org.eclipse.virgo.kernel.jmxremote.access.properties. Check the file has the correct permissions.</screen>
	<para>
	If @tomcat.product.name.short@ starts correctly (see <xref linkend="starting-stopping"/>) you can skip this section and carry on. However to secure your
	installation you have to set correct permissions. To do so, go to the ‘configuration’ directory of the installation
	in Windows Explorer.
	</para>
	<para>
	<imagedata fileref="images/install-windows-1-FileListing.png" />
	</para>
	<para>
	Right click on the ‘org.eclipse.virgo.kernel.jmxremote.access.properties’ file and view its properties,
	then select the ‘Security’ tab. Remove all groups and users from the list and select ‘Apply’.
	</para>
	<para>
	<imagedata fileref="images/install-windows-2-SecuritySettings.png" />
	</para>
	<para>
	Within the security page select the ‘Advanced’ options. On the ‘Owner’ tab, choose the owner
	that you are trying to run the @tomcat.product.name.short@ as and select ‘Apply’.
	</para>
	<para>
	<imagedata fileref="images/install-windows-3-AdvanceSettingsOwner.png" />
	</para>
	<para>
	Once this is done select ‘OK’ to return to the ‘Security’ tab
	and now add the owner to the list of groups and users that have permission to access the file.
	</para>
	<para>
	<imagedata fileref="images/install-windows-4-AllSetReadAndExecute.png" />
	</para>
	<para>
	Once all these steps are complete you can proceed to start the @tomcat.product.name.short@.
	</para>
	<screen>C:\dev\virgo-web-server-@bundle.version@>bin\startup.bat
	[2009-12-08 13:09:09.545] startup-tracker <KE0001I> Kernel starting.</screen>
	</section>
	</section>
	</chapter>