Revision as of 10:19, 28 October 2010

Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.

A guide to deployment and administration of Gyrex based servers.

Contents

• 1 Getting Started
  • 1.1 Overview
  • 1.2 Quick Start
• 2 Concepts
  • 2.1 Modularity
  • 2.2 Provisioning
  • 2.3 Operation Mode
• 3 Configuration
  • 3.1 Logging
    • 3.1.1 Using Logback System Property
    • 3.1.2 Using Workspace Log Configuration

Getting Started

Overview

Gyrex is a Java base application. For proper operation it requires a Java Virtual Machine installed on the system (at least Java 6). It comes with a native launcher that is capable for searching for installed Java VMs.

Quick Start

1. Download Gyrex, unzip and run.
2. Open Admin Console (by default running on http://localhost:3110/) and perform initial configuration

Concepts

Modularity

Gyrex is based on OSGi/Equinox. Thus, Gyrex is completely modular. Gyrex consists of a bunch of components which can be mixed at runtime, i.e. components can be installed and activated individually. In addition, components can run in multiple versions.

Provisioning

Gyrex used p2 for all provisioning operations. Whenever something needs to installed into the system a p2 operation must be performed. Typically, applications (or just individual application components) are published by their maintainers into a repository. An administrator can then cherry-pick at runtime the desired applications from a maintainers repository and install them into a server.

Operation Mode

Gyrex allows server to run in different modes. Typically, this is initiated by passing different startup arguments when launching a server instance. This allows to operate a server either in production or development mode. Depending on the selected mode, different default settings are applied. For example, a production system will be configured more strictly regarding security and not exposing as much information to end users as a development system.

Configuration

Logging

Gyrex provides a logging infrastructure based on SLF4J and Logback. This also includes support for capturing Apache Commons Logging and LOG4J log events. The default configuration logs all messages to the console in development mode. In product mode an rotating error log is created in the instance area logs location. However, it's possible to supply your own custom Logback configuration file in order to customize logging.

If you are new to Logback please have a look at the Logback manual.

Using Logback System Property

The first option is using the system property logback.configurationFile. This will instruct Logback to read the configuration from the specified file.

Example:

gyrex [...] -vmargs [...] -Dlogback.configurationFile=/path/to/config.xml

Note, this can also be set via gyrex.ini or configuration/config.ini.

Using Workspace Log Configuration

Another option is placing a configuration file into your workspace location (aka. OSGi instance directory, Eclipse workspace). The configuration file must be <workspace>/etc/logback.xml and will be read at Gyrex start to configure Logback. The file is only read at start, though. However, once initialized you can use Logback capabilities to have Logback monitor the file for updates/changes to the configuration at runtime.

The benefit of using this method is that a substitution property gyrex.instance.area.logs will be provided which expands to the full path (includinding trailing slash) of the workspace logs directory. This allows to create configuration files without hard coded path names which can be reused across multiple workspaces.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <!-- console logger -->
  <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- application log file -->
  <appender name="applog" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <!-- deny all events with a level below INFO, that is TRACE and DEBUG -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <file>${gyrex.instance.area.logs:-logs/}application.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <!-- daily rollover -->
      <fileNamePattern>${gyrex.instance.area.logs:-logs/}application.%d{yyyy-MM-dd}.log</fileNamePattern>
      <!-- keep 30 days' worth of history -->
      <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- query log file -->
  <appender name="querylog" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${gyrex.instance.area.logs:-logs/}queries.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <!-- daily rollover -->
      <fileNamePattern>${gyrex.instance.area.logs:-logs/}queries.%d{yyyy-MM-dd}.log</fileNamePattern>
      <!-- keep 30 days' worth of history -->
      <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- enable logging for interested packages -->
  <logger name="org.eclipse.gyrex.examples.bugsearch" level="DEBUG">
    <!-- log to console -->
    <appender-ref ref="console" />
  </logger>

  <!-- configure query logging -->
  <logger name="bugsearch.querylog" level="INFO" additivity="false">
    <appender-ref ref="querylog" />
  </logger>

  <!-- configure default logging (children can override) -->
  <root level="WARN">
    <appender-ref ref="applog" />
  </root>

</configuration>