IBM® WebSphere® Application Server Community Edition (hereafter called Community Edition) Version 1 is a lightweight Java™ 2 Platform, Enterprise Edition (J2EE) application server. It is built on top of Apache Geronimo Milestone 5, an open-source application server created by the Apache Software Foundation. In Part 1 of this two-part series, you will learn the Community Edition directory structure, how to startup the server with different options, and how to use different commands and options provided by the deployer. In addition, you will master configuring the server, Tomcat default ports, logging properties, and recovering your server from system failure. In Part 2, you will learn how to configure databases (including IBM Cloudscape, Oracle®, Microsoft® SQL server, and DB2®), Java Message Service (JMS), LDAP, SSL, and CORBA over IIOP.
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.
Community Edition directory structure
To install Community Edition, ensure you meet the the system requirements and follow the download and installation instructions provided in Get started with WebSphere Application Server Community Edition. After the installation, the following subdirectories are created:
- bin/: This directory contains the server.jar, server startup scripts, deployer.jar, client.jar, and IBM Cloudscape ij tool script. These files allow you to start the server, run the deploy tool, start the J2EE client, and start the Cloudscape ij tool, respectively.
- config-store/: This directory holds resources and application modules, some of which are started along with the Community Edition server. It contains the index.properties file. This file maps modules to the numeric names of the config-store subdirectories in which they are contained.
- doc/: This directory contains the default server, Tomcat, database, activemq, client, CORBA, and other system plans that are used by the server initially.
- graphics/: This directory contains the graphics that are used by the server welcome page and the administrative console.
- lib/: This directory contains the kernel jars, which are used to provide kernel services and load other service, resource, and application modules.
- license/: This directory contains the license and notices for Community Edition.
- repository/: This directory contains shared libraries, such as database drivers and JMS drivers, which are used by many application modules. Each library is loaded when a module that depends on it is loaded.
- schema/: This directory contains schema definitions for XML deployment descriptors and configuration files.
- var/: This directory contains log files, transaction logs, and security files as well as information about the configurations used when the server was last running.
- _uninstall/: This directory contains information that will be used by the uninstaller.
Starting the WebSphere Application Server Community Edition server
When starting the server, there are different options you can use to control the amount of output:
-quiet: This suppresses the progress bar. The server will output only messages of level WARN or higher.
-v: The server will output messages of level INFO or higher.
-vv: The server will output messages of level DEBUG or higher.
Selectively start up configurations
If you run into problems and you need to isolate the cause, or if Community Edition will not start, you can override the list of configurations normally started without permanently changing it. To do this, pass the configuration or configurations to start as arguments when starting the server. For instance, if you have an application module called
hello and you are having problems, you may want to try running only that module and its dependencies to make sure the problems are not coming from another application module (Listing 1).
java -jar server.jar hello
This only works as expected if the configuration has correctly declared its dependencies, or you already know exactly what configurations to start. Otherwise, the module may fail unexpectedly because not all the necessary pieces are started. For instance, if you are having a problem with deployment, you might decide you want to run only the
org/apache/geronimo/RuntimeDeployer configuration. Even if the configuration starts successfully, when you actually try to deploy, the deploy fails and tells you that the server has to be running to use that command. The reason is that the RuntimeDeployer does not work without other configurations, such as the JMX infrastructure, but does not have explicit dependencies on those configurations. Therefore, not everything needed to run the RuntimeDeployer is actually started. Running only part of the server is not recommended because you may cause more problems, which hide the true reasons you are trying to solve.
Keeping the server from stopping
If it is a problem to keep the same user logged in all the time, you can run Community Edition in the background on Linux. On Windows, your only option is to lock the machine to keep the current user logged in.
Using the deployer
The Community Edition deployer helps you manage your application deployments with various commands. To invoke the deployer, the format is:
deploy.[bat|sh] [general options] command [command options]
For more detailed information on any one command, type:
deploy.[bat|sh] help command
The help information is not necessarily accurate, however. For instance, many of the deployer commands can only be run when the server is started, but the help documentation says they can work when the server is stopped. When in doubt, refer to the Community Edition documentation.
For a full list of the general options, type:
deploy.[bat|sh] help options
The general options (for any command) are:
- --uri: This is the URI of a running server to contact. You can use this to run the deployment tool against a server
that is not running on the default port (1099) on localhost. The URI format is:
- --driver: You can use the deployer tool not only with Community Edition, but with any JSR-88-compliant server. For servers other than Community Edition, you need to provide the location of the jar file containing the JSR-88 deployment implementation classes.
- --user: This is the username to use when authenticating. If no username is provided, you will be prompted. The default username for Community Edition is "system".
- --password: This is the password to use when authenticating. If no password is provided, Community Edition will try to connect without a password. If that fails, you will be prompted. The default password for Community Edition is "manager".
- --syserr: If true, errors will be logged to the syserr device. The default is false.
- --verbose: If true, output debug information to standard out. The default is false.
Available deployer commands and their usage
Common commands are:
deploycommand normally takes a module and a plan for how to deploy that module. It validates the module and plan, installs the module on to the server, and starts the module. If the module is very simple and you are willing to accept all of the defaults, it may not be necessary to have a plan. Also, instead of providing the plan as a separate argument, it can also be part of the module itself. If the plan is packaged as part of the module, its location depends on the type of module:
Module type Plan location Web module WEB-INF/geronimo-web.xml EJB module META-INF/openejb-jar.xml Resource adapter META-INF/geronimo-ra.xml Client application META-INF/geronimo-application-client.xml J2EE application META-INF/geronimo-application.xml
deploycommand, like many of the others, has additional options to cover the case where you want to work with multiple deployment targets. Because multiple target support is so limited at this point, we will not cover those additional options here.
redeploycommand is equivalent to running
undeploy, and then
deploy. The module will be started after redeployment even if the module was stopped before. While the redeploy is occurring, some portions of the application may be available to clients while others may be unavailable, causing requests to fail.
startcommand starts a module that has already been deployed. You can list multiple module IDs to start them all.
stopcommand stops a module that has already been deployed. You can list multiple module IDs to stop them all. After stopping, the module cannot be accessed until it is started again.
undeploycommand stops a module and removes all its deployment information from the server. It will not be accessible unless it is deployed again. Unlike
redeploy, you can specify multiple modules to undeploy.
Other commands are:
distributecommand is similar to deploy. The difference is that it also makes the module available but, unlike deploy, does not start it. This means you can use
distributewhen the server is not started.
list-modulescommand lets you view all the available modules. For Web modules, you can use the
list-modulescommand to find out their Web address (URL). You can specify either
--stoppedto see only those modules in that state. The server must be running to use this command.
list-targetscommand lists the places where you can deploy modules. Each target is either a cluster or a server and represents one configuration store. However, support for multiple configuration stores is not fully tested. There is no support for a cluster as a target so this command is not useful yet. The server must be running to use this command.
The deployer works even when the server is not running, but there is not much you can do. You can only distribute an application, which means Community Edition will validate that it is a valid application and install it. None of the other commands (besides the
package command, which is not discussed here) will work when the server is not running.
Understanding the config-store directory
The config-store directory, located at the wasce_install_root\config-store directory, holds resources and application modules, some of which are started along with the Community Edition server. The available configuration modules are listed in the wasce_install_root\config-store\index.properties, which provides the mapping between the module configuration name and the numeric config-store subdirectories in which they are contained. After your J2EE application has been deployed successfully, you will see a serialized version of its configuration in the config-store/assigned number directory.
By looking at the index.properties file, you can find out the numeric directory name that is assigned by the server when the J2EE application is deployed. For example, if you deployed the hello sample program provided by Community Edition, you will see the hello program assigned to a numeric ID:
#Wed Nov 16 09:28:46 EST 2005 org/apache/geronimo/applications/Welcome/Tomcat=18 org/apache/geronimo/Tomcat=7 org/apache/geronimo/SampleSecurityRealm=17 org/apache/geronimo/RMINaming=4 org/apache/geronimo/ActiveMQServer=15 org/apache/geronimo/TomcatRuntimeDeployer=9 org/apache/geronimo/DefaultDatabase=13 hello=44 ...
This means the serialized version of the hello program's configuration is in the config-store/44 directory. The first line indicates the date and time last time the index.properties file was last written. There is also an index.backup file that contains the backup version of the index.properties file by the server. The contents of the config-store directory are maintained by the deployment tools automatically, so it is not recommended that system administrators modify this directory.
Understanding the config.list file
The config.list file, located in the wasce_install_root\var\config directory, contains the resources and application modules that were running when the server was previously shutdown. If the server is started without special direction, the server will read the config.list to determine what resources and application modules it should start. If you do not make any changes, you see the following default start sequence in the config.list file from top row to bottom row.
|Configuration ID||Initial default plan||Usage|
|org/apache/geronimo/System||system-plan.xml||Contains the basic services needed for Community Edition to operate. Should always be started.|
|org/apache/geronimo/RMINaming||naming-server-plan.xml||Contains the RMI Naming server configuration.|
|org/apache/geronimo/Server||j2ee-server-plan.xml||Contains the service necessary for Community Edition to act as a J2EE server.|
|org/apache/geronimo/Security||j2ee-security-plan.xml||Contains the security configuration of the server. If you are looking for a security realm sample to use in your own applications, check out the j2ee-secure-plan.xml file.|
|org/apache/geronimo/SystemDatabase||system-database-plan.xml||Starts the embedded IBM Cloudscape database server, which listens on port 1527 by default.|
|org/apache/geronimo/SystemJMS||system-jms-plan.xml||Starts the JMS connection factory and default connection queues.|
|org/apache/geronimo/RuntimeDeployer||j2ee-runtime-deployer-plan.xml||Contains the deployment configuration of the server.|
|org/apache/geronimo/TomcatRuntimeDeployer||j2ee-tomcat-runtime-deployer-plan.xml||Contains the Tomcat Web module builder configuration.|
|org/apache/geronimo/applications/Welcome/Tomcat||welcome-tomcat-plan.xml||Starts the Community Edition Welcome Page.|
|org/apache/geronimo/Console/Tomcat||webconsole-tomcat-plan.xml||Starts the Community Edition Administrative Console (Technial Preview).|
You can issue the following deployer command to find out what modules have started:
deploy.[bat|sh] --user system --password manager list-modules --started
Output of the deploy list-modules command
Found 12 modules + org/apache/geronimo/applications/Welcome/Tomcat @ http://LinT42:8080/ + org/apache/geronimo/Tomcat + org/apache/geronimo/RMINaming + org/apache/geronimo/ActiveMQServer + org/apache/geronimo/TomcatRuntimeDeployer + org/apache/geronimo/Server + org/apache/geronimo/Security + org/apache/geronimo/SystemDatabase + org/apache/geronimo/SystemJMS + org/apache/geronimo/RuntimeDeployer + org/apache/geronimo/Console/Tomcat `-> geronimo-console-standard-1.0-M5.war @ http://LinT42:8080/console-standard `-> geronimo-console-framework-1.0-M5.war @ http://LinT42:8080/console + org/apache/geronimo/System
You may find it strange that you do not see org/apache/geronimo/Tomcat and org/apache/geronimo/ActiveMQServer listed in the config.list file, but they have actually started. The parentId of org/apache/geronimo/applications/Welcome/Tomcat and org/apache/geronimo/Console/Tomcat is org/apache/geronimo/Tomcat. Therefore, org/apache/geronimo/Tomcat will be started before the welcome page and console page start, based on the dependency injection deployment architecture of Community Edition. The situation is the same for org/apache/geronimo/ActiveMQServer server, which will be started before org/apache/geronimo/SystemJMS is started.
Using config.xml to configure server attributes
If you want to change the ports and host names of different servers like Tomcat, RMI, Cloudscape server, or configure your own CORBA properties, you can change the initial configuration provided by Community Edition. Config.xml, located in the wasce_install_root\var\config directory, is designed to store system administrators' own customized configuration. You can customize all the server configurations in config.xml, either by modifying the default configurations (RMINaming, RuntimeDeployer, Tomcat, Server, Security, ServerCorba, and ActiveMQServer GBeans) provided in the config.xml that comes with Community Edition, or by adding your own configurations. When the server starts next time, it reads the configuration from the config.xml file and applies it to the config store. The configuration changes will not be written back into the initial configuration files located in the wasce_install_root\doc\plan directory, which you want to remain intact. No matter what you do, do not forget to backup your server first! See Recovering from a system failure for more information.
The example below shows how to change the Tomcat server Web container from running on the default port number 8080 to run on 80 instead.
Tomcat WebConnector configuration in config.xml
<configuration name="org/apache/geronimo/Tomcat"> <gbean name="TomcatWebConnector"> <attribute name="host">0.0.0.0</attribute> <attribute name="port">80</attribute> <attribute name="redirectPort">8443</attribute> <attribute name="catalinaHome">var/catalina</attribute> </gbean> ... </configuration>
Save the config.xml file and restart the server. You must restart the server for the change to take effect because server will only read the config.xml during server initialization. You can also change the other attributes' value as needed. However, it is not a good idea to change the configuration name or GBean name. You may notice that in the same directory, there is also a file called config.tomcat.xml. This file contains sample configuration settings for running the server with Tomcat as the Web container and it is not used when server starts. If you had changed the configuration and wanted to return to the default Tomcat settings, you would copy this file over your existing config.xml file.
Logging and system recovery
When you encounter a problem, the best place to look is in the log files in wasce_install_root/var/logs. See Get started with WebSphere Application Server Community Edition for more information about the logs and what each one contains.
Each log has a corresponding -log4j.properties file that dictates where the log file is, how much detail is written to the log file, and what format it is in.
The line you will most likely be the most concerned with is
log4j.appender.FILE.threshold=. By setting this to
DEBUG, you can control what is
written into the log. For more information on the Log4j format, see
Log4j delivers control over logging.
Recovering from a system failure
Community Edition does not have a system for managing configuration changes. If a mistake is made, or the configuration becomes corrupted, it is difficult to recover. The best thing to do is to make regular backups of your Community Edition configuration directories.
- When your Community Edition is in the state you wish to backup, make sure the server is stopped.
- Make copies of your config-store and var/config directories. You can store these in a zip file for convenience.
- When you need to return your server to the desired state, make sure the server is stopped.
- Restore the config-store and var/config directories by first deleting the existing directories, and then unzipping or copying the older directories into the their location.
- Start the server. The server startup configuration should be in the state it was in when you backed it up. Changes that were made to the repository or logging properties may still affect the overall state of the server.
Part 1 of this two-part series provided an overview of what you need to know to administer Community Edition V1. Part 2 of this series covers how to configure:
- Database resources, including IBM Cloudscape, Oracle, Microsoft SQL 2000, and DB2
- JMS resources
- CORBA over IIOP
Now that you have the information you need to get started with system administration, you can successfully manage your Community Edition server.
- IBM WebSphere Developer Technical Journal: Get started with WebSphere Application Server Community Edition V1
- Windows Deployment and Resource Kits (run Community Edition as a Windows service)
- Log4j delivers control over logging: The open source log4j API for Java offers fast, efficient log services
- IBM WebSphere Application Server Community Edition product documentation
- IBM WebSphere Application Server Community Edition resources
- Apache Geronimo project resources
- Apache Geronimo and IBM WebSphere Application Server Community Edition forums
Get products and technologies
- Download the latest version of IBM WebSphere Application Server Community Edition
- Download an earlier version of IBM WebSphere Application Server Community Edition
- IBM WebSphere Application Server Community Edition technical support offerings
- Participate in the discussion forum.
- developerWorks blogs: Get involved in the developerWorks community.