Author: benlc Date: 2010-04-12 04:02:10 -0400 (Mon, 12 Apr 2010) New Revision: 2583 Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Databases.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Getting_Started.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation_Guide.ent portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Post_Installation.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Test_Your_Installation.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/publican.cfg Log: 'committing revision following platform install and test' Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Configuration.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Configuration.xml 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Configuration.xml 2010-04-12 08:02:10 UTC (rev 2583) @@ -5,7 +5,7 @@ ]> <chapter> <title>Database Configuration</title> - + <section id="sect-Portal_EAP-Configuration-Installing_an_RDBMS_JDBC_connector"> <title>Installing an RDBMS JDBC connector</title> <para> @@ -22,7 +22,28 @@ Refer to the help files in each download for installation instructions. In most cases, the RDBMS JDBC connector comes as a <computeroutput>.jar</computeroutput> file. Copy this file into the <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/lib/</filename> directory. </para> </section> - + + &START_EDIT; + <section id="sect-Portal_EAP-Configuration-Installing_an_RDBMS_JDBC_connectorE"> + <title>Installing an RDBMS JDBC connector</title> + <para> + A relational database management system (RDBMS) Java Database Connectivity (JDBC) connector is required for &PRODUCT; to communicate with a database. + &PRODUCT; comes bundled with Hypersonic SQL (HSQL) database so that users can get up and running quickly without having to initially set up + a database. However, HSQL should not be used in a production environment. Removing HSQL is simply a matter of removing + <remark><filename>JBOSS_DIST/jboss-as/server/$CONFIG/deploy/hsql-ds.xml</filename>.</remark> + </para> + <para> + Test suites have been run against + the <trademark class="registered">Oracle</trademark> 9, <trademark class="registered">Oracle</trademark> 10, <trademark class="registered">Microsoft SQL Server</trademark>, + MySQL 4, MySQL 5, and PostgreSQL 8 databases - these databases are recommended for production use. Please refer to your database documentation for the correct + RDBMS JDBC connector to use. The MySQL RDBMS JDBC connector can be downloaded from <ulink url="http://www.mysql.com/products/connector/j/"></ulink>;, and the + PostgreSQL RDBMS JDBC connector can be downloaded from <ulink url="http://jdbc.postgresql.org/download.html"></ulink>;. + </para> + <para> + Refer to the help files in each download for installation instructions. In most cases, the RDBMS JDBC connector comes as a <computeroutput>.jar</computeroutput> file within the downloaded zip file. Copy this file into the <filename>$JBOSS_HOME/server/<replaceable>$CONFIG</replaceable>/lib/</filename> directory. + </para> + </section> + &END_EDIT; <section id="sect-Portal_EAP-Configuration-Datasource_Descriptors"> <title>Datasource Descriptors</title> <para> @@ -59,6 +80,71 @@ </screen> </para> </section> + + &START_EDIT; + <section id="sect-Portal_EAP-Configuration-Datasource_DescriptorsE"> + <title>Datasource Descriptors</title> + <para> + A Datasource descriptor is required for JBoss Portal to communicate with a database. Sample Datasource descriptor files are provided for the Hypersonic SQL, <trademark class="registered">Microsoft SQL Server</trademark>, MySQL, <trademark class="registered">Oracle</trademark>, and PostgreSQL databases. These can be found in the <remark><filename>$JBOSS_HOME/jboss-as/docs/examples/jca</filename></remark> directory. + </para> + <para> + The sample Datasource descriptors will work with default installations of external databases; however, you may need to configure the correct username and password. As indicated in the mysql-ds.xml file displayed below, the sample MySQL and PostgreSQL Datasource descriptors assume the name of the database to be <remark><computeroutput>jbossdb</computeroutput></remark>. + </para> + <para> + Copy the required Datasource descriptor file to <filename>$JBOSS_HOME/server/<replaceable>$CONFIG</replaceable>/deploy/</filename> directory. When copying a Datasource descriptor for MySQL, <trademark class="registered">Microsoft SQL Server</trademark>, PostgreSQL, or <trademark class="registered">Oracle</trademark> databases, change the <computeroutput>&lt;user-name&gt;<replaceable>portal</replaceable>&lt;/user-name&gt;</computeroutput> and <computeroutput>&lt;password&gt;<replaceable>portalpassword</replaceable>&lt;/password&gt;</computeroutput> sections to reflect the correct username and password of the user who has access to the jbossportal database. + </para> + <important> + <title>Different Datasource Descriptors</title> + <para> + Ensure that there is only one Datasource descriptor in the <filename>$JBOSS_HOME/server/<replaceable>$CONFIG</replaceable>/deploy/</filename> directory. For example, if you want to use a MySQL database, remove the <filename>hsqldb-ds.xml</filename> file, and other descriptors, if they exists. For a default configuration this will require removing the <filename>gatein-ds.xml</filename> and <filename>hsqldb-ds.xml</filename> files. + </para> + </important> + <para> + The following is an example Datasource descriptor file for MySQL 5: + </para> + <para> +<screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;!-- See http://www.jboss.org/community/wiki/Multiple1PC for information about local-tx-datasource --&gt; +&lt;!-- $Id: mysql-ds.xml 88948 2009-05-15 14:09:08Z jesper.pedersen $ --&gt; +&lt;!-- Datasource config for MySQL using 3.0.9 available from: + http://www.mysql.com/downloads/api-jdbc-stable.html +--&gt; + +&lt;datasources&gt; + &lt;local-tx-datasource&gt; + &lt;jndi-name&gt;MySqlDS&lt;/jndi-name&gt; + &lt;connection-url&gt;jdbc:mysql://mysql-hostname:3306/jbossdb&lt;/connection-url&gt; + &lt;driver-class&gt;com.mysql.jdbc.Driver&lt;/driver-class&gt; + &lt;user-name&gt;x&lt;/user-name&gt; + &lt;password&gt;y&lt;/password&gt; + &lt;exception-sorter-class-name&gt; + org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter + &lt;/exception-sorter-class-name&gt; + &lt;!-- should only be used on drivers after 3.22.1 with "ping" support + &lt;valid-connection-checker-class-name&gt; + org.jboss.resource.adapter.jdbc.vendor.MySQLValidConnectionChecker + &lt;/valid-connection-checker-class-name&gt; + --&gt; + &lt;!-- sql to call when connection is created + &lt;new-connection-sql&gt;some arbitrary sql&lt;/new-connection-sql&gt; + --&gt; + &lt;!-- sql to call on an existing pooled connection when it is obtained from pool - + MySQLValidConnectionChecker is preferred for newer drivers + &lt;check-valid-connection-sql&gt; + some arbitrary sql + &lt;/check-valid-connection-sql&gt; + --&gt; + + &lt;!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) --&gt; + &lt;metadata&gt; + &lt;type-mapping&gt;mySQL&lt;/type-mapping&gt; + &lt;/metadata&gt; + &lt;/local-tx-datasource&gt; +&lt;/datasources&gt;</screen> + </para> + </section> + &END_EDIT; + </chapter> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Databases.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Databases.xml 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Databases.xml 2010-04-12 08:02:10 UTC (rev 2583) @@ -36,6 +36,29 @@ </para> </listitem> </orderedlist> + + &START_EDIT; + + <orderedlist> + <listitem> + <para> + Navigate to the <ulink url="http://dev.mysql.com/downloads/connector/j/3.1.html">JDBC MySQL connector</ulink> section of dev.mysql.com. Download the <computeroutput>Compressed Tar Archive (.tar.gz)</computeroutput> file or the <computeroutput>Zip Archive (.zip)</computeroutput> file. + </para> + </listitem> + <listitem> + <para> + Unzip the <filename>mysql-java-connector</filename> into the desired directory. It does not matter which directory is used. + </para> + </listitem> + <listitem> + <para> + Change into the directory to which the <filename>mysql-java-connector</filename> was extracted. Copy the <filename>mysql-connector-java-<replaceable>version-number</replaceable>-bin.jar</filename> file into the <filename>$JBOSS_HOME/server/<replaceable>$CONFIG</replaceable>/lib/</filename> directory. + </para> + </listitem> + </orderedlist> + + &END_EDIT; + <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-Data_Truncation_Errors"> <title>Data Truncation Errors</title> <para> @@ -50,6 +73,23 @@ <para> If you are running MySQL in strict mode, remove <computeroutput>STRICT_TRANS_TABLES</computeroutput> from the <computeroutput>sql-mode=</computeroutput> line, in the <filename>my.cnf</filename> file if you are running Linux, and from the <filename>my.cfg</filename> file if you are running <trademark class="registered">Windows</trademark>. For further information, please see <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=AvoidMySQL5DataTruncat...;. </para> + &START_EDIT; + + <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-Data_Truncation_ErrorsE"> + <title>Data Truncation Errors</title> + <para> + If you are running MySQL 5, data truncation errors such as the following may occur: + </para> + </formalpara> + <para> +<screen> +ERROR JDBCExceptionReporter Data truncation: Data too long for column &#39;jbp_viewrealemail&#39; at row 1 +</screen> + </para> + <para> + If you are running MySQL in strict mode, remove <computeroutput>STRICT_TRANS_TABLES</computeroutput> from the <quote><computeroutput>sql-mode =</computeroutput></quote> line of the relevant configuration file. For Linux, this is the <filename>my.cnf</filename> file. For <trademark class="registered">Windows</trademark>, edit the <filename>my.cfg</filename> file. For further information, please see <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=AvoidMySQL5DataTruncat...;. + </para> + &END_EDIT; <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-Creating_a_MySQL_Database"> <title>Creating a MySQL Database</title> <para> @@ -132,6 +172,98 @@ </para> </listitem> </orderedlist> + &START_EDIT; + <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-Creating_a_MySQL_DatabaseE"> + <title>Creating a MySQL Database</title> + <para> + If you have just installed MySQL, make sure the MySQL server is running, and then run the following command to set the root user password: + </para> + </formalpara> + <para> +<screen> +mysqladmin -u root password &#39;<replaceable>new-root-user-password</replaceable>&#39; +</screen> + </para> + <orderedlist> + <listitem> + <para> + Run the following command to log in to MySQL. Enter the root user password when prompted: + </para> + <para> +<screen> +mysql -u root -p +</screen> + </para> + </listitem> + <listitem> + <para> + Use the <command>CREATE DATABASE</command> command to create a new jbossportal database. Note: the rest of this guide, and configuration examples following here after, assume the database name to be jbossportal. If you change the database name, please change the name in all necessary configuration files: + </para> + <para> +<screen> +mysql&gt; CREATE DATABASE jbossportal; +</screen> + </para> + <para> + The output should be similar to the following: + </para> + <para> +<screen> +Query OK, 1 row affected (0.00 sec) +</screen> + </para> + <para> + At this point, the <command>SHOW DATABASES;</command> command should display the <command>jbossportal</command> database: + </para> + <para> +<screen> +mysql&gt; SHOW DATABASES; ++--------------------+ +| Database | ++--------------------+ +| information_schema | +| jbossportal | +| mysql | ++--------------------+ +3 rows in set (0.00 sec) +</screen> + </para> + <para> + It is safe to ignore the other databases. + </para> + </listitem> + <listitem> + <para> + Add a new user and give that user access to the jbossportal database. The following example adds a new user named <computeroutput>portal</computeroutput>, with the password <computeroutput>portalpassword</computeroutput>. It is recommended that you choose a different password to the one supplied here by changing <replaceable>portalpassword</replaceable> to some other password: + </para> + <screen>CREATE USER 'portal'@'localhost' IDENTIFIED BY 'portalpassword';</screen> + </listitem> + <listitem> + <para> + Grant the necessary privileges to the user: + </para> + <para> +<screen> +mysql&gt; GRANT ALL PRIVILEGES ON jbossportal.* TO &#39;<replaceable>portal</replaceable>&#39;@&#39;localhost&#39; +IDENTIFIED BY &#39;<replaceable>portalpassword</replaceable>&#39; WITH GRANT OPTION; +</screen> + </para> + <para> + The output should be similar to the following: + </para> + <para> +<screen> +Query OK, 0 rows affected (0.00 sec) +</screen> + </para> + <note><title>Note: Changed Password?</title> + <para> + If you changed the portal user&#39;s password, remember to also change the password in the MySQL Datasource descriptor. + </para> + </note> + </listitem> + </orderedlist> + &END_EDIT; <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-MySQL_Datasource_Descriptor"> <title>MySQL Datasource Descriptor</title> <para> @@ -150,6 +282,65 @@ </para> </listitem> </orderedlist> + &START_EDIT; + <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-MySQL_Datasource_DescriptorE"> + <title>MySQL Datasource Descriptor</title> + <para> + To install the MySQL Datasource descriptor: + </para> + </formalpara> + <orderedlist> + <listitem> + <para> + Copy the MySQL Datasource descriptor - <filename>$JBOSS_HOME/docs/examples/jca/mysql-ds.xml</filename> - into the <filename>$JBOSS_HOME/server/<replaceable>$CONFIG</replaceable>/deploy/</filename> directory. + </para> + </listitem> + <listitem> + <para> + Update the following lines in the Datasource descriptor to reflect the correct database, user-name and password respectively: + <itemizedlist> + <listitem> + <para> + <computeroutput>&lt;connection-url&gt;jdbc:mysql://mysql-hostname:3306/<replaceable>DATABASE</replaceable>&lt;/connection-url&gt;</computeroutput>; + <itemizedlist> + <listitem> + <para> + In this example the database name is <literal>jbossportal</literal>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <computeroutput>&lt;user-name&gt;<replaceable>USER-NAME</replaceable>&lt;/user-name&gt;</computeroutput>; + <itemizedlist> + <listitem> + <para> + The user-name for this example is <literal>portal</literal>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <computeroutput>&lt;password&gt;<replaceable>PASSWORD</replaceable>&lt;/password&gt;</computeroutput>; + <itemizedlist> + <listitem> + <para> + This example uses the <literal>portalpassword</literal> password. Enter this or the password chosen at <xref linkend="form-Portal_EAP-Using_a_MySQL_Database-Creating_a_MySQL_DatabaseE"></xref>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </orderedlist> + &END_EDIT; + <formalpara id="form-Portal_EAP-Using_a_MySQL_Database-MySQL_Table_Errors"> <title>MySQL Table Errors</title> <para> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Getting_Started.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Getting_Started.xml 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Getting_Started.xml 2010-04-12 08:02:10 UTC (rev 2583) @@ -243,6 +243,14 @@ <title>Configuring Your Java Environment</title> <para> You must have a working installation of <emphasis role="bold">JDK 1.5</emphasis> before you install &PRODUCT;. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 5.0 using RHN, on a generic Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM. + </para> + &START_EDIT; + + <para> + You must have a working installation of <emphasis role="bold">JDK 1.6</emphasis> before you install &PRODUCT;. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 6.0 using RHN, on a generic Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM. + </para> + &END_EDIT; + <itemizedlist id="Configuring_Your_Java_Environment-Benefits_of_64_bit_JVM_on_64_bit_OS_and_Hardware"> <title>Benefits of 64-bit JVM on 64-bit OS and Hardware:</title> <listitem> @@ -315,6 +323,83 @@ </para> </listitem> </itemizedlist> + &START_EDIT; + <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_JDK_6.0_using_RHN"> + <title>Installing and Configuring JDK 6.0 using RHN</title> + <listitem> + <para> + Java SDKs are provided by the Red Hat Enterprise Linux 5 Base and Supplementary channels for your Linux variant and architecture. The available JDKs corresponding to each channel and architecture are listed below: + </para> + <para> + + </para> + <variablelist><title></title> + <varlistentry> + <term> + Channel: rhel-&lt;arch&gt;-server-5 + </term> + <listitem> + <para> + java-1.6.0-openjdk + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Channel: rhel-&lt;arch&gt;-server-supplementary-5 + </term> + <listitem> + <para> + java-1.6.0-sun (Sun) + </para> + + <para> + java-1.6.0-ibm (IBM) + </para> + + <para> + java-1.6.0-bea (JRockit) + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Ensure that the -devel packages are also installed. + </para> + </listitem> + + <listitem> + <para> + Selecting <command moreinfo="none">alternatives</command> for <command moreinfo="none">java</command>, <command moreinfo="none">javac</command> and <command moreinfo="none">java_sdk_1.6.0</command> (setting <command moreinfo="none">java_sdk_1.6.0</command> is optional). + </para> + + <para> + This is only needed if you want to use the SysV service script + and/or want this installed SDK to be the default java and javac + in the system. This choice can often be overridden by setting + the <command moreinfo="none">JAVA_HOME</command> environment variable. + </para> + + <para> + The <command moreinfo="none">alternatives</command> system allows different versions of Java, from different sources, to co-exist on your system. You should make sure the desired one is selected so that the service script uses the one you want. + </para> + + <para> + As root, issue the following command: + </para> + <screen> + <command moreinfo="none">/usr/sbin/alternatives --config java</command> + </screen> + <para> + and make sure the desired one is selected (marked with a '+'), or select it by entering its number as prompted. + </para> + + <para> + Make sure you do the same for <command moreinfo="none">javac</command> and <command moreinfo="none">java_sdk_1.6.0.</command> We recommend that all point to the same manufacturer and version. + </para> + </listitem> + </itemizedlist> + &END_EDIT; <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_a_generic_Linux_platform"> <title>Installing and Configuring 32-bit Sun JDK 5.0 on a generic Linux platform</title> <listitem> @@ -404,7 +489,128 @@ </para> </listitem> </itemizedlist> - <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Microsoft_Windows"> + &START_EDIT; + <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_JDK_6.0_on_a_generic_Linux_platform"> + <title>Installing and Configuring JDK 6.0 on a generic Linux platform</title> + <listitem> + <para> + Download the Java 2 Platform, Standard Edition (J2SE) Development Kit (JDK) 6.0 from Sun&#39;s website: <ulink url="http://java.sun.com/javase/downloads/index.jsp#need">&l...;. + </para> + </listitem> + <listitem> + <para> + From this page, select the latest update under the <literal>Java Platform, Standard Edition</literal> heading. Alternatively, this page can be accessed directly at <ulink url="http://java.sun.com/javase/downloads/widget/jdk6.jsp">&...;. + </para> + </listitem> + <listitem> + <para> + Follow the instructions presented on this page including selecting the appropriate platform and architecture. + </para> + </listitem> + <listitem> + <para> + Clicking the <guibutton>Continue</guibutton> button will display the download options (depending on whether the user chooses to register): + </para> + <itemizedlist> + <listitem> + <para> + jdk-6u&lt;update number&gt;-linux-&lt;arch&gt;-rpm.bin or; + </para> + </listitem> + <listitem> + <para> + jdk-6u&lt;update number&gt;-linux-&lt;arch&gt;.bin + </para> + </listitem> + </itemizedlist> + <para>If installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, it is recommended that the self-extracting file containing the RPM package is selected. This option will set up and use the SysV service scripts in addition to installing the JDK. The RPM option is also recommended if the &PRODUCT; is being set up in a production environment. Should you decide not to use the self-extracting file, the next step can be ignored. + </para> + </listitem> + <listitem> + <para> + Download and install the appropriate <literal>-compat RPM</literal> from <literal>JPackage</literal> <ulink url="ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-f... here</ulink>. Please ensure you choose a matching version of the <literal>-compat</literal> package to the JDK you installed. + </para> + &START_NOTE; + <para> + The latest JDK available from Sun's site is update 19. The jpackage site linked to above lists the latest <literal>-compat rpm</literal> at update 6 (java-1.6.0-sun-compat-1.6.0.06-1jpp.i586.rpm). So there is a conflict here as the downloaded package and the -compat rpm cannot be matched as stated above. + </para> + &END_NOTE; + </listitem> + <listitem> + <para> + Create an environment variable that points to the JDK installation directory and call it <literal>JAVA_HOME</literal>. Add <literal>$JAVA_HOME/bin</literal> to the system path to be able to run <literal>java</literal> from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory. <programlisting> +#In this example /usr/java/jdk1.6.0_19 is the JDK installation directory. +export JAVA_HOME=/usr/java/jdk1.6.0_19 +export PATH=$PATH:$JAVA_HOME/bin +</programlisting> + Set this variable for the user account performing the installation and also for the user account that will run the server. + </para> + </listitem> + <listitem> + <para> + If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.6 installation as the default <literal>java</literal> and <literal>javac</literal>. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system. + <note> + <para> + Selecting alternatives as decribed below can be avoided by setting the <literal>JAVA_HOME</literal> environment variable as explained in the previous step. + </para> + </note> + <itemizedlist> + <title>Select alternatives for java, javac and java_sdk_1.6.0</title> + + <listitem> + <para> + As root, type the following command at the shell prompt and you should see something like this: <programlisting> +[root@vsr ~]$ /usr/sbin/alternatives --config java +There are 2 programs which provide &#39;java&#39;. +Selection Command +----------------------------------------------- + 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java +*+ 2 /usr/lib/jvm/jre-1.6.0-sun/bin/java +Enter to keep the current selection[+], or type selection number: +</programlisting> + Make sure the Sun version [<literal>jre-1.6.0-sun</literal> in this case] is selected (marked with a &#39;+&#39; in the output), or select it by entering its number as prompted. + </para> + </listitem> + <listitem> + <para> + Repeat the same for javac and java_sdk_1.6.0. <programlisting> +[root@vsr ~]$ /usr/sbin/alternatives --config javac +There are 1 programs which provide &#39;javac&#39;. + Selection Command +----------------------------------------------- +*+ 1 /usr/lib/jvm/java-1.6.0-sun/bin/javac +Enter to keep the current selection[+], or type selection number: +</programlisting> +<programlisting> +[root@vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.6.0 +There are 1 programs which provide &#39;java_sdk_1.6.0&#39;. + Selection Command +----------------------------------------------- +*+ 1 /usr/lib/jvm/java-1.6.0-sun +Enter to keep the current selection[+], or type selection number: +</programlisting> + You should verify that java, javac and java_sdk_1.6.0 all point to the same manufacturer and version. + &START_NOTE; + Better to use java-1.6.0-variant rather than java-1.6.0-sun as could be sun or openjdk. Also include openJDK download site info http://openjdk.java.net/install/ ? + &END_NOTE; + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + Make sure that the <literal>java</literal> executable is in your path and that you are using an appropriate version. To verify your Java environment, type <literal>java -version</literal> at the shell prompt and you should see something like this: <programlisting> +[root@vsr ~]$ java -version +java version "1.6.0_19" +Java(TM) SE Runtime Environment (build 1.6.0_19-b01) +Java HotSpot(TM) Server VM (build 14.2-b01, mixed mode) +</programlisting> + </para> + </listitem> + </itemizedlist> + &END_EDIT; + <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Microsoft_Windows"> <title>Installing and Configuring 32-bit Sun JDK 5.0 on Microsoft Windows</title> <listitem> <para> @@ -417,7 +623,70 @@ </para> </listitem> </itemizedlist> - </para> + &START_EDIT; + <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_JDK_6.0_on_Microsoft_Windows"> + <title>Installing and Configuring JDK 6.0 on Microsoft Windows</title> + <listitem> + <para> + Download the Java 2 Platform, Standard Edition (J2SE) Development Kit (JDK) 6.0 from Sun&#39;s website: <ulink url="http://java.sun.com/javase/downloads/index.jsp#need">&l...;. + </para> + </listitem> + <listitem> + <para> + From this page, select the latest update under the <literal>Java Platform, Standard Edition</literal> heading. Alternatively, this page can be accessed directly at <ulink url="http://java.sun.com/javase/downloads/widget/jdk6.jsp">&...;. + </para> + </listitem> + <listitem> + <para> + Follow the instructions presented on this page including selecting the appropriate platform and architecture. + </para> + </listitem> + <listitem> + <para> + Clicking the <guibutton>Continue</guibutton> button will display the download option (depending on whether the user chooses to register): + </para> + <itemizedlist> + <listitem> + <para> + jdk-6u&lt;update number&gt;-windows-&lt;arch&gt;.exe + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + Create an environment variable called <literal>JAVA_HOME</literal> that points to the JDK installation directory, for example: <literal>C:\Program Files\Java\jdk1.6.0_19\</literal>. + </para> + </listitem> + <listitem> + <para> + In order to run java from the command line add the <literal>jre\bin</literal> directory to your path, for example: <literal>C:\Program Files\Java\jdk1.6.0_19\jre\bin</literal>. To do this: + <orderedlist> + <listitem> + <para> + Open the Control Panel from the Start Menu, switching to Classic View if necessary. + </para> + </listitem> + <listitem> + <para> + Open the System Control Panel applet. + </para> + </listitem> + <listitem> + <para> + Select the Advanced Tab + </para> + </listitem> + <listitem> + <para> + Click on the Environment Variables button. + </para> + </listitem> + </orderedlist> + </para> + </listitem> + </itemizedlist> + &END_EDIT; </section> </section> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation.xml 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation.xml 2010-04-12 08:02:10 UTC (rev 2583) @@ -39,6 +39,31 @@ </para> </section> + &START_EDIT; + <section id="InstallingE"> + <title>Installing</title> + + <para> + To install from a zip file, simply unzip the downloaded file to a directory of your choice. You can unzip the platform on any operating system that supports the zip format. Six types of server configurations will be included in your installation - minimal, default, production, all, standard and web. + The Getting Started Guide of &JBEAP; as well as http://www.jboss.org/community/docs/DOC-12942 explain in detail the different server configuration file sets. + + <itemizedlist> + <listitem> + <para> + Unzip <literal>jboss-epp-<replaceable>&lt;release&gt;</replaceable>.zip</literal> to extract the archive contents into the location of your choice. You can do this using the JDK <literal>jar</literal> tool (or any other ZIP extraction tool). <programlisting> + [vsr]$ <literal>cd jbeppinstallationdir</literal> + [vsr]$ <literal>jar -xvf jboss-epp-<replaceable>&lt;release&gt;</replaceable>.zip</literal></programlisting> + </para> + </listitem> + <listitem> + <para> + You are done with the installation! You should now have a directory called <filename>jboss-epp-<replaceable>&lt;release&gt;</replaceable></filename>. Refer to the Getting Started Guide to understand and explore the Platform Directory Structure. + </para> + </listitem> + </itemizedlist> + </para> + </section> + &END_EDIT; <section id="server-config-differences"> <title>Choosing a server configuration</title> <para> @@ -74,5 +99,47 @@ </itemizedlist> </para> </section> + &START_EDIT; + + <section id="server-config-differencesE"> + <title>Choosing a server configuration</title> + <para> + The important differences as far as Portal is concerned are: + + <itemizedlist> + <listitem> + <para> + the <literal>minimal</literal>, <literal>web</literal> and <literal>standard</literal> server configurations do not contain any Portal relevant components. These directories exist for the sake of consistency with &JBEAP; + </para> + </listitem> + <listitem> + <para> + the <literal>default</literal> server configuration includes non-clustered Portal components contained within the <remark><literal>httpha-invoker.sar</literal> OR <literal>jbossweb.sar</literal> OR <literal>jbossws.sar</literal> OR <literal>uuid-key-generator.sar</literal></remark> service archive. This archive is located in the <literal>deploy</literal> folder. <remark>This is the server configuration that is started when no other configuration is specified</remark> + </para> + </listitem> + <listitem> + <para> + the <literal>all</literal> server configuration includes clustered Portal components contained within <remark><literal>httpha-invoker.sar</literal> OR <literal>jbossweb.sar</literal> OR <literal>jbossws.sar</literal> OR <literal>juddi-service.sar</literal> OR <literal>snmp-adaptor.sar</literal></remark> service archive. This archive is located in the <literal>deploy</literal> folder. + </para> + </listitem> + <listitem> + <para> + the <literal>production</literal> server configuration includes clustered Portal components contained within <remark><literal>httpha-invoker.sar</literal> OR <literal>jbossweb.sar</literal> OR <literal>jbossws.sar</literal> OR <literal>juddi-service.sar</literal> OR <literal>snmp-adaptor.sar</literal> OR <literal>uuid-key-generator.sar</literal>.</remark> This archive is located in the <literal>deploy</literal> folder. + </para> + </listitem> + </itemizedlist> + <note><title>Note: Production Server</title> + <para> + The <literal>production</literal> server configuration has several optimizations including logging and memory size. + If you do not need the clustered portal version and want to use this optimized server configuration, you simply need to copy the <remark> + <literal>WHICH FILE?</literal> file </remark> from <literal>default/deploy</literal> to <literal>production/deploy</literal>. Don't forget to + remove <remark><literal>WHICH FILE as jboss-portal-ha.sar doesn't exist?</literal> </remark> though. + </para> + </note> + </para> + </section> + + &END_EDIT; + </chapter> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation_Guide.ent =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation_Guide.ent 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Installation_Guide.ent 2010-04-12 08:02:10 UTC (rev 2583) @@ -5,3 +5,7 @@ <!ENTITY YEAR "2010"> <!ENTITY HOLDER "Red Hat, Inc"> <!ENTITY RHEL "Red Hat Enterprise Linux"> +<!ENTITY START_EDIT "<formalpara><title><remark>&lt;!-- Start Edit</remark></title><para></para></formalpara>"> +<!ENTITY END_EDIT "<formalpara><title><remark>End Edit --&gt;</remark></title><para></para></formalpara>"> +<!ENTITY START_NOTE "<formalpara><title><remark>&lt;!-- Start Note to Reviewer</remark></title><para></para></formalpara>"> +<!ENTITY END_NOTE "<formalpara><title><remark>End Note to Reviewer --&gt;</remark></title><para></para></formalpara>"> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Post_Installation.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Post_Installation.xml 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Post_Installation.xml 2010-04-12 08:02:10 UTC (rev 2583) @@ -32,6 +32,37 @@ </para> </formalpara> </section> + &START_EDIT; + <section id="Set_JBOSS_HOMEE"> + <title> + Set JBOSS_HOME Environment Variable + </title> + <para><remark>Minor edit changed 4.3 to 5.0 in path to installation directory.</remark></para> + <formalpara> + <title> + On a Linux Platform + </title> + <para> + Create an environment variable that points to the installation directory (<filename>JBOSS_DIST/jboss-as</filename>) and call it <literal>JBOSS_HOME</literal>. Add <literal>$JBOSS_HOME/bin</literal> to the system path to be able to run the server from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory. + <programlisting> +#In this example /home/user/jboss-epp-5.0/jboss-as is the installation directory. + export JBOSS_HOME=/home/user/jboss-epp-5.0/jboss-as + export PATH=$PATH:$JBOSS_HOME/bin + </programlisting> + Set this variable for the user account(s) that will run the server. + </para> + </formalpara> + <formalpara> + <title> + On Microsoft Windows + </title> + <para> + Create an environment variable called <literal>JBOSS_HOME</literal> that points to the installation directory, for example: C:\Program Files\jboss-epp-5.0\jboss-as\. In order to run the server from the command line add the <filename>bin</filename> directory to your path, for example: C:\Program Files\jboss-epp-5.0\jboss-as\bin. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button. + </para> + </formalpara> + </section> + &END_EDIT; + <section id="Adjust_Memory_Settings"> <title>Adjust memory settings</title> <para> @@ -44,6 +75,24 @@ </programlisting> </para> </section> + &START_EDIT; + + <section id="Adjust_Memory_SettingsE"> + <title>Adjust memory settings</title> + <para> + The default configuration for the server to start with, if no other configuration is specified, is the production configuration. It is recommended to run the example Seam applications that are included with the documentation using the production configuration. + </para> + <para> + To avoid memory issues, adjust the memory settings before deploying the applications. You can do this by updating <literal>JAVA_OPTS</literal> settings in the file <filename>JBOSS_DIST/jboss-as/bin/run.conf</filename> with these recommended values: +<programlisting> + -Xms1303m -Xmx1303m -XX:MaxPermSize=256m .... +</programlisting> + </para> + <para><remark>This is the default so the "adjust" statement is not correct. Should it be set higher than 256m?</remark></para> + </section> + + &END_EDIT; + <section id="Post-Installation"> <title> Post Installation Security Configuration @@ -99,8 +148,88 @@ </para> </formalpara> </section> + + &START_EDIT; + <section id="Post-InstallationE"> + <title> + Post Installation Security Configuration + </title> + <para> + When installed from the zip archive, authentication is required to access the majority of JBoss services, including administrative services. User accounts have not been set up to eliminate the possibility of default username/password based attacks. + </para> + <important><title>Default admin user configuration</title> + <para> + It is recommended that the admin=admin username and password configuration, which is commented out by default, not be used for a production server. The admin user is included as an example of the user/password definition format only. + </para> + </important> + + <formalpara><title>Set up the <literal>jmx-console</literal> users and roles</title> + <para> + Edit the <filename>jmx-console-users.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/conf/props/</filename> directory defining the username and password: + </para> + </formalpara> + <programlisting>user=password</programlisting> + <para> + Edit the <filename>jmx-console-roles.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/conf/props/</filename> directory to define the user's roles: + </para> + <programlisting>user=JBossAdmin,HttpInvoker</programlisting> + + <formalpara><title>Set up the <literal>admin-console</literal> users and roles</title> + <para> + Edit the <filename>web-console-users.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/</filename> directory: + </para> + </formalpara> + <programlisting>user=password</programlisting> + <para> + Edit the <filename>web-console-roles.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/</filename> directory: + </para> + <programlisting>user=JBossAdmin,HttpInvoker</programlisting> + <note><title>$JBOSS_HOME and $CONFIG</title> + <para> + <varname>$JBOSS_HOME</varname> is the <filename>jboss-as</filename> directory, a level above the bin directory. <varname>$CONFIG</varname> is the chosen server configuration - all, default, minimal production, standard or web. + </para> + </note> + <important> + <para> + Login credentials for the <literal>admin-console</literal> are the same as those used for the JMX console. + </para> + </important> + <formalpara> + <title>Set SuckerPassword for JBoss Messaging:</title> + <para> + JBoss Messaging makes internal connections between nodes in order to redistribute messages between clustered destinations. These connections are made with the user name of a special reserved user whose password is specified by this parameter <literal>SuckerPassword</literal> in the Server Peer configuration file: + <programlisting> + <remark>$JBOSS_HOME/server/$CONFIG/deploy/messaging/messaging-service.xml</remark> + </programlisting> + Where <literal>$JBOSS_HOME</literal> is the install directory and <literal>$CONFIG</literal> is the server configuration being used. + To avoid a security risk, you MUST specify the value of the attribute <literal>SuckerPassword</literal>, failing which the default value will be used. Any one who knows the default password will be able to gain access to any destinations on the server. The following fragment should be uncommented and modified: + <programlisting> + &lt;mbean code="org.jboss.jms.server.ServerPeer" + name="jboss.messaging:service=ServerPeer" + xmbean-dd="xmdesc/ServerPeer-xmbean.xml"&gt; + ... + ... + ... + ... + &lt;!-- The password used by the message sucker connections to create connections. + THIS SHOULD ALWAYS BE CHANGED AT INSTALL TIME TO SECURE SYSTEM --&gt; + &lt;attribute name="SuckerPassword"&gt;&lt;/attribute&gt; + ... + ... + ... + &lt;/mbean&gt; + </programlisting> + </para> + </formalpara> + <para><remark>edit $JBOSS_HOME/server/$CONFIG/deploy/messaging/messaging-jboss-beans.xml as well?</remark></para> + <para><remark><literal>&lt;property name="suckerPassword"&gt;CHANGE ME!!&lt;/property&gt;</literal></remark></para> + <para><remark><literal>Also can't see jmx console or admin-console in the interface so is section this relevant?</literal></remark></para> + </section> + + &END_EDIT; <section id="Disabling_Authentication"> <title>Disabling Authentication</title> + <para><remark>No changes here as all paths and files are the same</remark></para> <para> It is also possible to disable authentication on specific services. All specified paths in the sections below are relative to <literal>$JBOSS_HOME</literal>. </para> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Test_Your_Installation.xml =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Test_Your_Installation.xml 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/en-US/Test_Your_Installation.xml 2010-04-12 08:02:10 UTC (rev 2583) @@ -6,6 +6,7 @@ <chapter id="Test_your_Installation"> <title>Test your Installation</title> + <para> After you have installed the JBoss Enterprise Portal Platform, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. Make sure you have set the <literal>JBOSS_HOME</literal> envirnoment variables as explained in <ulink url="Post_Installation_Configuration"/>. To test your installation, move to <filename>JBOSS_DIST/jboss-as/bin</filename> directory and execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system. Your output should look like the following (accounting for installation directory differences) and contain no error or exception messages: </para> @@ -43,7 +44,76 @@ Note that there is no "Server Started" message shown at the console when the server is started using the <literal>production</literal> profile, which is the default profile used when no other is specified. This message may be observed in the <filename>server.log</filename> file located in the <filename>server/production/log</filename> subdirectory. </para> </note> + + &START_EDIT; <para> + After you have installed the JBoss Enterprise Portal Platform, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. Make sure you have set the <literal>JBOSS_HOME</literal> environment variables as explained in <ulink url="Post_Installation_Configuration"/>. + </para> + <para> + To test your installation: + <itemizedlist> + <listitem> + <para> + move to the <filename>$JBOSS_HOME/bin</filename> directory; + </para> + </listitem> + <listitem> + <para> + execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system; + <itemizedlist> + <listitem> + <para> + Ensure that you run the configuration corresponding to the <filename>$JBOSS_HOME/server/$CONFIG/</filename> which you chose to set up the database connection in <xref linkend="form-Portal_EAP-Using_a_MySQL_Database-Creating_a_MySQL_DatabaseE"></xref> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + <para> + The example below uses the production configuration. Your output should look like the following (accounting for installation directory differences) and should not contain any error or exception messages: + </para> +<programlisting> +[user@localhost bin]$ ./run.sh -c production +========================================================================= + + JBoss Bootstrap Environment + + JBOSS_HOME: /home/user/jboss-epp-5.0/jboss-as + + JAVA: /usr/java/jdk1.6.0_16/bin/java + + JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1303m -Xmx1303m -XX:MaxPermSize=256m + -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 + -Dsun.rmi.dgc.server.gcInterval=3600000 -Dsun.lang.ClassLoader.allowArraySyntax=true + -Dexo.conf.dir.name=gatein -Djava.net.preferIPv4Stack=true + + CLASSPATH: /home/user/jboss-epp-5.0/jboss-as/bin/run.jar/usr/java/jdk1.6.0_16/lib/tools.jar + +========================================================================= + +16:59:41,401 INFO [ServerImpl] Starting JBoss (Microcontainer)... +16:59:41,401 INFO [ServerImpl] Release ID: JBoss [EAP] 5.0.0.GA (build: SVNTag=JBPAPP_5_0_0_GA date=200910202128) +16:59:41,402 INFO [ServerImpl] Bootstrap URL: null +16:59:41,402 INFO [ServerImpl] Home Dir: /home/user/jboss-epp-5.0/jboss-as +16:59:41,402 INFO [ServerImpl] Home URL: file:/home/user/jboss-epp-5.0/jboss-as/ +16:59:41,402 INFO [ServerImpl] Library URL: file:/home/user/jboss-epp-5.0/jboss-as/lib/ +16:59:41,403 INFO [ServerImpl] Patch URL: null +16:59:41,403 INFO [ServerImpl] Common Base URL: file:/home/user/jboss-epp-5.0/jboss-as/common/ +16:59:41,404 INFO [ServerImpl] Common Library URL: file:/home/user/jboss-epp-5.0/jboss-as/common/lib/ +16:59:41,404 INFO [ServerImpl] Server Name: production +... +... +16:59:44,345 INFO [JMXKernel] Legacy JMX core initialized +</programlisting> + <note> + <para> + Note that there is no "Server Started" message shown at the console when the server is started using the <literal>production</literal> profile. This message may be observed in the <filename>server.log</filename> file located in the <filename>server/production/log</filename> subdirectory. + </para> + </note> + &END_EDIT; + <para> Now open <literal>http://localhost:8080/portal</literal> in your web browser. (Make sure you dont have anything else already on your machine using that port).<footnote><para> Note that on some machines, the name localhost won’t resolve properly and you should use the local loopback address 127.0.0.1 instead.</para></footnote> The contents of your page should look similar to this: <xref linkend="Test_your_Installation-Test_your_Installation" />. </para> @@ -60,5 +130,6 @@ <para> You are now ready to use the JBoss Enterprise Portal Platform. Refer to the User Guide and Reference Guide for more information about the platform layout and example applications showcasing JBoss Portal in action. </para> + </chapter> Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/publican.cfg =================================================================== --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/publican.cfg 2010-04-10 08:49:41 UTC (rev 2582) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Installation_Guide/publican.cfg 2010-04-12 08:02:10 UTC (rev 2583) @@ -6,4 +6,5 @@ type: Book brand: JBoss debug:1 +show_remarks:1