The Support Authority: A checklist for success with WebSphere Application Server Community Edition

These quick questions will help you avoid common mistakes when using IBM® WebSphere® Application Server Community Edition so you can focus on your development and accelerate your success. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Cindy He (hec@us.ibm.com), Software Engineer, WSO2 Inc

Cindy He is a software engineer for the IBM Software Group, currently a member of the WebSphere L2 support team. For the last two years she has worked on WebSphere Application Server support and WebSphere Application Server Community Edition support.



Russell Wright (rbwright@us.ibm.com), WebSphere Serviceability Development, EMC

Russell Wright has several years of experience developing and supporting data communications and middleware software including WebSphere Application Server. He currently manages the deployment of troubleshooting tools for the IBM Support Assistant and is a developer for the IBM Guided Activity Assistant.



08 October 2008

Also available in Chinese Japanese

In each column, The Support Authority discusses resources, tools, and other elements of IBM Technical Support that are available for WebSphere products, plus techniques and new ideas that can further enhance your IBM support experience.

This just in...

As always, we begin with some new items of interest for the WebSphere® community at large:

  • The WebSphere brand is celebrating its 10th anniversary! See the WebSphere Anniversary page to learn about how WebSphere products have become the middleware foundation for SOA around the world.
  • We’re proud to announce that IBM WebSphere Application Server V7 was released on September 26, 2008! And with that release, of course, there are several new resources to help you begin using it:
  • If you use WebSphere Portal, then you will want to check out the WebSphere Portal Security features page for some recent important security fixes. You can also learn more about securing your WebSphere Portal environment here.
  • “Going green” is something we’re all striving to do to protect our planet’s environment. IBM has a new Redpaper case study that shows how you can take smart SOA approaches to achieve green solutions.
  • The new Performance Analysis Tool for Java™, available on alphaWorks, helps you find threads that are constraining resources. It is currently available for Windows®.
  • If you want to stay on top of what’s new, see the featured documents list for a number of IBM products. You can also subscribe to proactive emails for your favorite products to learn when there’s new information available.

Continue to monitor the various support-related Web sites, as well as this column, for news about other tools as we encounter them.

And now, on to our main topic...


Asking the right question

IBM WebSphere Application Server Community Edition is a lightweight application server designed to help you accelerate your development and deployment efforts by offering technology that is quick, easy to download, and free to use. Built on Apache Geronimo technology, WebSphere Application Server Community Edition V2.1 (hereafter referred to as Community Edition) combines some of the best open source technologies, such as Apache Tomcat, OpenEJB, Apache ActiveMQ, and Apache Derby.

Since its launch, thousands of users have been quick to adopt Community Edition with great success, and with little difficulty. If you do experience problems getting started with Community Edition, chances are that asking one of the questions listed here will help you resolve the issue so you can continue moving forward with your development objectives. If you haven’t started working with Community Edition yet, use this list of questions as a checklist so you can avoid common mistakes and get the most out of Community Edition now:

  1. Have you met the system requirements?
  2. Are you using a recommended and supported Java SDK?
  3. Is the location of the Java Runtime Environment set correctly?
  4. Do you have sufficient authority to install?
  5. Are all dependent packages installed (Linux only)?
  6. Does the installation program have execute permission?
  7. Are you are using the correct URL to access the administrative console?
  8. Have you changed the administrative console’s default user name and password?
  9. Did the application server start successfully?
  10. Do you have network connectivity?
  11. Can you access the server using the host system’s short name?
  12. Are the resource references defined correctly in the deployment plan?
  13. Did you use inverse class loading in production?
  14. Did you verify class dependencies?
  15. What if I still have a problem?

And here are the answers:

  1. Have you met the system requirements?

    Before installing WebSphere Application Server Community Edition, check the detailed system requirements to confirm that your system meets the minimum memory (150 MB (not including JDK), 256 MB RAM), operating system, JVM (IBM SE 5), and other requirements. This information also describes recommended, compatible, and unsupported configurations.

  2. Are you using a recommended and supported Java SDK?

    Many installation and run time problems occur when using a Java™ SDK that Community Edition does not support. While Community Edition can run in several different Java Runtime Environments (JRE), only two are recommended: IBM Java 5 (32-bit) and IBM Java 5 (64-bit). To verify that you are using one of the recommended JREs, make sure that the java command is on your PATH and run this command from a shell:

    <command shell prompt> java -fullversion

    For example, if you are using IBM JRE 1.5, the output will look similar to this:

    J2RE 1.5.0 IBM Windows 32 build pwi32devifx-20071025 (SR6b)

    See detailed system requirements for more information.

  3. Is the location of the Java Runtime Environment set correctly?

    Community Edition sets the location of its JRE using the setenv.bat (Windows) or etenv.sh (UNIX®) commands, which are located in the <WAS_CE_HOME>/bin directory. These commands set the location of the JRE in the WASCE_JAVA_HOME environment variable. Confirm that the setenv script sets the WASCE_JAVA_HOME environment variable to the location where your JRE is installed.

  4. Do you have sufficient authority to install?

    Log on to the system with a user name that has sufficient authority to install software. On Windows, you must use the administrator ID, or a user that is a member of the Administrator group. On Linux®, use a user name that has permission to read/write/execute the installation media, the JRE directory, the target directory, and /var/log.

  5. Are all dependent packages installed (Linux only)?

    Each Linux platform contains different packages on which Community Edition depends. Some Linux distributions install these packages by default, while others do not. Before installing Community Edition on Linux, make sure that all of the dependent packages are installed. You will find lists of dependent packages are available for these Linux platforms:

  6. Does the installation program have execute permission?

    The name of the Community Edition installation program is different on Windows and UNIX platforms:

    • Windows: wasce_setup-version-win.exe
    • UNIX: wasce_setup-version-unix.bin

    On UNIX platforms, the installation program, wasce_setup-version-unix.bin, must have permission to execute before you can install Community Edition. Depending on which UNIX platform you are using, you might be able to check and set file permissions from the desktop. If you do not have this ability, follow these steps:

    1. Open a terminal window.
    2. Ensure that you have “root” privileges.
    3. Change to the directory where you downloaded the Community Edition package.
    4. Set execute permission on the installation program:

      <command shell prompt> chmod 755 wasce_setup-version-unix.bin

  7. Are you are using the correct URL to access the administrative console?

    The application server’s administrative console is available via your Web browser over both secure and unsecure HTTP protocols. To avoid getting errors like “HTTP 404: page not found,” you must be sure that you are using the correct URL. The default URLs are:

    unsecure: http://<hostname>:8080/console

    SSL: https://<hostname>:8443/console

    where <hostname> is the system where the application server is running. You can configure different port numbers by changing the HTTPPort and HTTPSPort properties in the <WAS_CE_HOME>/var/config/config-substitutions.properties file. For example:

    HTTPPort=8080

    HTTPSPort=8443

    When you successfully connect to the administrative console, you will see the panel shown in Figure 1.

    Figure 1. Administrative console
    Figure 1. Administrative console
  8. Have you changed the administrative console’s default user name and password?

    When you install Community Edition, a default administrative user name and password are set to authorize access to the administrative console. The default user name is “system” and the default password is “manager.” Change the administrative password to help keep your system secure:

    1. From Console Navigation, under Security click Users and Groups.
    2. Under Console Realm Users, click Edit for default user system.
    3. Type in and confirm a new password.

    Keep in mind that, by default, Community Edition stores user and group information on the file system. See Modifying the Default Server Security Realmfor more information.

  9. Did the application server start successfully?

    The administrative console is dependent on other modules to run successfully. Make sure that those modules are started before launching the console. You can view the complete list of dependent modules from the application EARs portlet (Figure 2). The console EAR file is called org.apache.geronimo.plugins/console-tomcat/<version>/car, and the Parent Components column lists the components that the administrative console is dependent upon.

    Figure 2. List of dependent modules
    Figure 2. List of dependent modules

    Follow these steps to start the server:

    1. Open a terminal window.
    2. Change the directory to <WAS_CE_HOME>/bin.
    3. Type command startup.bat (Windows) or startup.sh (UNIX).

    When the server starts successfully, the output should look like Figure 3.

    Figure 3. Output for successful server start
    Figure 3. Output for successful server start
  10. Do you have network connectivity?

    To confirm your network connectivity:

    1. Verify that you can resolve host names. For example, ping another host on the network.
    2. If there is a firewall between the browser and the application server, make sure that it is configured to allow traffic. For example, if you are using SSL, make sure that the HTTPS port is open.

    A networking component can fail to start when the connection is refused. The server contains a number of networking components (for example, the GBean JMXService) that access the network during initialization. If one of these components fails to start because the connection is refused, the problem might be caused by firewall software running on the server's host. If this is the situation, configure your firewall software to consider your local host as a trusted host. Depending on the software you use, you might need to specify the trusted host several times, for example:

    • As localhost
    • As its fully qualified host name
    • As its TCP/IP address.
  11. Can you access the server using the host system’s short name?

    Regardless of how you specify the target server’s host name, Apache Geronimo uses the unqualified (short) host name during remote deployment. The client then uses this short name to start the file transfer for sending your application to the server system. If the name cannot be resolved by the network, you will see a java.net.UnknownHostException.

    You can avoid this problem by checking that you can access the host system using the short name. For example, verify that you can ping the host name using the short name. If you receive a successful response, then your name resolution service can resolve the short name to an IP address.

  12. Are the resource references defined correctly in the deployment plan?

    To deploy or distribute your Java EE asset, you define resource references in the deployment plan; examples of resources are a database or JMS. Community Edition provides several deployment plan templates for common types of Java EE assets, including:

    See Using deployment plan templates for templates and samples.

    The server will be unable to deploy or distribute your asset if it cannot resolve a reference in a Java EE deployment plan to a resource on the server. Make sure you deploy your asset with a deployment plan that defines the relationship. Some tips:

    • If you attempt to deploy your asset without a deployment plan, you will see error messages about being unable to deploy or distribute your asset. To resolve these issues, create a deployment plan so that you can successfully deploy your asset.
    • If you are using a deployment plan and you see errors during deployment, check the error message and the logs to determine which resource could not be resolved. Fix the problem by correcting the resource reference in the deployment plan.
    • Make sure the configuration identifier of a resource reference matches the configuration identifier of the resource.
    • Use a single-byte character set to name the configuration identifier; there is a known problem in Apache Geronimo that causes errors when you use a double-byte character set (such as Chinese) to name the configuration identifier.
  13. Did you use inverse class loading in production?

    Inverse class loading is useful for problem determination and testing by letting you override the default Java EE class loader hierarchy so that your module’s class library is searched before the parents are searched. You must exercise caution if you plan to use inverse class loading in production because it affects all classes and can cause conflicts when objects constructed in your module are passed to a parent for processing. In production systems, you should use hidden classes instead, and specify only those classes that can be used without conflicts.

    See Managing the classpath in the Community Edition V2.1 documentation for more information about classpaths.

  14. Did you verify class dependencies?

    If you see either of these exceptions:

    • java.lang.ClassNotFoundException
    • java.lang.ClassCastException

    then packages that your modules depend on are probably not defined and stored in the server’s repository. The server keeps common Java libraries in a repository using the same directory structure and naming conventions promoted by the Apache Maven project. If your Java EE asset depends on a library that is not already in the repository, you must update the repository to include the new library and define the dependency in your Java EE asset's deployment plan. See Adding Java libraries to the server’s repository for more information.

  15. What if I still have a problem?

    If you still have problems after following these tips, try these support resources to find solutions and answers to your questions:

These questions and answers equip you with information you can use to resolve or avoid some of the most common issues encountered when installing, configuring, and using WebSphere Application Server Community Edition V2.1. This knowledge will contribute to your success deploying your applications on Community Edition. For in-depth installation and application deployment instructions please visit WebSphere Application Server Community Edition 2.1 documentation.


Acknowledgements

Russell Wright offers his thanks to Daniel Julin for his thoughtful and thorough guidance during the transition of coordinating the WebSphere Support Authority column.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Open source
ArticleID=343773
ArticleTitle=The Support Authority: A checklist for success with WebSphere Application Server Community Edition
publish-date=10082008