Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Quick Start Guide

- Previous: Book Information
- Next: Chapter 2 Quick Start for Setting Up High Availability Failover

# Chapter 1 Quick Start

Welcome to the Quick Start Guide. This guide is for developers, system administrators, and Application Server administrators who are interested in learning about the capabilities of the Sun Java System Application Server 8.1 2005Q2 software.

This guide describes basic and advanced steps for using Application Server. The steps are presented in the order that you should complete them. The basic steps, which usually require less than 45 minutes to complete, are in these sections:

- Starting the Server

- Creating a Cluster

- Deploying an Application

The advanced steps, which usually require about 45 minutes to complete, are in these sections:

- The steps for setting up load balancing, in Setting up Load Balancing

- The steps for setting up high availability and failover, in Chapter 2, Quick Start for Setting Up High Availability Failover

The final sections of this guide include instructions for cleaning up and information on sources of information to use after completing this Quick Start Guide.

# Variable Names and Default Paths

The following table describes what the variable names and default paths are for the directories used in this guide. Variable names are in the first column, and default paths are in the second column.

Variable Name | Description and Path
--- | ---
install-dir | By default, the Application Server installation directory is located here: Solaris Java Enterprise System installations: `/opt/SUNWappserver/appserver` Linux Java Enterprise System installations: `/opt/sun/appserver/` Windows Java Enterprise System installations: SystemDrive`:\Sun\ApplicationServer` Solaris and Linux stand-alone Application Server installations, non-root user: user_home_directory`/SUNWappserver` Solaris and Linux stand-alone Application Server installations, root user: `/opt/SUNWappserver` Windows stand-alone installations: SystemDrive`:\Sun\AppServer`
domain_root_dir | By default, the directory containing all domains is located here: Solaris Java Enterprise System installations: `/var/opt/SUNWappserver/domains/` Linux Java Enterprise System installations: `/var/opt/sun/appserver/domains/` All other installations: install-dir`/domains/`
domain_dir | By default, domain directories are located here: domain_root_dir `/`domain_dir

# About Application Server Administration

To enable administrators to manage server instances and clusters running on multiple hosts, Application Server provides these tools:

- The Admin Console, a browser-based graphical user interface (GUI)

- The asadmin utility, a command-line tool

- Programmatic JavaTM Management Extensions (JMXTM) APIs

These tools connect to a server called the Domain Administration Server, a specially designated Application Server instance that intermediates in all administrative tasks. The Domain Administration Server (DAS) provides a single secure interface for validating and executing administrative commands regardless of which interface is used.

A domain is a collection of configuration data, deployed applications, and machines with a designated administrator. The domain definition describes and can control the operation of several applications, stand-alone application server instances, and clusters, potentially spread over multiple machines. When the DAS is installed, a default domain called domain1 is always installed. You work with the default domain in this guide.

To complete most of the steps presented in this guide, you will use the Admin Console.

# Starting the Server

This topic, the first of three basic topics, provides the following sections

- Starting the Domain Administration Server

- Logging in to the Admin Console

- Examining the Log File

## Starting the Domain Administration Server

To start the Domain Administration Server, start the default domain, `domain 1`, using the following procedures.

Note –

Because this guide instructs you to set an environment variable `AS_ADMIN_USER` for administrative user name, it does not instruct you to supply a user name argument when the `asadmin` command is used. Without the environment variable, you supply this argument when you type the command. The general syntax is:

`asadmin` command_verb`--user` username command_arguments

For example, if your user name is `admin`, the syntax for `asadmin` `start-domain` is: `asadmin start-domain --user admin domain1`

### To Start the Domain on Solaris and Linux

1. Add the install-dir`/bin/` directory to the `PATH` environment variable.

2. Set the `AS_ADMIN_USER` environment variable so that you do not need to type it for every command.

   Set the value of `AS_ADMIN_USER` to the admin user you specified when you installed the Application Server. For example, `setenv AS_ADMIN_USER admin`

3. Start the server by entering this command from the install-dir:

   `asadmin start-domain domain1`

   When you are prompted for the admin password and the master password, enter the passwords that you provided during installation.

4. A message appears telling you that the Domain Administration Server is starting:

   `Starting Domain domain1, please wait. Log redirected to domain_dir/domain1/logs/server.log...`

5. When the startup process has completed, an additional message appears:

   `Domain domain1 started`

### To Start the Domain on Windows

1. From the Explorer window or desktop, right click My Computer.

2. Choose Properties to display the System Properties dialog.

3. Click the Advanced tab.

4. Click Environment Variables.

5. In the User variables section:

   - If a `PATH` variable exists, verify that install-dir`\bin` exists in the path: install-dir`\bin;`other_entries.

   - If a `PATH` variable is not present, click New. In Variable Name, type `PATH`. In Variable Value, type the path to the server’s `bin` directory: install-dir`\bin`. Click OK to commit the change.

6. Add a new environment variable `AS_ADMIN_USER` and set it to the Administrative User Name that you assigned during installation.

7. Click OK to commit the change and close the remaining open windows.

8. Start the Application Server

   - For Java Enterprise System installations, from the Start menu, choose Programs ⇒ Sun Microsystems ⇒ Application Server⇒ Start Admin Server.

   - For stand-alone installations, from the Start menu, choose Programs ⇒ Sun Microsystems ⇒ Application Server EE ⇒ Start Admin Server.

9. When a command prompt window opens to prompt you for the admin password and the master password, enter the passwords that you provided during installation.

   A window appears with a message telling that you the server is starting:

   `Starting Domain domain1, please wait. Log redirected to domain_dir\domain1\logs\server.log...`

   When the startup process has completed, you see an additional message:

   `Domain domain1 started.Press any key to continue ...`

10. Press a key to close the message window.

## Logging in to the Admin Console

The Admin Console is a browser interface that simplifies a variety of administration and configuration tasks. It is commonly used to:

- Deploy and undeploy applications

- Enable, disable, and manage applications

- Configure resources and other server settings

- Configure clusters and node agents

- Manage server instances and clusters

- Select and view log files

For further information about using the Admin Console, consult the online help or the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

### To Log In to the Admin Console

1. Type this URL in your browser:

   `https://` localhost`:4849/asadmin`

   Because the Admin Console is a secure web application, you must use https instead of http.

   Replace the localhost variable with the name of the system that the Domain Admin Server is running on.

   `4849` is the Admin Console’s default port number. If you changed the port number during the installation, use that number instead.

   Note –

   If a popup window appears with a message such as `Website Certified by an Unknown Authority`, click OK.

   This message appears because your browser does not recognize the self-signed certificate that the Domain Administration Server uses to service the Admin Console over the secure transmission protocol.

2. When the log in window appears, enter the admin user name and password.

3. Click Log In.

   When the Admin Console appears, it looks like this:

   In the left pane, select what you want to manage from the tree provided. In the right pane, various administrative tasks are listed under the “Common Tasks” heading.

   Tip –

   Click the Registration tab to register your software if you have not already done so.

## Examining the Log File

Application Server instances and the Domain Administration Server produce annotated logs on the file system. By default, all errors, warnings or useful informative messages are logged.

### To View the Domain Administration Server Log File

1. From the Common Tasks list in the right pane, click Search Log Files to launch a new browser window for Log Viewer.

2. In the Log Viewer window, select “server” from the Instance Name drop–down list and click Search.

   The Domain Administration Server’s recent log file entries are displayed.

3. Scan the messages and look for any `WARNING` or `SEVERE` messages indicating that problems were encountered during server start-up.

   You can close Log Viewer at any time. After you create clusters and deploy applications, examine log files if any of the operations failed. Use Log Viewer to view the log files of any running Application Server instance in the domain.

   For more information about the log file, see Chapter 15, Configuring Logging, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

##### Next Steps

In this section you started the Domain Administration Server and confirmed that it is running. You also logged in to the Admin Console and used the Log Viewer. You can stop the Quick Start trail here if you do not wish to continue, or you can go on to the next section.

# Creating a Cluster

This section, the second of three basic topics, explains how to create a cluster that contains two Application Server instances. For simplicity, the cluster runs completely within one machine. This topic includes the following tasks:

- To Start the Node Agent

- To Create a Cluster

## To Start the Node Agent

A node agent is a lightweight process running on each machine that participates in an Application Server administrative domain. The node agent is responsible for starting and stopping server instances on the host. It also collaborates with the Domain Administration Server to create new Application Server instances.

One node agent is needed on a machine, for each Application Server administrative domain that the machine belongs to. If you chose the Node Agent Component during installation, a default node agent called hostname was created.

1. In a terminal window, type this command:

   `asadmin start-node-agent` hostname

   Replace the variable hostname with the name of the host where the Application Server is running.

2. When you are prompted, provide the master password.

   The node agent starts and connects with the Domain Administration Server.

   Note –

   If the Domain Administration Server is not running, the node agent might fail to start.

## To Create a Cluster

A cluster is a group of server instances (typically on multiple hosts) that share the same configurations, resources, and applications. A cluster facilitates load balancing across server instances and high availability through failover. You can create clusters spanning multiple machines and manage them with the help of the node agent process on each machine. In this guide, for simplicity, our sample cluster will be on one host, the same one where the Domain Administration Server is running.

##### Before You Begin

You must have already started the node agent process on each machine, as described in previous section. When you specify instances during cluster creation, you must associate the instance with a running node agent for the machine on which you want the instance to run. If the node agent is not running, the instance will not start. Node agent and instance names must be unique across clusters that are created in a domain.

1. Log in to the Administration Console at `https://` localhost`:4849` if you have not already done so.

   Replace the localhost variable with the name of the system that the Domain Administration Server is running on.

   `4849` is the Admin Console’s default port number. If you changed the port number during the installation, use that number instead.

2. On the right pane, under Common Tasks, click Create New Cluster to display the Create Cluster input page.

3. Type `FirstCluster` as the name of the new cluster.

4. From the drop-down list of available configuration templates, select the default-config configuration and choose `Make a copy of the selected Configuration`.

5. Click the Add button twice, to create two entries to specify two instances for the cluster.

6. Type `i1` and `i2` as instance names. The node agent name is automatically populated with the name of the local machine.

   You see a screen like this:

7. Click OK. The create process can take a few minutes.

   Note –

   This exercise requires automatically assigned port numbers for HTTP, HTTPS, IIOP and IIOPS. You can change them later, if desired.

   When the create process is completed, the Cluster Created Successfully page appears, and `FirstCluster` appears in the tree in the left pane. A copy of the configuration template `default-config` was made for this cluster, and the name `FirstCluster-config` was assigned to it.

8. In the left pane, expand Clusters and click FirstCluster to display the General Information page for clusters.

9. Click the Instances tab to display i1 and i2, the instances that you created.

   1. Click i1 to examine this instance.

   2. From the tabs above the General Information heading of the right pane, click Properties and see the value for `HTTP_LISTENER_PORT`.

   3. Repeat these steps for i2.

      Note –

      By default, the HTTP ports are 38081 for i1 and 38080 for i2. If these ports were busy on your machine when you created these clusters, or if you had already assigned these ports to other instances and clusters, different port numbers were assigned.

##### Next Steps

In this section you have created a simple cluster on a single machine. You can also create clusters spanning multiple machines using the same basic steps (as long as you have the software installed and a node agent running on each machine).

You can stop the Quick Start trail here if you do not wish to continue, or you can go on to the next section.

# Deploying an Application

This section, the third of three basic topics, presents the following steps:

- To Deploy the Sample Application

- To Start the Cluster

- To Verify the Application Deployment

## To Deploy the Sample Application

This guide uses the `clusterjsp` sample application to demonstrate web path load balancing capabilities. This task shows you how to deploy that application.

Note –

Ensure that you have enabled cookies in your browser before you deploy this application.

1. Click the Home button to go to the Common Tasks page, if you are not there already.

2. On the right pane, under Common Tasks, click Deploy Enterprise Application.

3. In the File to Upload text box, click Browse, and navigate to install-dir`/samples/ee-samples/highavailability/apps/clusterjsp/clusterjsp.ear`.

4. Click Next to display the Deploy Enterprise Application page.

5. Scroll down to the Targets section of the page.

6. Select FirstCluster from the Available list, and click Add to move it to the Selected list.

7. Click OK.

   The `clusterjsp` application is now deployed to FirstCluster.

## To Start the Cluster

1. In the tree on the left pane, click the FirstCluster node under Clusters.

2. In the right pane, click the General tab if it is not already active.

3. Click the Start Instances button to start the cluster.

4. Verify that it has started by checking that the Status field, which indicates what instances are running.

## To Verify the Application Deployment

This procedure verifies that the application was deployed properly and is accessible on each instance in the cluster.

1. Type the following URL in your browser:

   `http://`localhost`:`port`/clusterjsp`

   Replace the localhost variable with the name of the system that the Domain Admin Server is running on.

   Replace the port variable with the value of `HTTP-LISTENER-PORT` for i1. This example uses `http://`localhost`:38081/clusterjsp`.

2. Add some session attribute data.

3. Examine the Session and Host information displayed. For example:

   - `Executed From Server:` localhost

   - `Server Port Number: 38081`

   - `Executed Server IP Address: 198.19.255.255`

   - `Session Created: Day Mon 05 14:55:34 PDT 2005`

4. Add some session data and click the Add to Session button.

5. Repeat this procedure for instance i2 by typing this URL in your browser:

   `http://`localhost `:38080/clusterjsp`

   In this section you deployed an application to a cluster and tested that the application is available on all instances in the cluster.

   Congratulations! You have completed the basic steps in this Quick Start Guide. You can stop the Quick Start trail here if you do not wish to proceed to the advanced steps.

# Setting up Load Balancing

A load balancer is typically deployed in front of a cluster. It:

- Allows an application or service to be scaled horizontally across multiple physical (or logical) hosts yet still presents the user with a single URL

- Insulates the user from host failures or server crashes, when it is used with session replication

- Enhances security by hiding the internal network from the user

Application Server includes load balancing plug-ins for popular web servers like Apache, Microsoft Windows IIS, and Sun Java System Web Server.

This section provides instructions on how to download and set up the Web Server software to act as a load balancer to the cluster of Application Servers. To complete this section, you must have sufficient memory to run a Web Server on your system in addition to the Domain Administration Server and the two Application Server instances you have created so far in this guide. A system with 512 Mbytes to 1024 Mbytes of memory is recommended to complete this section.

This topic presents the following steps:

- Installing Web Server Software

- Installing the Load Balancer Plug-in

- Creating a Load Balancer Configuration

- Starting Load Balancing

- Verifying Load Balancing

## Installing Web Server Software

If you already have Web Server software installed, and if you can identify a Web Server instance to serve as the load balancer, note the location of this instance in the file system and skip to Installing the Load Balancer Plug-in.

### To Install the Web Server Using the Java Enterprise System Installer

If you are using Sun Java Enterprise System software, the Web Server is selected for installation automatically when you choose to install the Load Balancer Plug-in. However, you can also install Web Server software using these steps:

1. Launch the Java Enterprise System installer.

2. Select the Sun Java System Web Server component in the Component Selection page.

3. Choose “Configure Now” to be prompted for Web Server Configuration during installation.

4. When you are prompted, define a default Web Server instance.

   Tip –

   Remember the port number you choose for this default Web Server instance. This guide assumes that port 38000 is selected as the HTTP port for default instance.

### To Install the Web Server for Stand-Alone Application Server Installations

If you are using a stand-alone Application Server, or if you do not have access to the Sun Java Enterprise System installer, install Web Server software using these steps:

1. Go to `http://www.sun.com/downloads`. Scroll down to the Web & Proxy Servers heading and click Web Servers.

2. Download Web Server 6.1 Service Pack 2 or higher for the locale and platform of your choice.

   To download, you must log in with username and password registered with MySunSM, Sun StoreSM, SunSolveSM, or the Online Support Center. If you do not have a login account, you can register online.

3. Follow the instructions to install Web Server software. You must:

   1. Extract the software from the compressed archive.

   2. Run the setup program. If you need additional information, see the Web Server installation instructions at `http://docs.sun.com`.

4. The Web Server installation process configures the Administration Server for Web Server and prompts you to define a default Web Server instance.

   Tip –

   Remember the port number you choose for this default web server instance. This guide assumes that port 38000 is selected as the HTTP port for default instance.

## Installing the Load Balancer Plug-in

The section describes installing the load balancer plug-in for either a Sun Java Enterprise System distribution or a stand-alone Application Server distribution.

### To Install the Load Balancer Plug-in

1. Run the installer for the software distribution you are using—Sun Java Enterprise System software or the stand-alone Sun Java System Application Server software.

2. When you are asked which components you want to install, select Load Balancing Plug-in.

   On the Sun Java Enterprise System installer, you must expand the Application Server item to see the Load Balancing Plug-in. It is not selected for installation by default.

## Creating a Load Balancer Configuration

Now return to interacting with the Application Server’s Domain Admin Server. You need a shell execution environment for this section.

### To Create an HTTP Load Balancer Configuration

1. Create a load balancer configuration called `MyLbConfig` targeted to the cluster FirstCluster:

   `asadmin create-http-lb-config --target FirstCluster MyLbConfig`

2. Enable the FirstCluster cluster and the clusterjsp application deployed in it for HTTP load balancing:

   `asadmin enable-http-lb-server FirstCluster`

   `asadmin enable-http-lb-application --name clusterjsp FirstCluster`

3. Create a health checker for the load balancer, which signals when an instance that goes down recovers.

   `asadmin create-http-health-checker --interval 10 --config MyLbConfig FirstCluster`

   The interval is the number of seconds the health checker waits between checks of an unhealthy instance.

4. Export the configuration to a file `loadbalancer.xml`.

   `asadmin export-http-lb-config --config MyLbConfig loadbalancer.xml`

5. Copy `loadbalancer.xml` to:

   web_server_install_dir`/https-`hostname`/config/loadbalancer.xml`

## Starting Load Balancing

Start load balancing by starting or restarting the Web Server.

- If the Web Server instance serving as load balancer is not already running, start the Web Server software by executing the start program in the following directory:

  web_server_install_dir`/https-`hostname

- If the Web Server instance serving as load balancer is already running, stop the server and start it using the start and stop programs in the following directory:

  web_server_install_dir`/https-`hostname

## Verifying Load Balancing

Once the application is deployed and the load balancer is running, verify that the load balancing is working.

### To Verify Load Balancing

1. To display the first page of the clusterjsp application, type this URL in your browser:

   `http://`localhost`:`web_server_port`/clusterjsp`

   Replace the localhost variable with the name of the system that the Web Server is running on.

   Replace the web_server_port variable with the value of the port attribute of the `LS` element in web_server_install_dir`/https-`hostname`/config/server.xml`. For this example, port 38000 is used.

   A page similar to what you saw in To Verify the Application Deployment. appears.

2. Examine the Session and Host information displayed. For example:

   - `Executed From Server:` localhost

   - `Server Port Number: 38000`

   - `Executed Server IP Address: 192.18.145.133`

   - `Session Created: Day Mon 05 14:55:34 PDT 2005`

3. The Server Port Number is 38000, the Web Server’s port. The load balancer has forwarded the request on the two instances in the cluster.

4. Using different browser software, or a browser on a different machine, create a new session. Requests from the same browser are “sticky” and go to the same instance.

   These sessions should be distributed to the two instances in the cluster. You can verify this by looking at the server access log files located here:

   - Solaris Java Enterprise System installation:

     `/var/opt/SUNWappserver/nodeagents/`nodeagent_name`/i1/logs/access/server_access_log`

     `/var/opt/SUNWappserver/nodeagents/`nodeagent_name`/i2/logs/access/server_access_log`

   - Linux Java Enterprise System installation:

     `/var/opt/sun/appserver/nodeagents/`nodeagent_name`/i1/logs/access/server_access_log`

     `/var/opt/sun/appserver/nodeagents/`nodeagent_name`/i2/logs/access/server_access_log`

   - Windows Java Enterprise System installation:

     install-dir`\nodeagents\`nodeagent_name`\i1\logs\access\server_access_log`

     install-dir`\nodeagents\`nodeagent_name`\i2\logs\access\server_access_log`

   - Stand-alone Application Server installations:

     install-dir`/nodeagents/`nodeagent_name`/i1/logs/access/server_access_log`

     install-dir`/nodeagents/`nodeagent_name`/i2/logs/access/server_access_log`

5. Add a name and value pair (`Name=Name Value=Duke`) for storing in `HttpSession`.

6. Click the “Add to Session Data” button.

7. Verify that the session data was added

##### Next Steps

In this section you created an instance to use as a load balancer and set up a load balancing configuration. You also verified load balancing.

To configure and verify HTTP session failover, continue to Chapter 2, Quick Start for Setting Up High Availability Failover. Otherwise continue on to Cleaning Up.

# Cleaning Up

To clean up, you can uninstall the Application Server installation by completing the steps in To Uninstall Completely, or you can simply delete the sample cluster you have just created by completing the steps in To Remove the Sample Cluster Only.

Caution –

If you plan to complete Chapter 2, Quick Start for Setting Up High Availability Failover do not use these clean-up procedures. Instead, go to Chapter 2, Quick Start for Setting Up High Availability Failover now and when you are done use the procedures you’ll find there to clean up.

## To Uninstall Completely

To completely uninstall Application Server and also uninstall the Web Server, use the following procedure.

1. Stop the Application Server processes using these commands:

   `asadmin stop-cluster FirstCluster`

   `asadmin stop-node-agent hostname`

   `asadmin stop-domain domain1`

   At this point all processes related to Application Server are stopped.

2. Uninstall the Application Server.

   In a Solaris or Linux Java Enterprise System installation, run `var/sadm/prod/entsys/uninstall` and follow the steps in the uninstallation wizard.

   In a Windows Java Enterprise System installation, use the Control Panel's Add/Remove Programs item. Choose Sun Java Enterprise Systems and click Change/Remove.

   In a Solaris or Linux stand-alone Application Server installation, run install-dir`/uninstall` and follow the steps in the uninstallation wizard.

   In a Windows stand-alone installation, from the Start menu, choose Programs ⇒ Sun Microsystems ⇒ Application Server EE ⇒ Uninstall.

3. If you installed Web Server for this exercise, stop the web server instance acting as load balancer and uninstall the Web Server product. You can stop the instance by executing the stop program in the following directory:

   web_server_install_dir`/https-`hostname

4. If you want to unsinstall the Web Server product, run the uninstall program from the web_server_install_dir.

## To Remove the Sample Cluster Only

To remove only the FirstCluster (the sample highly available cluster) and the sample application used during this exercise, but retain the installed Application Server and Web Server, use the following procedure.

1. Stop the Application Server processes and clean up configuration:

   `asadmin stop-cluster FirstCluster`

   `asadmin disable-http-lb-server FirstCluster`

   `asadmin delete-http-lb-ref --config MyLbConfig FirstCluster`

   `asadmin delete-http-lb-config MyLbConfig`

   `asadmin delete-instance i1`

   `asadmin delete-instance i2`

   `asadmin delete-cluster FirstCluster`

   `asadmin undeploy clusterjsp`

2. Stop the web server instance acting as load balancer by running the stop program in the following directory:

   web_server_install_dir`/https-`hostname

3. Rename the `loadbalancer.xml` file in web_server_install_dir`/https-`hostname `/config` to `loadbalancer.xml.sav`

# Where to Go Next

Other resources for learning about and using Application Server are available. They include:

- Product details at install-dir`/docs-ee/about.html`.

  See this document for the latest information on what is new, and pointers to tutorials and other educational services.

- Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Release Notes

  See this document for late-breaking information regarding this release.

- Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide

  See this document for information on performing administrative functions using the Admin Console.

- Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual

  See this document for reference information on Application Server’s command-line utilities, such as `asadmin`.

- Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

  See this document for information on the Sun Java System Application Server’s high availability features.

- The J2EE 1.4 Tutorial

  See this document for a tutorial that covers the process for building and deploying Java 2 Platform, Enterprise Edition (J2EETM platform) applications.

- Java BluePrints guidelines for the Enterprise

  See this document for a comprehensive set of examples that demonstrate operations of the Application Server software and that can be used as application templates.

- Previous: Book Information
- Next: Chapter 2 Quick Start for Setting Up High Availability Failover

- © 2010, Oracle Corporation and/or its affiliates