diff options
Diffstat (limited to 'doc/book/src/java-broker/Java-Broker-Installation.xml')
| -rw-r--r-- | doc/book/src/java-broker/Java-Broker-Installation.xml | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/doc/book/src/java-broker/Java-Broker-Installation.xml b/doc/book/src/java-broker/Java-Broker-Installation.xml new file mode 100644 index 0000000000..218e39f578 --- /dev/null +++ b/doc/book/src/java-broker/Java-Broker-Installation.xml @@ -0,0 +1,185 @@ +<?xml version="1.0"?> +<!DOCTYPE entities [ +<!ENTITY % entities SYSTEM "commonEntities.xml"> +%entities; +]> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> + +<chapter id="Java-Broker-Installation"> + <title>Installation</title> + <section role="h2" id="Java-Broker-Installation-Introduction"> + <title>Introduction</title> + <para>This document describes how to install the Java Broker on both Windows and UNIX + platforms.</para> + </section> + <section role="h2" id="Java-Broker-Installation-Prerequistes"> + <title>Prerequisites</title> + <section role="h3" id="Java-Broker-Installation-Prerequistes-Java"> + <title>Java Platform</title> + <para> + The Java Broker is an 100% Java implementation and as such it can be used on any operating + system supporting Java 1.6 or higher. This includes Linux, Solaris, Mac OS X, and Windows XP/Vista/7/8.</para> + <para> + The broker has been tested with Java implementations from both Oracle and IBM. Whatever + platform you chose, it is recommended that you ensure it is patched with any critical updates made + available from the vendor. + </para> + <para> + Verify that your JVM is installed properly by following <link linkend="Java-Broker-Miscellaneous-JVM-Verification">these instructions.</link> + </para> + </section> + <section role="h3" id="Java-Broker-Installation-Prerequistes-Disk"> + <title>Disk</title> + <para>The Java Broker installation requires approximately 20MB of free disk space.</para> + <para>The Java Broker also requires a working directory. The working directory is used for + the message store, that is, the area of the file-system used to record persistent messages whilst they + are passing through the Broker. The working directory is also used for the default location of the log file. + The size of the working directory will depend on the how the Broker is used.</para> + <para>The performance of the file system hosting the work directory is key to the performance of Broker as + a whole. For best performance, choose a device that has low latency and one that is uncontended by other + applications.</para> + <para>Be aware that there are additional considerations if you are considering hosting the working directory on NFS. See + <xref linkend="Java-Broker-Stores"/> for further details.</para> + </section> + <section role="h3" id="Java-Broker-Installation-Prerequistes-Memory"> + <title>Memory</title> + <para>Qpid caches messages on the heap for performance reasons, so in general, the Broker will + benefit from as much heap as possible. However, on a 32bit JVM, the maximum addressable memory range + for a process is 4GB, after leaving space for the JVM's own use this will give a maximum heap size + of approximately ~3.7GB.</para> + </section> + <section role="h3" id="Java-Broker-Installation-Prerequistes-OperatingSystemAccount"> + <title>Operating System Account</title> + <para>Installation or operation of Qpid does <emphasis>not</emphasis> require a privileged account (i.e. root + on UNIX platforms or Administrator on Windows). However it is suggested that you use an dedicated account + (e.g. qpid) for the installation and operation of the Java Broker.</para> + </section> + </section> + + <section role="h2" id="Java-Broker-Installation-Download"> + <title>Download</title> + <section role="h3" id="Java-Broker-Installation-Download-Release"> + <title>Broker Release</title> + <para>You can download the latest qpid-java-broker-&qpidCurrentRelease;.tar.gz package from the <ulink + url="&qpidDownloadUrl;">Download Page</ulink>. + </para> + <para> It is recommended that you confirm the integrity of the download by verifying the PGP signature + matches that available on the site. Instrutions are given on the download page. + </para> + </section> + <section role="h3" id="Java-Broker-Installation-Download-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these + stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + </para> + </section> + </section> + + <section role="h2" id="Java-Broker-Installation-InstallationWindows"> + <title>Installation on Windows</title> + <para> + Firstly, verify that your JVM is installed properly by following + <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Windows">these instructions.</link> + </para> + <para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files. + It need not be the same location as the store used for the persistent messages or the log file (you will chose this + location later). For the remainder this example we will assumed that location c:\qpid has been chosen.</para> + <para>Now using WinZip<footnote><para>WinZip is a Registered Trademark of WinZip International LLC</para></footnote> (or similar) + extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para> + <para>The extraction of the Qpid package will have created a directory qpid-broker-&qpidCurrentRelease; within c:\qpid</para> + <screen>Volume in drive C has no label + + Directory of c:\qpid\qpid-broker-&qpidCurrentRelease; + +07/25/2012 11:22 PM . +09/30/2012 10:51 AM .. +09/30/2012 12:24 AM bin +08/21/2012 11:17 PM etc +07/25/2012 11:22 PM lib +07/20/2012 08:10 PM 65,925 LICENSE +07/20/2012 08:10 PM 3,858 NOTICE +07/20/2012 08:10 PM 1,346 README.txt + 3 File(s) 71,129 bytes + 5 Dir(s) 743,228,796,928 bytes free</screen> + <section role="h3" id="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK"> + <title>Setting the working directory</title> + <para>Qpid requires a work directory. This directory is used for the default location of the Qpid log + file and is used for the storage of persistent messages. The work directory can be set on the + command-line (for the lifetime of the command interpreter), but you will normally want to set + the environment variable permanently via the Advanced System Settings in the Control Panel.</para> + <screen>set QPID_WORK=S:\qpidwork</screen> + <para>If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it + on start-up.</para> + </section> + <section role="h3" id="Java-Broker-Installation-InstallationWindows-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these + stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + </para> + </section> + </section> + + <section role="h2" id="Java-Broker-Installation-InstallationUnix"> + <title>Installation on UNIX platforms</title> + <para> + Firstly, verify that your JVM is installed properly by following + <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Unix">these instructions.</link> + </para> + <para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files. + It need not be the same location as the store used for the persistent messages or the log file (you will chose this + location later). For the remainder this example we will assumed that location /usr/local/qpid has been chosen.</para> + <para>Extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para> + <programlisting>mkdir /usr/local/qpid +cd /usr/local/qpid +tar xvzf qpid-java-broker-&qpidCurrentRelease;.tar.gz></programlisting> + <para>The extraction of the Qpid package will have created a directory qpid-broker-x.x</para> + <screen>ls -la qpid-broker-&qpidCurrentRelease;/ +total 152 +drwxr-xr-x 8 qpid qpid 272 25 Jul 23:22 . +drwxr-xr-x 45 qpid qpid 1530 30 Sep 10:51 .. +-rw-r--r--@ 1 qpid qpid 65925 20 Jul 20:10 LICENSE +-rw-r--r--@ 1 qpid qpid 3858 20 Jul 20:10 NOTICE +-rw-r--r--@ 1 qpid qpid 1346 20 Jul 20:10 README.txt +drwxr-xr-x 10 qpid qpid 340 30 Sep 00:24 bin +drwxr-xr-x 9 qpid qpid 306 21 Aug 23:17 etc +drwxr-xr-x 34 qpid qpid 1156 25 Jul 23:22 lib + </screen> + <section role="h3" id="Java-Broker-Installation-InstallationUnix-SettingQPIDWORK"> + <title>Setting the working directory</title> + <para>Qpid requires a work directory. This directory is used for the default location of the Qpid log + file and is used for the storage of persistent messages. The work directory can be set on the + command-line (for the lifetime of the current shell), but you will normally want to set + the environment variable permanently the user's shell profile file (~/.bash_profile for Bash etc).</para> + <screen><![CDATA[export QPID_WORK=/var/qpidwork]]> + </screen> + <para>If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it + on start-up. + </para> + </section> + <section role="h3" id="Java-Broker-Installation-InstallationUnix-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these + stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + </para> + </section> + </section> +</chapter> |