[jboss-cvs] jboss-docs/jbossas/install/en ...
Norman Richards
norman.richards at jboss.com
Mon Oct 16 13:21:58 EDT 2006
User: nrichards
Date: 06/10/16 13:21:58
Modified: jbossas/install/en master.xml
Log:
jems installer 1.2 updates
Revision Changes Path
1.3 +324 -93 jboss-docs/jbossas/install/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-docs/jbossas/install/en/master.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- master.xml 19 Sep 2006 18:31:38 -0000 1.2
+++ master.xml 16 Oct 2006 17:21:58 -0000 1.3
@@ -19,77 +19,167 @@
<preface>
<title>About this Guide</title>
- <para>JBoss, a J2EE 1.4 certified application server, is the most widely used open source application server on
- the market. The highly flexible and easy-to-use server architecture has made JBoss the ideal choice for
- users just starting out with J2EE, as well as senior architects looking for a customizable middleware
- platform. The ready availability of the source code allows you to debug the server, learn its inner workings
- and create customized versions for your personal or business use. This guide will show you how to download
- and install JBoss 4.0. You will learn how to start and stop your JBoss instance, and you will also learn
- about the directory structure and understand what the key services and configuration files are. </para>
+ <para>JBoss AS is an open source J2EE 1.4 certified application server. It is the most widely used application
+ server on the market. The highly flexible and easy-to-use server architecture has made JBoss AS the ideal
+ choice for users just starting out with J2EE, as well as senior architects looking for a customizable
+ middleware platform. The ready availability of the source code allows you to debug the server, learn its
+ inner workings and create customized versions for your personal or business use. This guide will show you
+ how to download and install JBoss AS 4.0. You will learn how to start and stop your JBoss instance, and you
+ will also learn about the directory structure and understand what the key services and configuration files
+ are. </para>
</preface>
<chapter id="install">
<title>Installing JBoss</title>
- <para>JBoss 4 requires either a Java 1.4 or Java 5 JVM (Java Virtual Machine) to run.
- Before installing the server, you need to check your system to make sure you have a working
- Java 1.4 or 1.5 installation.
-
- Java 1.5 is required to use the new simplified EJB3 technologies.
-
- </para>
-
- <para>The simplest
- way to check on your Java environment is to execute the <literal>java -version</literal> command to ensure
- that the <literal>java</literal> executable is in your path and that you are using an appropriate version:</para>
+ <para> Before installing the server, you need to check your system to make sure you have a suitable Java
+ installation. JBoss 4 requires either a Java 1.4 or Java 5 JVM (Java Virtual Machine) to run. Java 5 is
+ required to use the newer simplified EJB3 technologies. The choice of JVMs is yours otherwise, but we do
+ recommend considering the Java 5 JVM where possible to take advantage of the latest JVM performanace
+ improvements and monitoring capabilities. No matter what JVM is chosen, you should generally prefer the
+ latest stable versions and keep an eye on future bug fix releases for issues that might affect your
+ installation. </para>
+
+ <para>To verify your Java environment execute the <literal>java -version</literal> command. This will ensure
+ that the <literal>java</literal> executable is in your path and that you are using the intended Java
+ version. The following output shows a Java 5 (sometimes called Java 1.5) JVM. If you don't see the
+ appropriate version, check your JVM installation instructions.</para>
<programlisting>[tmp]$ java -version
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_02-56)
- Java HotSpot(TM) Client VM (build 1.5.0_02-36, mixed mode, sharing)</programlisting>
+Java HotSpot(TM) Client VM (build 1.5.0_02-36, mixed mode, sharing)</programlisting>
+
+ <para>JBoss AS is distributed as part of the Red Hat JBoss Media Kit. Recent JBoss releases are also available
+ (both in binary and source form) online from the JBoss AS downloads page, <ulink
+ url="http://labs.jboss.org/portal/jbossas/download/"/> and as part of the JEMS distribution, available
+ online at <ulink url="http://labs.jboss.com/portal/jemsinstaller/downloads"/>. </para>
- <para>The most recent release of JBoss is available from the JBoss downloads page, <ulink
- url="http://www.jboss.org/products/jbossas/downloads"/>. After you have downloaded the version you want
- to install, use the JDK <literal>jar</literal> tool (or any other ZIP extraction tool) to extract the
- <literal>jboss-4.0.4.zip</literal> archive contents into a location of your choice. It does not matter
- where on your system you install JBoss. Note, however, that installing JBoss into a directory that has a
- name that contains spaces causes problems in some situations with Sun-based VMs. This is caused by bugs with
- file URLs not correctly escaping the spaces in the resulting URL. The <literal>jboss-4.0.4.tgz</literal>
- archive is a gzipped tar file that requires a gnutar-compatible tar program that can handle the long
+
+ <para> JBoss is released in two forms. The first is a ZIP or tgz archive containing a base JBoss installation.
+ We'll talk about the ZIP version, as any system containing a Java installation will have the tools to
+ extract the archive. The gzipped tar file requires a gnutar-compatible tar program that can handle the long
pathnames in the archive. The default tar binaries on Solaris and OS X do not currently support the long
pathnames. </para>
- <para> JBoss also provides a GUI installer that can simplify the installation process. In addition to the basic
- installation, the installer allows you to select the which services are installed secure the JBoss
- management applications. Using a custom JBoss install created by the installer can greatly simplify the
+ <para> The standard JBoss 4.0.4 ZIP distribution will be named <literal>jboss-4.0.4.GA.zip</literal>. If service
+ pack releases may later become available, they will contain the <literal>SP</literal> designation,
+ <literal>jboss-4.0.4SP1.zip</literal> for example. You can use use the JDK <literal>jar</literal> tool
+ (or any other ZIP extraction tool) to extract the archive contents into a directory of your choice. It does
+ not matter where on your system you install JBoss. Note, however, that installing JBoss into a directory
+ that has a name that contains spaces causes problems on some platforms with Sun-based VMs. </para>
+
+
+ <para>The resulting JBoss installation is a raw installation containing all the JBoss AS services in a
+ completely unconfigured state. It is the quickest way to get a runnable JBoss instance, but the latter work
+ to configure the server can be quite intensive. JBoss now provides a GUI installer that can simplify the
+ installation process. In addition to the basic installation, the installer allows you to select the which
+ services are installed, ensuring all service dependencies are met, secure the installation and configure a
+ default datasource. Using a custom JBoss install created by the installer can greatly simplify the
installation and configuration of JBoss. </para>
+
+
<para>The installer can be run directly from a web browser using Java Web Start or can be downloaded as an
- executable JAR file named <literal>jboss-4.0.4-installer.jar</literal>. On many operating system, you can
- run executable JARs by double-clicking them. If your system doesn't support that, you can run the installer
- directly from the command line: </para>
- <programlisting>[tmp]$ java -jar jboss-4.0.4-installer.jar</programlisting>
+ executable JAR file. If you choose the Java Web Start option, you only need to click the Run Installer link
+ for the desired JBoss version on the downloads page. The Java Web Start installer is quick and easy.
+ However, options like command-line install will require manually downloading and running the installer
+ executable JAR. On many operating system, you can run executable JARs by double-clicking them. If your
+ system doesn't support that, you can run the installer directly from the command line: (The remainder of
+ this guide will assume the JEMS 1.2.0 installer, available from <ulink
+ url="http://labs.jboss.com/portal/jemsinstaller/downloads"/>) </para>
+ <programlisting>[tmp]$ java -jar jems-installer-1.2.0.jar</programlisting>
+
+
+
+ <para>When you launch the installer, you will be given the option to select the installer language as shown in
+ <xref linkend="install_lang_select"/>. This screen only selects the language that the installer will
+ display choices in and has no effect on the language used by JBoss or the applications deployed in JBoss. </para>
+
+ <figure id="install_lang_select">
+ <title>The installer language selection screen.</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_lang_select.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+
+ <!--
+ <figure id="install_welcome">
+ <title>YYY</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_welcome.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ -->
+
+ <para>After language selection, the installer will present a series of screens presenting the release notes and
+ asking you to accept the JBoss license. JBoss is completely open source and is released under the GNU LGPL
+ license. The license screen (shown in <xref linkend="install_license"/>) displays the full text of the LGPL
+ license. More information on why JBoss uses the LGPL license and the advantages the LGPL provides to JBoss
+ users can be found at <ulink url="http://www.jboss.com/company/licensing"
+ >http://www.jboss.com/company/licensing</ulink>. </para>
+ <!--
+ <figure id="install_release_notes">
+ <title>The release notes screen</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_release_notes.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ -->
+
+
+ <figure id="install_license">
+ <title>The license screen</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_license.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para> The installer will ask you for the directory you want to install JBoss into. This is shown in <xref
+ linkend="install_dir_select"/>. The installer does not write the installation directory into any of the
+ scripts or into any form of registery, so you will be free to move or rename the JBoss installation
+ directory after installation. On some platforms, installation directories that contains spaces can cause
+ problems, so we recommend sticking to simple directory names. </para>
+ <figure id="install_dir_select">
+ <title>Selecting the installation directory</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_dir_select.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para> When you launch the installer, you will be able to select the starting server configuration set, as shown
- in <xref linkend="ch1.installgroup.fig"/>.</para>
- <figure id="ch1.installgroup.fig">
- <title>The JBoss AS installer configuration set selection screen</title>
+ <para> After that you able to select the starting server configuration set, as shown in <xref
+ linkend="install_group_select"/>. </para>
+
+
+ <figure id="install_group_select">
+ <title>Selecting the installation group</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/installgroup.jpg"/>
+ <imagedata align="center" fileref="images/install_group_select.png"/>
</imageobject>
</mediaobject>
</figure>
+
<para>The starting configuration determine which sets of packages are available for installation. The following
table describes each of the configuration sets. </para>
- <table id="ch1.installgroup.table">
+ <table id="installgroup.table">
<title>The JBoss AS installer configuration sets</title>
<tgroup cols="3">
<colspec colname="c1" colnum="1" colwidth="2*"/>
@@ -103,14 +193,6 @@
</row>
</thead>
<tbody>
-
- <row>
- <entry>
- <literal>default</literal>
- </entry>
- <entry>A base J2EE 1.4 server profile.</entry>
- <entry/>
- </row>
<row>
<entry>
<literal>all</literal>
@@ -118,12 +200,13 @@
<entry>A full J2EE 1.4 server profile with enterprise extensions such as clustering and IIOP. </entry>
<entry/>
</row>
+
<row>
<entry>
- <literal>minimal</literal>
+ <literal>default</literal>
</entry>
- <entry>A minimal JMX microkernel</entry>
- <entry>This is not a J2EE 1.4 compatible configuration.</entry>
+ <entry>A base J2EE 1.4 server profile.</entry>
+ <entry/>
</row>
<row>
<entry>
@@ -141,7 +224,6 @@
<entry>An EJB3 profile supporting the full EJB3 specification with Tomcat and clustering.</entry>
<entry>This requires a Java 5 runtime and is not a J2EE 1.4 compatible configuration.</entry>
</row>
-
<row>
<entry>
<literal>jms</literal>
@@ -149,6 +231,26 @@
<entry>A JMS 1.1 server profile</entry>
<entry>This is not a J2EE 1.4 compatible configuration.</entry>
</row>
+
+
+ <row>
+ <entry>
+ <literal>minimal</literal>
+ </entry>
+ <entry>A minimal JMX microkernel</entry>
+ <entry>This is not a J2EE 1.4 compatible configuration.</entry>
+ </row>
+
+
+
+ <row>
+ <entry>
+ <literal>portal</literal>
+ </entry>
+ <entry>A JBoss Portal 2.4 profile</entry>
+ <entry>This is not a J2EE 1.4 compatible configuration.</entry>
+ </row>
+
<row>
<entry>
<literal>tomcat</literal>
@@ -163,64 +265,191 @@
- <para> After selecting the configuration set, you have the option to further customize the services installed,
- eliminating unneeded options. When choosing configuration sets, be aware that you can not add packages not
- in the configuration set. If you you wanted a simple web container (the tomcat configuration) that also had
- JMS support (the jms configuration), it would be necessary to go to a larger configuration, such as the
- default configuration, and remove the unwanted packages. <xref linkend="ch1.install.fig"/> shows the package
- selection screen.</para>
- <figure id="ch1.install.fig">
- <title>The JBoss installer package selection screen</title>
+
+ <para> After selecting the configuration set, you have the option to further customize the installation,
+ customizing the set of services installed. <xref linkend="install_package_select"/> shows the package
+ selection screen. The installer knows the dependencies between services and will not allow you to configure
+ services in an incompatible way. This is much easier than the trial and error approach of configuring
+ services by hand from a raw ZIP install. When choosing configuration sets, be aware that you can not add
+ packages that are not a part of the selected configuration set. If you you wanted a simple web container
+ (the tomcat configuration) that also had JMS support (the jms configuration), it would be necessary to go to
+ a larger configuration, such as the default configuration, and remove the unwanted packages. There are some
+ combinations of JEMS components that are not supported directly through the installer. </para>
+
+ <figure id="install_package_select">
+ <title>Selecting the packages to install</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/installer.jpg"/>
+ <imagedata align="center" fileref="images/install_package_select.png"/>
</imageobject>
</mediaobject>
</figure>
- <para>The following screen (<xref linkend="ch1.installconfig.fig"/>) allows for the customization of the server
+
+
+
+ <para>The following screen (<xref linkend="install_config_name"/>) allows for the customization of the server
configuration name. Unless you need to create multiple configurations, you should use a configuration name
- of <literal>default</literal>. Use of any other configuration requires you to start JBoss with the
+ of <literal>default</literal>. Using any other configuration name requires you to start JBoss with the
<literal>-c</literal> option to specify the configuration JBoss should use. </para>
- <figure id="ch1.installconfig.fig">
- <title>The JBoss installer configuration name screen</title>
+
+ <figure id="install_config_name">
+ <title>Name the configuration</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_config_name.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+
+
+ <para> Almost all applications require a datasource to connect to a backend database. JBoss provides an embedded
+ Hypersonic database along with a default datasource to connect applications to. Being able to run
+ applications out of the box makes JBoss very developer friendly. All projects will eventually need to move
+ to a more capable database, but most will choose to do so at the very beginning of the project. The
+ datasource configuration screen, shown in <xref linkend="install_datasource"/>, gives you the option to use
+ the default hypersonic datasource to configure a replacement datasource. </para>
+
+ <figure id="install_datasource">
+ <title>Configure the default datasource</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/installconfig.jpg"/>
+ <imagedata align="center" fileref="images/install_datasource.png"/>
</imageobject>
</mediaobject>
</figure>
- <para>The installer will then guide you through a few install customization screens. The first screen allows you
- to enable applications isolation, completely separating the classloading space of all applications.
- Application isolation can be helpful in some instances, but it comes with the cost of requiring slow
- pass-by-value semantics for passing data between applications. In most cases, it is preferable to use loader
- repositories to control the sharing of classes on an application-by-application basis rather than enabling
- isolation for the entire server. </para>
-
- <para> When installed from the tar/zip archive, all JBoss services are left in a developer-friendly state
- requiring no authentication to access most JBoss services, including administrative services. The installer
- gives you a chance to secure those services on the security screen, shown in <xref
- linkend="ch1.installsecurity.fig"/>. It is recommended that you click to enable security for all
- services and change the password from the default <literal>admin</literal>/<literal>admin</literal> values. </para>
+ <para>If you want to configure the datasource, choose the configure option and select the database type. You'll
+ then be given the opportunity to enter database connection information as shown in <xref
+ linkend="install_config_datasource"/>. </para>
- <figure id="ch1.installsecurity.fig">
- <title>The JBoss installer security configuration screen</title>
+
+
+ <figure id="install_config_datasource">
+ <title>Configure the default datasource</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/installsecurity.jpg"/>
+ <imagedata align="center" fileref="images/install_config_datasource.png"/>
</imageobject>
</mediaobject>
</figure>
+ <para> Note that when installing a datasource this way, you must place the correct JDBC driver JAR file the lib
+ directory of your server configuration. See <xref linkend="dirs"/> for more information about JBoss
+ directory structure. </para>
+
+ <para>The next screen allows you to enable applications isolation, completely separating the classloading space
+ of all applications. Application isolation can be helpful in some instances, but it comes with the cost of
+ requiring slow pass-by-value semantics for passing data between applications. In most cases, it is
+ preferable to use loader repositories to control the sharing of classes on an application-by-application
+ basis rather than enabling isolation for the entire server. </para>
+
+
+ <figure id="install_isolation">
+ <title>Configure application isolation</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_isolation.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+
+
+ <para> When installed from a raw archive, all JBoss services are left in a developer-friendly state requiring no
+ authentication to access most JBoss services, including administrative services. The installer gives you a
+ chance to secure those services on the security screen, shown in <xref linkend="install_security"/>. It is
+ recommended that you click to enable security for all services. You will be required to enter a password for
+ the admin user. We strongly recommend not using the default password, "admin". </para>
+
+
+
+ <figure id="install_security">
+ <title>JBoss security settings</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_security.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <!--
+ <figure id="install_confirm">
+ <title>The installation confirmation screen</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_confirm.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <figure id="install_progress">
+ <title>Installation progress</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_progress.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ -->
+
+
+ <para> The following screens will ask you to confirm your installation and then show you the installation
+ progress. When your installation is done, the completion screen (<xref linkend="install_done"/>) gives you
+ the option to save an installation script that can be used to recreate your installation configuration. The
+ installation script will be covered in <xref linkend="automated_install"/>
+ </para>
+
+ <figure id="install_done">
+ <title>The installation is completed</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/install_done.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Your JBoss installation can be found in the directory that you specified at the beginning of the install.
+ The installer image may contain different services than the archive distribution, depending on the type of
+ installation performed. However, the basic structure and layout of all JBoss instances are the same. The
+ JBoss directory structure will be explained in <xref linkend="dirs"/>. </para>
+ </chapter>
+
+ <chapter id="automated_install">
+ <title>Command-line installation</title>
+ <para> The GUI installer obviously requires a display to run. but many servers run in headless mode with no
+ graphical display options. In these cases, the installer can be run on a machine with a display, and the
+ resulting JBoss installation can be copied to the server machine. Another option for installing in these
+ environments is to use the commandline installation capabilities. The JBoss installer can be run from the
+ commandline installing either a base server profile or recreating a previous installation using the
+ installer script created during a previous installation. </para>
+
+ <para>When you want to install a specific configuration set, the installer can be run from the command line
+ using the -installGroup and installpath options: </para>
+
+ <programlisting>java -jar jems-installer-1.2.0.BETA2.jar -installGroup default installpath=/opt/jboss-4.0.4</programlisting>
+
+ <para>The -installGroup parameter is any valid installation group. Different JBoss installers install have
+ different options. The options for the JEMS 1.2 installer are shown in <xref linkend="installgroup.table"/>.
+ The installpath options specifies the directory you want to install JBoss into. If you do not specify the
+ installpath option, the installer defaults to a directory named jboss-install. </para>
+
+ <para> This type of installation provides no ability to specify specific specific packages or to use the
+ security and datasource configuration options. These options can be set when using an installer script.
+ Script generation requires running the actual GUI interface, but the generated script can be used from the
+ commandline. The last panel of the installer provides the option to save an installer script that preserves
+ all of the selections made in the installer. The installation can be run by passing the installation script
+ as a parameter to the installer. </para>
+
+ <programlisting>java -jar jems-installer-1.2.0.BETA2.jar installscript.xml</programlisting>
+
+ <para> The installation script is a simple XML file that can be safely editted if further customization is
+ needed. The most likely detail to change would be the installation directory. </para>
- <para> When you install from the installer, you get a smaller install image that is more tuned for your
- environment. However, the directory structure will be slightly different than when using the tar/zip
- archive. The examples in the book need to make use of many different configurations and will assume the
- complete install. Although use of the installer is recommended for normal JBoss use, you'll need to download
- the complete image to work through all the examples. </para>
</chapter>
<chapter id="dirs">
@@ -362,6 +591,8 @@
<para> The contents of the <literal>conf</literal> and <literal>deploy</literal> directories will be shown in
the following section. </para>
</chapter>
+
+
<chapter id="config-files">
<title>The Default Server Configuration File Set</title>
<para>The <literal>JBOSS_DIST/server</literal> directory contains one or more configuration file sets. The
@@ -406,8 +637,8 @@
</term>
<listitem>
<para>The <literal>jndi.properties</literal> file specifies the JNDI
- <literal>InitialContext</literal> properties that are used within the JBoss server when an
- <literal>InitialContext</literal> is created using the no-arg constructor.</para>
+ <literal>InitialContext</literal> properties that are used within theNS-MYC10 JBoss server when
+ an <literal>InitialContext</literal> is created using the no-arg constructor.</para>
</listitem>
</varlistentry>
<varlistentry>
More information about the jboss-cvs-commits
mailing list