Installation and Configuration Guide (All Platforms)

Table of Contents

Sun GlassFish Web Stack Installation and Configuration Guide

This document describes how to install and configure Sun GlassFish Web Stack and its components on Solaris and Linux platforms.

Introduction

Sun GlassFish Web Stack is a complete open source web application platform consisting of Apache, lighttpd, MySQL, PHP, Tomcat, Glassfish, Ruby, and Python. It comes with the support for Memory Caching framework (memcached), Dynamic Trace debugging (DTrace), Xdebug, and advanced PHP security framework (Suhosin).

Sun GlassFish Web Stack is available for Solaris, OpenSolaris, and Red Hat Enterprise Linux.

Sun GlassFish Web Stack Components

The table lists the primary components bundled with Sun GlassFish Web Stack.

Sun GlassFish Web Stack Distributions

Sun GlassFish Web Stack is distributed in two different versions.

• Native Package Version: This is the non-relocatable version of the Sun GlassFish Web Stack distribution. It can only be installed in the system directories as specified in the Sun GlassFish Web Stack Directory Layout section. This guide deals with the Native Package Version by default.
• Unbundled IPS/pkg(5) distribution: This distribution is based on the Image Packaging System (IPS). This distribution can be installed in the directory of your choice.

The Unbundled IPS/pkg(5) distribution provides the following significant benefits:

• Non Root Installation : Supports installation of Sun GlassFish Web Stack without root or administrative privileges.
• Relocatable Installation : Allows for the installation of multiple copies of the Sun GlassFish Web Stack on the same system.
• Simplified Add-On Framework : Simplified component install, update and uninstall mechanism.

Installing Sun GlassFish Web Stack

This section discusses the installation of Sun GlassFish Web Stack on Solaris, OpenSolaris, and Linux platforms.

User Permissions

This section explains about the user permissions required for Sun GlassFish Web Stack installation.

Native Package Version

System administration or root privileges are required for performing the Native Package installation.

Unbundled IPS/pkg(5) distribution

Sun GlassFish Web Stack Unbundled IPS/pkg(5) distribution can be installed with or without the administrative or root privileges. When installing as the root user, file and directory ownership as well as run-time identity will match a native package install (e.g., webservd for Apache or Lighttpd). If the required daemon user id doesn't already exist, installation will fail and the user will be prompted to create it manually. When installing as non-root user, all the files and directories will be owned by the user running the installation, and that will be used as the run-time identity as well.

Sun GlassFish Web Stack Operating System Dependencies

Platform specific dependencies exist on Solaris and Red Hat Enterprise Linux platforms. Install the dependent packages first. The following table summarize the dependencies for various Sun GlassFish Web Stack components.

Note This is not a complete dependency list. Only important packages are listed here.

Warning Unbundled IPS/pkg(5) distribution of Sun GlassFish Web Stack installer has no way of checking the Operating System dependencies. You must cross check with the following dependency table and install all the required dependent packages prior to installing the respective Sun GlassFish Web Stack Components.

|| Sun GlassFish Web Stack Component || Important Solaris Dependencies || Important Red Hat Enterprise Linux Dependencies ||

Note On the Red Hat Enterprise Linux x86_64 version, Sun GlassFish Web Stack also depends upon the 32 bit versions of the listed packages.

Installing Sun GlassFish Web Stack on Solaris and Linux Platforms

Perform the following steps to install Sun GlassFish Web Stack

1. Download the Sun GlassFish Web Stack package from the Sun GlassFish Web Stack download page, http://www.sun.com/systems/solutions/amp/getit.jsp. The download page provides packages for RedHat Enterprise Linux (x86 and x86_64) and Solaris (x86, x86_64, and Sparc). Download the package which is relevant to your platform.
2. Extract the tar.gz file containing the Sun GlassFish Web Stack installer.

   gunzip -c xxx.tar.gz | tar xf -
   

   This command will expand the Web Stack installation files into the current directory; you may wish to perform this step within a temporary directory.

3. Run the installation script to begin the installation. The list of available installer commands are shown in the following table.

Installing Sun GlassFish Enterprise Server

Sun GlassFish Enterprise Server is shipped with its own installer and can be installed using the GlassFish Enterprise Server intallation waizard. You can install the GlassFish Enterprise Server by executing the installer in the GUI mode:

./sges-2_1-solaris-sparc.bin on Solaris SPARC platform

./sges-2_1-solaris-i586.bin on Solaris x86 platform

./sges-2_1-linux.bin on Linux platform

For more detailed information, see Sun GlassFish Enterprise Server 2.1 Installation Guide.

Installing Sun GlassFish Web Stack on OpenSolaris Platform

For information on installing Sun GlassFish Web Stack on OpenSolaris platform, see Web Stack Getting Started Guide for OpenSolaris

Installing Sun GlassFish Web Stack Unbundled IPS/pkg(5) distribution

The Sun GlassFish Web Stack unbundled IPS/pkg(5) distribution is delivered in the form of a minimized distribution. A small, base set of the Web Stack components are pre-installed. The remaining components are available in a networked based repository. To install additional components or update installed components the Web Stack distribution contains a command line interface (pkg) as well as a graphical user interface (updatetool) to assist with the installation.

Setting up the Unbundled IPS/pkg(5) distribution for Sun GlassFish Web Stack

Perform the following steps to set up the Unbundled IPS/pkg(5) distribution for Sun GlassFish Web Stack

1. Download the Sun GlassFish Web Stack Unbundled IPS/pkg(5) distribution package from the Sun GlassFish Web Stack download page, http://www.sun.com/systems/solutions/amp/getit.jsp. Download page provides packages for RedHat Enterprise Linux (x86 and x86_64) and Solaris (x86, x86_64, and Sparc). Download the package which is relevant to your platform.
2. Extract the tar.gz file containing the Sun GlassFish Web Stack Unbundled IPS/pkg(5) distribution into any desired location. 

   gunzip -c webstack-image-* | tar xf -
   

3. Change into the webstack-1.5 directory (you may rename this directory if you prefer). The same directory will become the installation directory for all the Sun GlassFish Web Stack components. You can move or rename this directory as per your choice. This directory contains the following important binaries that you will use to manage Sun GlassFish Web Stack components
   • ./bin/pkg : Command Line Interface (CLI) for the Unbundled IPS/pkg(5) distribution.
   • ./bin/updatetool : Graphical User Interface (GUI) for the Unbundled IPS/pkg(5) distribution.
   • ./bin/setup-webstack : Post Installation Utility for the Unbundled IPS/pkg(5) distribution. You must run it after installing packages via CLI.

Note To install and update packages using the Unbundled IPS/pkg(5) distribution, you need a working internet connection.

Using Unbundled IPS/pkg(5) distribution CLI

You can use the ./bin/pkg command to install Sun GlassFish Web Stack packages from command line. Some of the important commands are shown in the following table.

Note You need to execute ./bin/setup-webstack after running the command ./bin/pkg install.

You can check the Sun GlassFish Web Stack Components section or the command list -a for a list of valid package names.
For more information on the pkg command, see the pkg(5) man page and the Update Center Wiki.

Using Unbundled IPS/pkg(5) distribution GUI

Sun GlassFish Web Stack Unbundled IPS/pkg(5) distribution ships with GUI tool called the Update Tool. Update Tool can be invoked by using the following command:

./bin/updatetool

You can use the update tool to perform the following tasks :

• Install new add-on packages
• Manage package updates
• View information about the installed packages

To install packages click on the 'Available Add-ons' item available on the sidebar. Select the packages you wish to install and click on the green 'Install' arrow.

To update packages click on the 'Available Updates' item available on the sidebar. Select the packages you wish to update and click on the 'Update' arrow.

For more information on the updatetool, refer to the online help. Online help can be accessed by Clicking 'Help > Contents' on the Main Menubar.

Upgrading to Sun GlassFish Web Stack 1.5

Sun GlassFish Web Stack 1.5 contains a number of important bugfixes, security updates and updated components. See the Sun GlassFish Web Stack 1.5 Release Notes for more information.

You can use the install command with -u switch to perform an automatic upgrade of all the installed packages of the Sun GlassFish Web Stack.

./install -u

Warning Upgrades done using the system package management tool are not supported and may lead to software corruption.

Note You can not mix version 1.4 and version 1.5 packages together. You must upgrade all the installed components.

Managing Sun GlassFish Web Stack Services

Sun GlassFish Web Stack installs a number of services on the system. The following table lists the Sun GlassFish Web Stack services and their start / stop commands.

Automatically Starting Services in Linux

In Linux starting or stopping a service merely causes a service to start or stop for a particular system session only in which the command was run. In order to start a service automatically in Linux, it must be put in system's default runlevel.

For example, to put Apache Web Server in runlevel 3 and 5, following command can be used:

chkconfig --level 35 sun-apache22 on

Sun GlassFish Web Stack Directory Layout

This section discusses the directory layout of Sun GlassFish Web Stack components. Sun GlassFish Web Stack files are installed in three different directories:

OPT_ROOT: Application installation directory.

ETC_ROOT: Application configuration directory.

VAR_ROOT: Application data directory.

The directory paths vary by platform. The following table following table lists the directory location for Solaris, Linux, and OpenSolaris platforms.

Apache HTTP Server Files

The following list describes the directory layout for Apache HTTP Server and additional plug-in modules:

Modules mod_fcgid, mod_jk,mod_security, and mod_dtrace are pre-installed with Apache HTTP Server. For more information about these modules, see http://fastcgi.coremail.cn/doc.htm, http://tomcat.apache.org/connectors-doc/generic_howto/quick.html, http://www.modsecurity.org/documentation/index.html, and http://prefetch.net/projects/apache_modtrace/mod_dtrace.c

MySQL Database Files

The following list describes the directory layout for the MySQL Database Server.

PHP Files

The following list describes the directory layout for PHP:

Note The PHP extensions like APC, DTrace, XDebug, suhosin, and tcpwrap  are disabled by default. To enable these extensions, you need to uncomment the respective line (extensions=<module-name>.so) in the conf.d file.

Ruby Files

The following list describes the directory layout for Ruby:

Squid Proxy Server Files

The following list describes the directory layout for Squid Proxy Server:

Sun GlassFish Web Stack Default Network Ports

Sun GlassFish Web Stack utilizes several network ports by default for regular component operation. The following table lists the ports by component.

Extending Sun GlassFish Web Stack

Sun GlassFish Web Stack can be easily extended by using various third party extensions. This enables you to add new features to the existing software. To compile Sun GlassFish Web Stack extensions you need to have mandatory development packages installed on your system.

Compiler Requirments:

Solaris 10: Sun Studio 12 or later.

Red Hat Enterprise Linux: RedHat Supported GCC release from the distribution repository.

Installing PHP extensions

PHP extensions are available in two forms, PECL (PHP Extension Community Library) and PEAR (PHP Extension and Application Repository). PECL extensions are shipped as C source code. PECL extensions are compiled C language extensions linked to the PHP core. As C programs , PECL extensions run more efficiently than PEAR packages. PECL includes modules for XML-parsing, access to additional databases, mail-parsing, embedding Perl or Python in PHP scripts.

A PEAR package is distributed as a gzipped tar file. Each archive consists of source code written in PHP, usually in an object-oriented style. Many PEAR packages can readily be used by developers as ordinary third party code via simple include statements in PHP.

Installing PECL extensions

The PECL extensions need to be compiled to shared object files (.so) before they can be used with PHP.

Some extensions require additional software to successfully build and install. Installation of the extension will fail if the additional software is not found in PATH, and error messages will vary depending on the required software and the extension being installed. Additional software commonly required includes GNU Autoconf and re2c (http://re2c.org/). 

After installing Sun Studio, run the following command to download, compile and install the PECL extension:

 # OPT_ROOT/bin/pecl install <extension name>

If you are not sure of the extension name, use the following command to get a list of all the available extensions:

$  OPT_ROOT/bin/pecl list-all

Installing PEAR extensions

Run the following command to download and install the PEAR extension:

# OPT_ROOT/bin/pear install <extension name>

Installing Python extensions

Python extensions are supported through Easy Install. Easy Install is a python module (easy_install) bundled with setuptools that lets you automatically download, build, install, and manage Python packages. easy_install is capable of downloading and installing python extensions from PyPI (Python Package Index) repository.

Installing setuptools (easy_install)

Use the following commands to download and install setuptools. You need have Sun Studio installed in your system to compile setuptools package. Also, verify that Sun GlassFish Web Stack location is present in the system PATH variable. This will avoid any conflict with the existing installation of python.

1. Download and extract the python setuptools source package from http://pypi.python.org/pypi/setuptools#downloads. Download the tar.gz file (setuptools-0.6c9.tar.gz).
2. Run the following command to compile and install the setuptools package.

# python setup.py install

Using easy_install

easy_install is very easy to use. Just use the following command to download and install the python extension.

# python easy_install.py <package name>

You can browse through the PyPI repository by visting http://pypi.python.org/pypi . 

Installing Ruby extensions (RubyGems)

Ruby extensions are supported by RubyGems. RubyGems is a package manager for the Ruby programming language that provides a standard format for distributing Ruby programs and libraries (in a self-contained format called a "gem"), a tool designed to easily manage the installation of gems, and a server for distributing them.

Use the following command to install the ruby extension (gem). Make sure that you have Sun GlassFish Web Stack in PATH variable.

# gem install <gem name>

If you are not sure of gem name, use the following command to get a list of all the available gems:

# gem list -r -d

For instance, when installing the mysql gem, the paths to the MySQL 5.1 client libraries and header files must be provided, as follows:

# gem install mysql --with-mysql-include=/usr/mysql/5.1/include --with-mysql-lib=/usr/mysql/5.1/lib

Note To use gem, make sure you have direct access to the Internet. If your system is behind a firewall or if it uses a proxy server, set the HTTP_PROXY variable.

The directory referenced by GEM_HOME should be writable. So make sure you execute the following command:

$ chmod -R a+w <GEM_HOME_PATH>

Caution - Do not perform the previously mentioned tasks, if GEM_HOME refers to $HOME/.gem.

Installing Apache Extensions

Additional features for Apache are available in the form of plug-in modules from third parties. These may take the form of a single source file which is built and installed by the user by running apxs, or a more complex build which takes the path to apxs as a configure argument.

Modules are built for 32-bit or 64-bit Apache individually. (A 64-bit build of Apache is not provided for Red Hat Enterprise Linux.)
The compiler used by apxs must match the compiler used to build Apache. On OpenSolaris, and Solaris 10, the cc command found in PATH must be Sun Studio; if gcc is installed, you may have to manipulate PATH to point to Sun Studio first. On Red Hat Enterprise Linux, gcc will be used.
Here is an example module build in which both 32-bit and 64-bit versions of the module are created:

$ pfexec /usr/apache2/2.2/bin/apxs -ci mod_example.c
$ pfexec /usr/apache2/2.2/bin/64/apxs -ci mod_example.c

This will create mod_example.so in directories /var/apache2/2.2/libexec/mod_example.so and /var/apache2/2.2/libexec/64/mod_example.so.
The recommended way to load and configure the module is by creating a file in /etc/apache2/2.2/conf.d with the following contents:

<IfDefine 64bit>
LoadModule example_module /var/apache2/2.2/libexec/64/mod_example.so
</IfDefine>
<IfDefine !64bit>
LoadModule example_module /var/apache2/2.2/libexec/mod_example.so
</IfDefine>
#module configuration directives

Modules which are built using a configure script typically provide a --with-apxs or --with-apxs2 option. Specify the path to either the 32-bit or 64-bit apxs, depending on which mode is required.

Advanced Configuration

Sun GlassFish Web Stack can take advantage of Solaris OS specific features like Solaris Zones, and DTrace. For more information, see:

• Using Memcached with Solaris Zones
• DTrace and Sun GlassFish Web Stack