IBM WebSphere Developer Technical Journal: Get started with WebSphere Application Server Community Edition

Updated for V1.0.1.1

IBM® WebSphere® Application Server Community Edition is an open source Java™ 2 Platform, Enterprise Edition (J2EE™) application server based on Apache Geronimo. This article will help you understand why you might want to use this new product, when it might be the best choice for your project, and then walks you through what you need to know to get up and running quickly with WebSphere Application Server Community Edition, from setting up your environment and choosing the right download package to deploying applications. Updated for V1.0.1.1.

Nell Gawor (ngawor@us.ibm.com), Advisory Software Engineer, IBM

Nell GaworNell Gawor is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group Advanced Design and Technology Group. She received a Masters Degree in Computer Science from the University of Illinois at Urbana-Champaign. Contact Nell at ngawor@us.ibm.com.



Lin Sun (linsun@us.ibm.com), Staff Software Engineer, IBM

Lin SunLin Sun is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group WebSphere Application Server Community Edition Development Team. She received a master's degree in information science from the University of North Carolina at Chapel Hill.



11 April 2006 (First published 07 December 2005)

Also available in Chinese Russian

From the IBM WebSphere Developer Technical Journal.

Introduction

IBM WebSphere Application Server Community Edition is a Java 2 Platform, Enterprise Edition (J2EE) application server built on top of Apache Geronimo, an open source application server created by the Apache Software Foundation.

When to use WebSphere Application Server Community Edition

When should you use WebSphere Application Server Community Edition? Depending on how you plan to use your application server, there are several scenarios when using WebSphere Application Server Community Edition (hereafter referred to as Community Edition) would be your best implementation choice; likewise, there are times when using a more robust WebSphere Application Server product would be justified, or even when using Apache Geronimo makes the most sense. For example:

  • If you need a lightweight application server as a development, test, or production platform to run your J2EE applications and desire a build that is stable, well-tested, and available with world-class support, then Community Edition would be your best choice, both technically and economically. You can be confident that you are using an application server that can run your applications and prototypes, plus Community Edition is free to download and use. You can install it and get it running in a short timeframe so you can get on with the business of evaluating and demonstrating prototypes, or developing and running applications. You can continue to use the product at no cost, purchase optional IBM support as needed, or even migrate to other WebSphere Application Server products if desired.

  • If you intend to run critical applications that require high availability, or if you want sophisticated management console and tooling capabilities to help you deploy and debug your J2EE applications, then you should explore other IBM WebSphere Application Server products. Community Edition enables you to quickly develop applications and grow them incrementally, and provides basic security, easy administration, and manual application deployment. If you are looking for more visual tooling for rapid development, WebSphere Application Server - Express may be a better choice. If you require scalability, enterprise-wide deployment, functional depth and robustness, or if you have high transaction volumes, want autonomic application deployment, or business goal-based application prioritization, look into WebSphere Application Server, WebSphere Application Server Network Deployment, or WebSphere Extended Deployment.

  • If you want to improve or customize your application server's implementation, add features, or fix bugs, then using Apache Geronimo might be the way to go for you to obtain all the relevant source code and build your own application server. Additionally, you could contribute your updates to the Apache Geronimo community so that your work can be used and leveraged by others.

Key features of Community Edition

Apache Geronimo is the open source J2EE application server project developed by the Apache Software Foundation, bringing together leading technologies (for example, Apache Tomcat, ActiveMQ, Tranql, OpenEJB, and so on) from the broader open source community to support the J2EE stack. (For a complete list of technologies, see the Community Edition documentation in Resources). Apache Geronimo is Apache licensed, highly customizable, and community driven.

Community Edition is a lightweight J2EE application server built on top of Apache Geronimo Version 1.0, with key features added by IBM, and available with IBM world-class support. Community Edition is largely made up of Apache Geronimo Version 1.0, with the balance of the product comprised of IBM added value. Key features of Community Edition include:

  • J2EE 1.4 certification with support for both IBM Java Virtual Machine (JVM) and Sun® JVM. IBM JVM is an industrial-strength performance leader and also the same JVM shipped with other WebSphere Application Server products.
  • Apache Tomcat as the default Web container.
  • Easy-to-use, fully supported administrative console.
  • Supports Web tier clustering and load balancing.
  • Supports hot deployment and remote deployment via both console and the Eclipse Integrated Development Environment.
  • IBM Cloudscape V10.1 database is embedded in Community Edition and supported for use in development and production.
  • Supports DB2®, Oracle® databases, Microsoft® SQL Server, and MySQL database server. IBM DB2 JDBC driver is included in Community Edition.
  • InstallShield installation with small footprint download packages. Community Edition can typically be installed in less than five minutes; ISV vendors can easily embed Community Edition.
  • IBM WebSphere product look and feel.
  • Migration aids from Gluecode Standard Edition, Apache Geronimo, and Apache Tomcat to Community Edition, and from Community Edition to other WebSphere Application Server products.
  • IBM LDAP integration.
  • Eclipse plug-in J2EE profiling feature that alerts you when you are using non-J2EE APIs in your application.
  • Detailed and complete documentation assets.
  • Liberal product license; users can freely use Community Edition in development, testing, and deployment.
  • IBM world-class product support available for a version for 1.5 years. (IBM Apache Geronimo support requires more frequent updates since it is tied closer to the Apache Geronimo community.)

Before you continue: This article was written for WebSphere Application Server Community Edition V1.0, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.


Download and install Community Edition

Community Edition system prerequisites:

  • A recommended operating system:
    • Windows® platforms on Intel® Architecture - 32 bit (IA-32) processors
      • Microsoft Windows Server 2003 with Service Pack 1 (SP1)
      • Microsoft Windows XP Professional Edition with Service Pack 2 (SP2) when restricted to a development environment
    • Linux® platforms on Intel Architecture - 32 bit (IA-32) processors
      • Red Hat Enterprise Linux Version 3 Update 5 through Update 7 (3u5-3u7) WS, ES, AS
      • Red Hat Enterprise Linux Version 4 Update 1 through Update 3 (4u1-4u3) WS, ES, AS
      • Novell® SuSE Linux Enterprise Server 9 Service Pack 2 through Service Pack 3 (SP2-SP3)
      • RedFlag Data Center Enterprise/Expert 5.0
    • Linux® platforms on PowerPC (PPC-64) processors
      • Red Hat Enterprise Linux Version 4 Update 1 through Update 3 (4u1-4u3) WS, ES, or AS
      • Novell SuSE Linux Enterprise Server 9 Service Pack 2 through Service Pack 3 (SP2-SP3)

Community Edition can run on other platforms, but one of these environments must be used to obtain support, if desired:

  • A supported Java environment:
    • IBM Java 2 Standard Edition (J2SE) Software Development Kit (SDK) Version 1.4.2 SR4-1
    • IBM Java 2 Standard Edition (J2SE) Java Runtime Environment (JRE) Version 1.4.2 SR4-1
    • Sun® Microsystems Java 2 Standard Edition (J2SE) Software Development Kit (SDK) Version 1.4.2 build 1.4.2_10
    • Sun Microsystems Java 2 Standard Edition (J2SE) Java Runtime Environment (JRE) Version 1.4.2 build 1.4.2_10

If you do not already have a supported Java environment, you can download an installation bundle that includes the recommended IBM J2SE SDK.

Download and install

Downloading and installing Community Edition is relatively simple. You can download the Community Edition software for free from developerWorks. Download the approproate version of Community Edition server based on on your platform and whether or not you already have a recommended Java Runtime Environment (JRE) or Java Software Development Kit (SDK) installed. If you do not have a supported JRE, be sure to select one of the packages labelled "and 32bit IBM SDK".

If you already have a supported Java environment, download the server-only wasce_setup file for your platform, then install Community Edition simply by running the wasce_setup file. Otherwise, you need to expand (untar or unzip, depending on your platform) the wasce_ibm142sdk_setup file and run the setup-ibm-sdk-142 file or IBMJava2-142-ia32-SDK file (depending on your platform) to create a supported Java environment before you can run the wasce_setup file.


Starting and stopping the server

To start

On a Windows 2003 or XP platform, start the server by selecting Start => Programs => IBM WebSphere => Application Server Community Edition => Start the server. This will launch the startup script located in wasce_install\bin\startup.bat, where wasce_install is the Community Edition installation directory.

On Linux, start the server by running startup.sh at wasce_install/bin, where wasce_install is the Community Edition installation directory. The server will be started in the background and you can check the wasce_install/var/log/geronimo.out for console output.

Figure 1 shows the Geronimo Application Server started message that displays when the server successfully starts on Windows platform.

Figure 1. Community Edition server started
Figure 1. Community Edition server started

To stop

On a Windows 2003 or XP platform, stop the server by selecting Start => Programs => IBM WebSphere => Application Server Community Edition => Stop the server. This will launch the shutdown script located in wasce_install\bin\shutdown.bat, where wasce_install is the Community Edition installation directory.

On Linux, stop the server by running shutdown.sh at wasce_install/bin, where wasce_install is the Community Edition installation directory.

Type the predefined username system and password manager, and the server will shutdown momentarily.


Deploy your first application

One of the files that is available when you download Community Edition is a ZIP file containing sample J2EE applications. Using these samples is a great way to get started with Community Edition. By deploying the simplest of these applications, the Hello sample, you can quickly learn the basics of deploying your own applications to Community Edition.

Using the samples and command deployer

  1. Download the wasce_samples zip file from the product download page and unzip it to a known location.

  2. Within the samples\wasce directory, the hello directory contains both the source and binary forms of the application. If you navigate into src/webapp, you will see that this is a very simple Web application. The main file is a Java ServerPages file, index.jsp (Listing 1).

    Listing 1. index.jsp
    <%@ page contentType="text/html;charset=UTF-8" language="java" %>
    <html>
      <head>
          <jsp:useBean id="datetime" class="java.util.Date" />
          <title>Hello IBM WebSphere Application Server Community Edition Version 1</title>
      </head>
      <body>
          <h2>Welcome to IBM WebSphere Application Server Community Edition Version 1</h2>
          <p>Congratulations on running this very simple demo application on ${datetime}.</p>
      </body>
    </html>

    The Hello application also has a standard J2EE-compliant deployment descriptor (Listing 2). The Hello application is a standard Web application, and so no changes should be necessary for it to run on Community Edition or any other J2EE application server.

    Listing 2. web.xml
      <?xml version="1.0" encoding="UTF-8"?>
      <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
    	http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" />

    The Hello application also has a Geronimo Web deployment plan, which is optional since this is a very simple Web application. However, with the Geronimo Web deployment plan, the name of the module is defined as: com/ibm/websphere/ce/samples/hello (rather than hello-1.0 when the Hello application is deployed without the geronimo-web.xml file), and the context root as: /hello (instead of /hello-1.0 when the Hello application is deployed without the geronimo-web.xml file).

    Listing 3. geronimo-web.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app configId="com/ibm/websphere/ce/samples/hello" 
        xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0" 
        xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.0" 
        xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.0" 
        xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.0"
    >
      <context-root>/hello</context-root>
      <context-priority-classloader>false</context-priority-classloader>
    </web-app>
  3. Start the server before deploying the application.

  4. Open another command prompt and navigate to the wasce_install\bin or wasce_install/bin directory, depending on your platform.

  5. Execute the command:

    deploy.[bat|sh] --user system --password manager deploy sample_install
    \wasce\hello\target\hello-1.0.war

    When the deployment command finishes, this message will display to indicate that the deployment was successful; "hostname" is replaced with your machine's hostname. Notice that the name of the module and context root are the same as the config ID and context root specified in the Geronimo Web deployment plan (Listing 3).

        Deployed com/ibm/websphere/ce/samples/hello @
        http://hostname:8080/hello
  6. Open http://localhost:8080/hello in a new browser window. You should see a message congratulating you on deploying the application successfully (Figure 2).

    Figure 2. The Hello application main page
    Figure 2. The Hello application main page
  7. To undeploy the hello application, execute the following command at the wasce_install\bin or wasce_install/bin directory, depending on your platform:

    deploy.[bat|sh] --user system --password manager undeploy com/ibm/websphere/
    ce/samples/hello

    You should see a message indicating that you have successfully undeployed the application. (In cases where you may not remember the name of the module containing the application, you can execute the list-modules command to see all the modules currently deployed on the server.)

You have successfully deployed and run the application. It doesn't get much easier than that. If you deploy an application that is more complex (for instance, one that has dependencies on external libraries, or one that needs to map any resource references to actual resources), you will need to provide extra information in the deployment plan.

Using the administrative console

You can also use the administrative console to deploy the Hello application. Open http://localhost:8080/console in a new browser window and use the predefined username system and password manager to logon to the administrative console.

  1. To deploy the Hello application, click on Applications => Deploy New. At the Install New Applications portlet, navigate to the hello-1.0.war file and click Install.

    Figure 3. Install new application using the administrative console
    Figure 3. Install new application using the administrative console
  2. To undeploy the Hello application, select Applications => Web App WARS. At the Installed Web Applications portlet, click the uninstall link next to the com/ibm/websphere/ce/samples/hello module.

Using hot deployment

  1. To deploy the Hello application, simply copy the sample_install\wasce\hello\target\hello-1.0.war file to the wasce_install/deploy directory. The hot deployment tool will automatically deploy the Hello application.

  2. To undeploy the Hello application, remove the hello-1.0.war from the wasce_install/deploy directory.

Refer to the product documentation (see Resources) to see if hot deployment is appropriate for you.


Troubleshooting

When you encounter a problem, the first place to look is in the logs.

Install log

  • Windows: wasce_install.log can be found in the user's home directory (for example, C:\Documents and Settings\userID where userID is replaced with the user name used to log on).
  • Linux: wasce_install.log can be found in the common log directory, /var/log.

Server Logs

Community Edition server logs can be found in the installDir/var/log directory where installDir is the server's installation directory.

  • server.log is the log that contains server startup, deployment, confirguration, application running, and server shutdown data.
  • client.log is the J2EE client container log.

Default database log

IBM Cloudscape Version 10.1 is the default system database and its log, derby.log, can be found in the installDir/var/log directory, where installDir is the server's installation directory.

Optional technical support

IBM technical support teams offer three levels of fee-based support for Community Edition as an annual subscription. Visit the Technical Support offerings page for details.


Next steps

Experiment with sample applications

Additional sample applications are provided in the sample download ZIP file. Working with these samples has proven to be a good way to continue learning an application server. Read the sample_install\readme.txt for a brief description of each sample application provided with Community Edition.

Read the documentation

Check out the product documentation (see Resources), which covers everything else you need to know about Community Edition, including quick start, choosing your strategy, concepts, tasks, references, video demonstrations and frequently asked questions.


Conclusion

The information provided in this article should be able to get you started installing and using WebSphere Application Server Community Edition. Use the examples described here and the samples provided with the software download to experiment, learn, and be productive. The Resources listed below will also be helpful as you set forth on your open source adventure. So, go ahead and download WebSphere Application Server Community Edition now -- and have fun!

Resources

Learn

Get products and technologies

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=99831
ArticleTitle=IBM WebSphere Developer Technical Journal: Get started with WebSphere Application Server Community Edition
publish-date=04112006