...

GERONIMO_HOME versus GERONIMO_SERVER

Simply put, GERONIMO_HOME is the path to the server binary installation and GERONIMO_SERVER is the path to the server run-time configuration. GERONIMO_HOME is the path to where Geronimo was installed which every instance references, and every Geronimo instance defines its own GERONIMO_SERVER as the path to the configuration for the instance.

We define GERONIMO_SERVER in order to have the Geronimo start procedures startup an instance.

Path Resolution

GERONIMO_HOME is obtained during startup relative to the directory Geronimo is installed in. By default, if the user does not define GERONIMO_SERVER it is set to GERONIMO_HOME. If the user defines GERONIMO_SERVER it is attempted to be resolved to an absolute path in the following ways:

1. First, as an absolute path IFF GERONIMO_SERVER is absolute
   • GERONIMO_SERVER
2. Second, as a relative path to GERONIMO_HOME IFF GERONIMO_SERVER is not absolute
   • GERONIMO_HOME/GERONIMO_SERVER

Technical Terms

Skip this sub-section if you do not care about the technical internals of Geronimo's use of GERONIMO_HOME versus GERONIMO_SERVER

Inside Geronimo there is a concept of home, base, and server, with corresponding java properties org.apache.geronimo.home.dir and org.apache.geronimo.server.dir. base and server are the same, but Geronimo references base in general to reference the location for run-time configuration. The definition of server is user provided, and redefines base.

When Geronimo runs, home and base properties are defined relative to the installation directory of Geronimo. When a user starts up a Geronimo instance, the user defines the server property. Defining the server property triggers Geronimo to change its base from home to server thus starting up a Geronimo instance.

Several internal libraries used by Geronimo define two categories of properties as home and base, and Geronimo defines these further when server is defined. Outside of running multiple Geronimo instances base properties can be used to separate the binary installation from the user-modifiable configuration for a single server installation when that is desirable in some disk layout strategies.

The layout of a Geronimo instance

• <GERONIMO_HOME>/
  • bin
  • jsr88
  • lib
  • schema

The repository is shared, and contains lots of basic and important libraries are required to bootstrap server. It is possible recommended to configure second repositories, one for each instance. See Configuring multiple Repositories.

• <GERONIMO_HOME>/
  • repository (This is the primary shared repository for bootstrapping Geronimo instances)

Each instance gets its own copy of the following at <geronimo_home>/<instance_name> . These are etc is read-only and var is read-write and . Both are necessary for each Geronimo instance.

• <GERONIMO_SERVER>/
  • etc
  • var

These are also read-write but are not part of the minimally necessary directories and files for running a Geronimo instance, but may be desired. The deploy and repository directories will be automatically created when you start Geronimo if they do not already exist.

• <GERONIMO_SERVER>/
  • repository (
  this
  • This is the local repository under <geronimo_home>/<instance_name>, and is not the same as the primary shared repository)
  • deploy
  • hotbundles

The bin, lib and schema directories are read-only, and thus are shared between instances. The repository is also shared, which means that an application deployed in one instance will show up in the list of deployed modules for all instances. Thus creating the second repository for each instance should be desiredis recommended to keep deployments local to the Geronimo instances. See Configuring multiple Repositories

Here is an example layout of what it would look like to have installed one Geronimo instance named "foo-server".

/opt/geronimo3    - GERONIMO_HOME
|-- bin           - read-only
|-- foo-server    - GERONIMO_SERVER
|   |-- etc           - read-only for the instance
|   |-- repository    - read-write (The instance's local repository you do want to deploy to)
|   `-- var           - read-write
|-- jsr88         - read-only
|-- lib           - read-only
|-- repository    - read-write (The primary shared repository you don't want to deploy to)
`-- schema        - read-only

Creating a new server instance

...

To create an instance named foo-server do the following. All your instance data will be put in <geronimo_home>/foo-server. All the directories named below are relative to <geronimo_home>.
Follow the procedures as below:

1. Create a directory foo-server under <geronimo_home>.
2. Copy var and etc directories to foo. You can use the command deploy:new-server-instance to help you with this step.
3. Recommended: create foo-server/repository and set it up as a second repository for the Geronimo instance. See Configuring multiple Repositories
4. Edit foo-server/var/config/config-substitutions.properties and change the portOffset. Try using any integers such as 1, 2, 10, 20, 30.. for various instances.

Running an instance

1. Set the org.apache.geronimo.server.name system property to define a server name GERONIMO_HOME environment variable to define the server instance directory before you start the server. This system property is null by default, defining the server instance at <geronimo_home> as the default instance. Use the syntax -Dorg.apache.geronimo.server.name=foo variable will be set to GERONIMO_HOME as default if not defined. Set GERONIMO_SERVER=foo-server to change the server name to an instance named foo-server located at <geronimo<GERONIMO_home>HOME>/foo. Add this to your GERONIMO_OPTS environment variable:-server, or GERONIMO_SERVER=/opt/geronimo/foo-server to set the absolute path.

• On a Windows system: set GERONIMO_OPTS SERVER="foo-Dorg.apache.geronimo.server.name=foo"
• On a Unix-like system: export GERONIMO_OPTSSERVER="foo-Dorg.apache.geronimo.server.name=foo"

1. Start the server using startup

   No Format
   borderStyle solid
   <geronimo_home>/bin/startup

2. To shutdown this instance, use the port number of RMI Naming port (default 1099). For the new instance foo, the port number should be 1099 plus portOffset specified in foo/var/config/config-substitutions.properties.

   No Format
   borderStyle solid
   <geronimo_home>/bin/shutdown --port <RMI_port_num>

3. To deploy applications to this instance use the port number of RMI Naming port

...

• First download the Geronimo bundle distribution
• Determine what you want GERONIMO_HOME to be. We will use /opt/geronimo3 for this example.
• Unpack the Geronimo bundle, and move the unpacked directory to /opt/geronimo3
• We'll create two Geronimo instances named gserv1 and gserv2
  • Create the Geronimo instance directories as /opt/geronimo3/gserv1 and /opt/geronimo3/gserv2
  • Copy the directories var and etc to each instance directory
  • Create a repository directory within each instance directory and set it up as a second repository for the corresponding Geronimo instance. See Configuring multiple Repositories
  • Modify the gservNgserv(1|2)/var/config/config-substitutions.properties file for each Geronimo instance changing the PortOffset. We'll set the PortOffset for gserv1 to 100 and the PortOffset for gserv2 to 200 for our example.
  • Create a start script in each Geronimo instance directory to make it easier to start each instance
    • /opt/geronimo3/gserv1/start.sh

      No Format
      borderStyle solid
      #!/bin/bash # Geronimo start script # instance: gserv1 # Uncomment this to explicitly set Geronimo's runtime Java #JAVA_HOME=/usr/jdk1.6.0_25 #PATH=${JAVA_HOME}/bin:${PATH} export GERONIMO_HOME=/opt/geronimo3 export GERONIMO_SERVER=${GERONIMO_HOME}/gserv1 export GERONIMO_OPTS=-Dorg.apache.geronimo.server.dir=${GERONIMO_SERVER} cd ${GERONIMO_SERVER} # Normal startup ${GERONIMO_HOME}/bin/startup # Interactive startup #${GERONIMO_HOME}/bin/geronimo run

    • /opt/geronimo3/gserv2/start.sh

      No Format
      borderStyle solid
      #!/bin/bash # Geronimo start script # instance: gserv2 # Uncomment this to explicitly set Geronimo's runtime Java #JAVA_HOME=/usr/jdk1.6.0_25 #PATH=${JAVA_HOME}/bin:${PATH} export GERONIMO_HOME=/opt/geronimo3 export GERONIMO_SERVER=${GERONIMO_HOME}/gserv2 export GERONIMO_OPTS=-Dorg.apache.geronimo.server.dir=${GERONIMO_SERVER} cd ${GERONIMO_SERVER} # Normal startuo ${GERONIMO_HOME}/bin/startup # Interactive startup #${GERONIMO_HOME}/bin/geronimo run

  • On linux, make the start script is executable with chmod: chmod 755 start.sh
• Your Geronimo installation file structure should look something similar to this:

  No Format
  borderStyle solid
  /opt/geronimo3 |-- LICENSE |-- NOTICE |-- README.txt |-- RELEASE_NOTES-3.0-SNAPSHOT.txt |-- bin |-- deploy |-etc- etc |-- gserv1 | |-- etc | |-- repository | |-- start.sh | `-- var |-- gserv2 | |-- etc | |-- repository | |-- start.sh | `-- var |-- hotbundles |-- jsr88 |-- lib |-- +repository+ |-- schema `-- -var-

  It is suggested that in GERONIMO_HOME etc and var are removed and repository is made read-only
• Finally you can start up each instance by executing their associated start script you just created in the previous step

...