This document contains the following sections:

Introduction

The Extensible Administration Console is a new Administration Console designed to mirror the flexibility of Geronimo's architecture. While the previous console was static, allowing configuration only for pre-defined components, the new Extensible Console changes dynamically with the components installed on your server.

This framework allows Geronimo plugin developers to package extensions to the Administration Console (called ACEs) with their components. On installation of a plugin, this new content will automatically be added to the Extensible Administration Console, so that the user can manage all of the configuration and tools from one place.

Objective

After reading this document, a Geronimo user will be able to

1. Install the Extensible Administration Console into a Geronimo minimal assembly (Tomcat or Jetty)
2. Download and install an Administrative Console Extension

Scope

This document covers installing Geronimo's Administration Console into a Geronimo minimal assembly and the process to install an ACE plugin. For more information about the underlying architecture and ACE development, see the Administration Console Extension Developer's Guide.

Who should read this document

These instructions are geared towards a basic user of Geronimo who wants to install new components on the administration console. Knowledge of the internal workings of the server is not necessary.

Assumptions

The reader should be familiar with the Geronimo application server and its applications. The reader should also be familiar with the basics of Geronimo's plugin framework. For more information about the architecture, this guide may also be a valuable resource: http://media.wiley.com/product_ancillary/31/04717854/DOWNLOAD/Pro_Apache_Geronimo_ch17.pdf.
The reader should have Apache Geronimo 2.1 Minimal ("Little-G") installed and running, with either Tomcat6 or Jetty6 as the web container. The Java EE assemblies already have the Extensible Aministration Console installed. For more information about getting started or getting updated to the right version, see this website: http://cwiki.apache.org/GMOxDOC21/installation.html.

Installation Planning

This section will prepare the user to install an ACE by providing the necessary terminology and introducing the installation scenarios that will be discussed.

Common Terminology

Plugin - An archive file (.car or .war) that can be installed into Geronimo to install a specific new service, such as ActiveMQ. For more about plugins, or to look at available plugins, check out geronimoplugins.com or geronimoplugincentral.org.
.CAR file (Configuration ARchive) - An archive file that stores Geronimo-specific configurations, as well as the classes, libraries, web pages, and other information associated with an application.
.WAR file (Web ARchive)- An archive file that contains a web application, including all of its classes, libraries, HTML and JSP pages, and other information. It can be deployed on any Java Enterprise compatible servlet container.
ACE (Administration Console Extension) - An archive file (either a .car or a .war), that includes Administration Console portlets. These portlets will be added to the Extensible Administration Console when the ACE is activated.
Extensible Administration console - A flexible version of Geronimo's original administration console. Once installed it is available at http://localhost:8080/console, and includes some portlets that correspond to the currently activated services in Geronimo.
Service - a component or set of functionality for Geronimo - it may be pre-installed, such as the Tomcat or Jetty web container, or it may be installed as a plugin
Minimal console - The administration console as it is first installed - with only the services necessary for basic functionality
Portlet - A web user interface component that can assembled together with other similar components to create a web (portal) page. See the Portlet Specification JSR 168.

Installation Scenarios

1. Installing the extensible administration console into a Geronimo minimal assembly
2. Installing an ACE in the .car format from an online repository
3. Installing an ACE in the .war format from disk

   Which kind of file format do I want ?

   • Need console extensions for a component you already have? If you are planning to add Administration Console portlets for a component that is already installed on your server, a .war file is simplest. A .war-format ACE has only the needed portlets, and is dependent on the component already being installed.
   • Need the component and its extensions? If you need to install both a new component and its associated Admin Console portlets, a .car file is the right choice. This will look up and download all the necessary components and dependencies, and will also install the new ACE file. A .car file can also be used if the component is already installed.
   • Not sure? If you aren't sure that you have all the pre-requisites installed, a .car is the safest option. This will work regardless of whether the component is pre-installed or not.

   What about installing a .car file from disk?

   Unfortunately, it is not possible to install a .car file from disk with the current Geronimo Administration Console. However you can still use the "deploy install-plugin" tool from the command line. For more information, read up on the deployer tool at http://cwiki.apache.org/GMOxDOC11/deployer-tool.html

Installing the Extensible Administration Console

This section covers all the necessary steps to install the new Extensible Administration Console on your Geronimo 2.1 Minimal Server. The Geronimo 2.1 Java EE servers already have the console installed.

Prerequisites

1. Geronimo 2.1 - Minimal is installed ("Little-G")
2. No other Geronimo administration console is currently installed

Install as a plugin

1. Start Geronimo
2. Use the deployment utility to search the online plugin catalog:

   bin/deploy.sh search-plugins http://geronimo.apache.org/plugins/geronimo-2.1/

3. Select the Geronimo Plugins :: Administration Console - Tomcat or Geronimo Plugins :: Administration Console - Jetty from the list of plugins
   Now you can point your web browser to http://localhost:8080/console and see the newly installed console.

Installing an ACE in .war format from an archive file

An ACE in .war format will install only the console extension. Its pre-requisite must already be installed on your system. For example, if you were installing a console extension to monitor a Derby database, Derby would need to be pre-installed on your server.
Prerequisites

1. You have a .war-format ACE to be installed.
2. The Extensible Administration Console is already deployed, as described above.
3. Any pre-requisites for the ACE are already installed.
   Instructions
4. Open the administrative console in an internet browser at address http://localhost:8080/console.
5. Select Deploy New on the left navigation bar.
6. Click browse and navigate to the ACE file.
7. Click Deploy.
8. Refresh your browser. Your new component will show up on the left side navigation menu.

Installing an Administration Console Extension in .car format from a repository

An ACE in the .car format installs a component and adds its configuration portlets to the Extensible Administration Console.
Prerequisites

1. Your plugin provider already has specified a repository URL. For a larger selection of available plugins, checking http://geronimo.apache.org/plugins/geronimo-2.1/repository/ is a good place to start.
2. The Extensible Administration Console already installed, as described in the previous section.

Instructions

1. Access the Extensible Administration Console by pointing a web browser to the following address http://localhost:8080/console.
2. Select Plugins on the left navigation bar.
3. Under Install Geronimo Plugins, choose the plugin's repository address.

4. With the correct repository displayed in the Repository box, select Search for Plugins.
5. Choose the plugin from the Available Plugins list by clicking directly on the plugin name.

6. Select Continue on next screen if the information is correct, or Cancel to return to the previous screen.
7. Select Install Plugin on the next screen to download and install the ACE and all of its required components.
8. When the plugin installation is complete, refresh your browser.
9. A new menu item will appear on the left. You can now configure this plugin's settings from the newly installed portlets.

Examples

Installing the HelloWorld ACE (.war file)

This is an example of a simple ACE file. It is not attached to any components - it simply adds a new "Hello World" portlet to the Extensible Administration Console.

1. Download example-extension-new.war example_extension_new.war
2. Access the Extensible Administration Console by pointing your web browser to http://localhost:8080/console.
3. Select Deploy New on the left navigation bar.
4. Click browse next to Archive and select the example-extension-new.war file. Leave the Plan box blank, Start app after install checked, and Redeploy application unchecked.

5. Click Install. Your new component will show up on the left side navigation menu.