Sun GlassFish Web Space Server 10.0 Administration Guide

Chapter 2 Web Space Server Installation Instructions

To install Web Space Server, download the single component installer (production bundle) for Sun GlassFish Web Space Server. The single component installer for Web Space Server is the version that is not bundled with Sun GlassFish Web Space Server and samples. The filename of the downloaded bundle for single component installer looks similar to webspace-10-fcs-for-gfv2.zip. You can configure it to a database installed on your disk. MySQL and Oracle 10g are the databases supported by Web Space Server. If your organization doesn't have a standard for local development databases, you can use MySQL.

Sun GlassFish Web Space Server 10.0 runs on GlassFish. Web Space Server is best suited to work on GlassFish v2, but it can also be installed on other versions of Sun GlassFish Web Space Server, and also on other application servers. It is a part of the GlassFish Portfolio. Support for Oracle WebLogic Server is added from Web Space Server 10.0 Update 6 release.

Unlike the evaluation bundle, which includes theGlassFish software and HSQL, the production bundle of Web Space Server can be installed only on an existing installation of an application server such as GlassFish.

The following sections provide instructions for using the production bundle for Web Space Server:

Installing the Database, Application Server, and Web Space Server

Perform the following procedure to configure Web Space Server on a Solaris system with UTF-8 support. For instructions about how to install MySQL on various other operating systems, see http://dev.mysql.com/doc/refman/5.1/en/installing.html.

Before You Begin

This section explains some basic requirements and concepts you should review before proceeding with Sun GlassFish Web Space Server 10.0 software installation.

System Requirements

See Software and Hardware Requirements in Sun GlassFish Web Space Server 10.0 Installation Guide for system requirements.

Installation Directories

Throughout these installation instructions, the root Web Space Server installation directory is referred to as <webspace_dir>.

When you unzip a core Web Space Server bundle (which looks similar to webspace-<version>-for-glassfish.zip), you get webspace-for-glassfish directory. You can install and configure Web Space Server from this directory. This directory is denoted by <webspace_dir>.

Platform-Specific Path Separators

The instructions and examples in this document use UNIX-style forward slash (/) path separators in file and command names. If Web Space Server and Sun GlassFish Enterprise Server are installed on a Windows system, be sure to use backslashes (\) instead of forward slashes; for example:

UNIX systems or Linux systems — glassfish/bin/asadmin
Windows systems — glassfish\bin\asadmin

To Install and Configure MySQL

Install MySQL by typing the following commands as superuser.

# groupadd mysql
# useradd -g mysql mysql
# cd /usr/local
# gunzip install-dir/mysql-version-os.tar.gz | tar xvf -
# ln -s install-dir/mysql-version-os mysql
# cd mysql
# chown -R mysql .
# chgrp -R mysql .
# scripts/mysql_install_db --user=mysql
# chown -R root .
# chown -R mysql data
# bin/mysqld_safe --user=mysql & *

Log in to the MySQL installation by going to the MySQL installation directory and typing the following command:

mysql -u root

Create the UTF-8 database by typing the following commands:

mysql> create database lportal default character set utf8
mysql> use lportal;
mysql> create user lportal;
mysql> grant all privileges on *.* to 'lportal'@'localhost' identified by 'lportal';
mysql> set password for 'lportal'@'localhost' = password('lportal');

Enable UTF-8 support for MySQL.

See, To Connect to a Database Other Than HSQL

To Install the GlassFish JAR Based Installer

Installing and starting GlassFish is a prerequisite for installing Web Space Server. The following procedure explains how to install the JAR based installer for GlassFish. The JAR based installer can be downloaded freely from the GlassFish server web site. You can use GlassFish V2 version and also the JAR based installer for GlassFish in case of desktop deployments of Web Space Server, which is used for development and testing of Web Space Server.

You can use the enterprise version of Web Space Server when you deploy Web Space Server in production environment. See, Installing Web Space Server on Sun GlassFish Enterprise Server 2.1.

Download the GlassFish v2 distribution at

https://glassfish.dev.java.net/downloads/v2.1-b60e.html

Set the environment variable JAVA_HOME to point to the directory in which JDK 1.6 is installed.

Run the following command:

#java -Xmx256m -jar filename.jar

Set ANT_HOME to point to the installation of Ant 1.7 or above.

Note –
Ant 1.6.5 is the default Ant version for GlassFish. Make sure that ANT_HOME is not pointing to GlassFish Ant.

Navigate to the GlassFish directory:

cd glassfish

Run the following command:

ant -f setup.xml

Start GlassFish.

cd bin

<downloaded-dir>/glassfish/bin>/asadmin start-domain

To Install Web Space Server

Download the stand-alone version of Web Space Server.

Extract the Web Space Server bundle.

unzip webspace-for-gfv2.zip

Navigate to the Application folder.

cd webspace-for-gfv2/webspace/application

Run ant -f install-gfv2.xml.

ant -f install-gfv2.xml
Buildfile: install-gfv2.xml

check-ant:

check-last-install:

set-last-install:

show-user-warning:
   [input] JAVA_HOME must be set to JDK 1.5 or greater and java must be availab
le in the execution path. GlassFish must be running. [RETURN to continue or CONT
ROL-C to stop]


set-glassfish-properties:
   [input] Enter GlassFish Directory  [\opt\glassfish]
<install-dir>\glassfish
   [input] Enter GlassFish Domain (include full path to domain)  [<install-dir>\glassfish\domains\domain1]

   [input] Enter GlassFish Target  [server]

   [input] Enter GlassFish Administrator [admin]

   [input] Enter GlassFish Administrator Password File (include full path to fi
le)  [full-path\gfpass.txt]

   [input] Enter GlassFish Administration Port  [4848]

   [input] Can installer deploy wars?  [true]


set-database-properties:
   [input] Use builtin HSQL or mySQL database  [HSQL]
mysql

set-hsql-properties:

set-mssql-properties:

set-mysql-properties:
   [input] Enter Database User Name  [root]

   [input] Enter Database User Password File (include full path to file)  [full-path\dbpass.txt]
//Place GlassFish admin password in a clear text file, and specify full path to it

   [input] Enter Database Host  [localhost]

   [input] Enter Database Port  [3306]

   [input] Enter Database Name  [lportal]

You need to set the application server and database properties in the process of running install-gfv2.xml. You have to specify path for a password file (a text file containing the password) for GlassFish. If MySQL is installed on your machine, stop GlassFish and choose MySQL instead of the HSQL database, and make changes to the portal-ext.properties file as described in the To Connect to a Database Other Than HSQL section. Provide a password file, and restart GlassFish. Provide properties such as hostname, port number, and database name. Make sure that Ant version is 1.7 or greater and JDK is 1.6 or greater. GlassFish need to be running if you are installing on HSQL.

To Connect to a Database Other Than HSQL

You need to make changes to the JDBC property in portal-ext.properties only when you are installing Web Space Server on GlassFish Enterprise Edition. It is not necessary to make these changes, when you are installing Web Space Server on the GlassFish JAR based installer.

Create a temporary folder. In this example, the folder is named test.

mkdir /tmp/test

Copy the portal-impl.jar file to the tmp folder.

The portal-impl.jar file contains resource bundles for Web Space Server.

cd GlassFish-install-dir/domains/domain1/application/j2ee-modules

cp webspace/WEB-INF/lib/portal-impl.jar /tmp/test

Change to the tmp directory.

cd /tmp/test

Extract the portal-impl.jar file.

jar -xvf portal-impl.jar

The portal.properties file will be placed in the tmp directory.

Open the portal.properties file and copy the JDBC property.

Create a text file named portal-ext.properties, and paste the JDBCproperty into it.

The Hypersonic (HSQL) and MySQL part of the JDBC property looks as below:

#
    # Hypersonic
    #
    jdbc.default.driverClassName=org.hsqldb.jdbcDriver
    jdbc.default.url=jdbc:hsqldb:lportal
    jdbc.default.username=sa
    jdbc.default.password=

    #
    # MySQL
    #
    #jdbc.default.driverClassName=com.mysql.jdbc.Driver
    #jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=
UTF-8&useFastDateParsing=false
    #jdbc.default.username=
    #jdbc.default.password=

Comment Hypersonic (HSQL) and uncomment MySQL.

Note –
Properties in the portal properties file are commented using the hash (#) symbol. A property can be commented by placing a hash symbol in front of it.

Save the portal-ext.properties file.

Create a directory structure webspace/WEB-INF/classes/ under ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace/customs, and copy portal-ext.properties file to it.

Change directory to ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace.

cd ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace

Run ant -f synchronize.xml.

Restart the GlassFish server.

The server will redeploy websynergy.war and update portal-ext.properties under applications/j2ee-modules/webspace/WEB-INF/classes.

UTF-8 Support for Oracle 10g or Later

When you configure Web Space Server for Oracle, the lportal database needs to be created with UTF-8 support.

CREATE DATABASE lportal    
   CHARACTER SET [AL32UTF8|UTF8]
   NATIONAL CHARACTER SET AL16UTF16

CHARACTER SET Clause

Type the character set, the database uses to store data. The supported character sets and default value of this parameter depends on your operating system.

Restriction on the CHARACTER SET

Note –

Do not specify the AL16UTF16 character set as the database character set.

Specify the national character set used to store data in columns specifically defined as NCHAR, NCLOB, or NVARCHAR2. Values allowed are AL16UTF16 and UTF8. The default value is AL16UTF16.

Also, refer to the Oracle Database Globalization Support Guide for information on Unicode data-type support. You can access this document at

http://download.oracle.com/docs/cd/B12037_01/server.101/b10749/toc.htm

Installing Updates from the Update Tool

Web Space Server updates and add-ons can be downloaded using the Sun GlassFish Update Tool.

Caution –

If the user is behind a proxy, and is upgrading from a early version of Web Space Server ( a version of Web Space Server which is earlier to Web Space Server 10.0 Update 5), the user need to use a workaround. For the instructions for using this workaround, see To Use updatetool in a Proxy That Requires Authentication.

First release of the product (Web Space Server 10.0) was bundled with Update Center 2.0 which was not supporting authenticated proxy setup. Sun GlassFish Web Space Server 10.0 Update 5 and later versions of Web Space Server are bundled with Update Center 2.2, with supports proxy authentication, and hence the workaround is not required.

Note –

The version of Update Tool included with some versions of GlassFish Enterprise Server is not compatible with the Web Space Server Add-On package repositories. You must use the version of Update Tool that comes with Web Space Server 10.0 software.

Update Tool also includes a command-line (CLI) Image Packaging System (IPS) utility, called pkg, which provides the same core functionality as its GUI-based counterpart. This IPS tool is started with the webspace_dir/bin/pkg command. See the Update Center wiki for complete information about Update Tool and the pkg command.

To Download the Updates Using Update Tool

Start Update Tool by changing to the webspace-dir/bin directory and typing updatetool.
- If the Update Tool main window appears, proceed to Step 2.
- If a prompt appears asking whether to allow the installation of Update Tool to proceed:
  1. Type y to proceed.
    
    The installer downloads and installs Update Tool and then exits. This process takes approximately 10 ‐ 15 minutes.
  2. Type the updatetool command again to start Update Tool.
    
    The Update Tool main window appears.

Expand Web Space under the Application Images pane, and click Available Updates.

Figure 2–1 Update Tool

Click the Edit Properties button.

The Image Properties window is displayed.

Select the option support.sun.com repository, and choose Preferred.

The Repository Properties window appears.

Provide the appropriate repository URL provided by Sun support, and click OK.

The support.sun.com repository is highlighted.

Figure 2–2 Selecting the support.sun.com repository

Click OK again to enable the support.sun.com repository.

The Update Tool main window is displayed.

Expand Web Space under the Application Images pane, and select Available Add-ons.

Select the Web Space for GlassFish V2 component, and click install.

Restart the GlassFish server.

cd <glassfish_dir>/bin
./asadmin stop-domain
./asadmin start-domain

Change to the webspace_dir/webspace/application directory.

Run the ant install-gfv2.xml script to regenerate and redeploy the Web Space Server WAR files.
```
ant -f install-gfv2.xml
```

Restart the GlassFish server.

cd <glassfish_dir>/bin
./asadmin start-domain

To Download the Updates Using the CLI-Based pkg Tool

Start Update Tool by changing to the webspace-dir/bin directory and typing updatetool.
- If the Update Tool main window appears, proceed to Step 2.
- If a prompt appears asking whether to allow the installation of Update Tool to proceed:
  1. Type y to proceed.
    
    The installer downloads and installs Update Tool and then exits. This process takes approximately 10 ‐ 15 minutes.
  2. Type the updatetool command again to start Update Tool.
    
    The Update Tool main window appears.

Change to the webspace_dir/pkg/bin directory.

Type the following command to download updates:

pkg set-authority -P --enable -O http://pkg.sun.com/webspace/10/ repository-name

Ask your SunSolve service representative for the correct repository name to use.

Type the following commands to install the Update components.
```
pkg image-update
```

Restart the GlassFish server.

cd <glassfish_dir>/bin
./asadmin stop-domain
./asadmin start-domain

Change to the webspace_dir/webspace/application directory.

Run the ant install-gfv2.xml script to regenerate and redeploy the Web Space Server WAR files.
```
ant -f install-gfv2.xml
```

Restart the GlassFish server.

cd <glassfish_dir>/bin
./asadmin start-domain

To Use `updatetool` in a Proxy That Requires Authentication

This is a workaround to install Web Space Server from behind a proxy, when you are updating from a early version of Web Space Server. Sun GlassFish Web Space Server 10.0 Update 5 and later versions of Web Space Server are bundled with Update Center 2.2 which supports proxy authentication, and this workaround is not required.

Download Update Center 2.2 suitable for your platform from Update Center Wiki.

Unzip the Update Center 2.2 to a temporary directory (i.e. /tmp/uc2.2)

Copy the files pkg-bootstrap.jar and pkg-client.jar from /tmp/uc2.2/pkg-toolkit-sunos-i386/pkg/lib to <webspace_dir>/webspace-for-gfv2/pkg/lib.

Navigate to <webspace_dir>/webspace-for-gfv2/bin, and run updatetool.

You are prompted to type the proxy info and proxy port.

Type the proxy info and proxy port information.

The latest version of the updatetool and pkg files is downloaded.

Run updatetool again to download Web Space Server packages.

Installing Samples

This section provides the instructions to install samples, which is a bundle of sample communities, users, and some portlets which are not yet officially supported by Sun. Customers can use samples, depending upon their need and interest.

To Install Samples

Download the zip file for add-ons and copy it to the Web Space Server installation directory.

cp webspace-10-fcs-addon-samples.zip webspace-for-gfv2/

cd webspace-for-gfv2/

Extract the zipped folder for samples.

unzip webspace-10-fcs-addon-samples.zip

Change to the /webspace/samples directory.

cd /webspace/samples

Install the samples.

To install a single sample (for example, socialspace.psar), type

ant -f install-gfv2.xml

Buildfile: install-gfv2.xml

show-user-warning:
   [input] Ant must be 1.7 or greater. JAVA_HOME must be set to JDK 1.5 or greater. 
[RETURN to continue or CONTROL-C to stop]


set-glassfish-properties:
   [input] Enter GlassFish Directory  [/opt/webspace-gfv2-sunos/glassfish2]
/<install-dir>/glassfish
   [input] Enter GlassFish Domain (include full path to domain)  [/<install-dir>/glassfish/domains/domain1]


set-psar-properties:
   [input] Enter psar file (include full path)  [samples/sample.psar]
/<install-dir>/webspace-for-gfv2/webspace/samples/samples/socialspace.psar

To install all samples, type

ant -f install-all-gfv2.xml

Buildfile: install-all-gfv2.xml

show-user-warning:
   [input] Ant must be 1.7 or greater. JAVA_HOME must be set to JDK 1.5 or greater. 
[RETURN to continue or CONTROL-C to stop]


set-glassfish-properties:
   [input] Enter GlassFish Directory  [/opt/webspace-gfv2-sunos/glassfish2]
/<install-dir>/glassfish
   [input] Enter GlassFish Domain (include full path to domain)  [/<install-dir>/glassfish/domains/domain1]


install:
    [echo] Stopping GlassFish...
    [echo] Execute /477/glassfish/bin/asadmin stop-domain if install hangs.

Restart theGlassFish server.

Configuring Web Space Server for Other Databases

MySQL 5.x (or later versions) or Oracle 10g (or later versions) are officially supported for a production environment. MySQL is the default database for the production environment but you can install and configure Web Space Server for other databases as well.

Configuring Web Space Server for Microsoft SQL

You must have the following software installed:

.NetFramework 3.0 and above
Windows Installer 4.5 and above
Windows Power Shell

To Install SQL Server Express 2008 With Management Tools

Download SQL Server 2008 Express with Tools/SQL Server 2008 Express Advanced Series.

Run the SQLEXPRADV_x86_ENU.exe file.

Click the System Configuration Checker in the SQL Server Installation Center to see if all the prerequisites are installed.

Choose Installation.
- If you are doing a fresh installation, select the New SQL Server standalone installation.
- If you are upgrading an existing installation, select the Add Features to an Existing Installation option.

Type the product key and click Next.

The product key setting page appears.

Accept the licence terms and click Next.

The licence terms page appears.

Click Install in the Set Up Support Files screen. Click Next on completing the setup.

In the Features Selection screen that appears, select the Database Engine Services and ManagementTools-Basic features.

Type MSSQLSERVER in the Named instance and Instance ID boxes for Instance configuration. Click Next.

See http://msdn.microsoft.com/en-us/library/ms165614.aspxfor more information about configuration.

Make the following changes in the Server Configuration page
1. Use NT AUTHORITY\SYSTEM as the account name for SQL Server Database engine.
2. Change the SQL Server browser startup to Automatic.
Other settings remain the same.

Do the following changes in the Database Engine Configuration screen:
1. Select Mixed Node so that the built in admin user sa can be user for authorization in addition to Windows authorization.
2. Provide a password for the account sa.
3. Click Next and wait till the installation is complete.

To Start Microsoft SQL Server

Run MSSQL Server Configuration Manager.

Navigate to SQL Server Network Configuration -> Protocols for SQL SERVER. Enable TCP/IP and Named Pipes. SQL server uses port 1433 by default.

Right-click SQL Server Services and choose SQL Server from the pop-up menu. Click Start.

Verify that Microsoft SQL is running.

You can verify this on the Solaris platform by running the netstat -an | grep 1433 command in a terminal window.

To Connect to Microsoft SQL Using the Management Studio tool

Run SQL Server Management Studio.

Navigate to File -> Connect Object Explorer.

Apply the following settings:
- Server Type: Database Engine
- Server Name: Name of the computer
- Authentication : SQL Server Authentication. In order to use SQL Server authentication, you need to select the Mixed Mode (Windows authentication + SQL Server authentication) option while installing Microsoft SQL.
  - Login : sa
  - Password : MSSQL administrator password assigned during installation

Click Connect.

Select New Query in the Management Studio tool.

Type create database lportal and click Execute.

The message “Query executed successfully” is displayed on successful creation of the database named lportal.

To Configure Web Space Server to Use Microsoft SQL

Add the following text to theportal-ext.properties file in theRoot-Dir/webspace-for-gfv2/var/webspace/war-workspace/customs/webspace/WEB-INF/classes directory.

# SQL Server
    #
    jdbc.default.driverClassName=net.sourceforge.jtds.jdbc.Driver
    jdbc.default.url=jdbc:jtds:sqlserver://localhost:1433/lportal
    jdbc.default.username=sa
    jdbc.default.password=<admin password set for MsSQL>

Download the jTDS JDBC driver from http://jtds.sourceforge.net/.

Copy the JAR file to the GlassFish-install-dir/domains/domain1/lib directory.

Restart the GlassFish server.

Updating WAR or Property Files

The process for updating a deployed WARor property file in Sun GlassFish Web Space Server is complex.

The following procedure describes how to update the portal-ext.properties file. Similarly, you can update a deployed WAR file.

To Update the `portal-ext.properties` File and a WAR File

Install the Web Space Server core zip file.

Create the directory structure webspace/WEB-INF/classes under install-dir/webspace-for-gfv2/var/webspace/war-workspace/customs.

Create a dummy portal-ext.properties file with the following entry in it:
```
dummy.property=true
```

Change to the install-dir/webspace-for-gfv2/var/webspace/war-workspace directory.

Run ant -f synchronize.xml.

Restart the GlassFish server.

The server will redeploy webspace.war and update portal-ext.properties in the directory GlassFish install-dir/domains/domain1/application/j2ee-modules/webspace/WEB-INF/classes.

Now add the OpenSSO add-on. Make sure to update the AMConfig.properties and portal-ext.properties files.

Restart the GlassFish server.

The portal-ext.properties file now contains the property dummy.property=true and OpenSSO related properties.

You can use the same process for any other WAR file.

Installing Web Space Server on Sun GlassFish Enterprise Server 2.1

Upgrade versions of Web Space Server can only be installed on GlassFish Enterprise Server 2.1 because only the enterprise version can be upgraded to GlassFish 2.1 patch 01. GlassFish 2.1 can be patched to GlassFish 2.1 patch 01 only if GlassFish 2.1 is an Enterprise Edition server (EE version) and not the open source version which uses a JAR based installer.

You can find the instructions to install Web Space Server on a cluster of Sun GlassFish Enterprise Server in the Web Space Server Deployment Guide.

To Install Web Space Server on Sun GlassFish Enterprise Server 2.1

Install Sun GlassFish Enterprise Server 2.1 on your machine.

Install Web Space Server 10.0.

Download webspace-for-gfv2.zip and unzip it.

Stop the Sun GlassFish Enterprise Server 2.1.

Add the following code to the server.policy file in the glassfish/domains/domain1 folder.

grant codeBase "file:${com.sun.aas.instanceRoot}/lib/-" {
   permission java.security.AllPermission;
};

// permissions for Webspace
grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/webspace/-" {
   permission java.security.AllPermission;
};

grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/saw-web/-" {
  permission java.security.AllPermission;
}; // Basic set of required permissions granted to all remaining code
grant {
...............
...............
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};

grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/ruon-web/-" {
permission java.security.AllPermission;
};

grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/wsrp-portlet/-" {
permission java.security.AllPermission;
};

Note –

You need to grant permissions for any web-app that tries to create database tables. For example, you will have to add the permission blocks for CommunityMapper and opensso-web also, in the same way as you added permission blocks for webspace and saw-web.

Update the portal-ext.properties file with auto.deploy.glassfish-tomcat.jee.dm.id=deployer:Sun:AppServer::localhost:4848:https

The portal-ext.properties file is located in ws_install_dir/var/webspace/war-workspace/customs/webspace/war-workspace/customs/webspace/WEB-INF/classes/portal-ext.properties.

Change to the ws_install_dir/webspace/application directory and run ant -f install.xml.

Chapter 2 Web Space Server Installation Instructions

Installing the Database, Application Server, and Web Space Server

Before You Begin

System Requirements

Installation Directories

Platform-Specific Path Separators

To Install and Configure MySQL

To Install the GlassFish JAR Based Installer

To Install Web Space Server

To Connect to a Database Other Than HSQL

UTF-8 Support for Oracle 10g or Later

Restriction on the CHARACTER SET

Installing Updates from the Update Tool

To Download the Updates Using Update Tool

Figure 2–1 Update Tool

Figure 2–2 Selecting the support.sun.com repository

To Download the Updates Using the CLI-Based pkg Tool

To Use updatetool in a Proxy That Requires Authentication

Installing Samples

To Install Samples

Configuring Web Space Server for Other Databases

Configuring Web Space Server for Microsoft SQL

To Install SQL Server Express 2008 With Management Tools

To Start Microsoft SQL Server

To Connect to Microsoft SQL Using the Management Studio tool

To Configure Web Space Server to Use Microsoft SQL

Updating WAR or Property Files

To Update the portal-ext.properties File and a WAR File

Installing Web Space Server on Sun GlassFish Enterprise Server 2.1

To Install Web Space Server on Sun GlassFish Enterprise Server 2.1

Figure 2–2 Selecting the `support.sun.com` repository

To Use `updatetool` in a Proxy That Requires Authentication

To Update the `portal-ext.properties` File and a WAR File