Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Gyrex/Administrator Guide
| Gyrex | |
| Website | |
| Download | |
| Community | |
| Mailing List • Forums • IRC • mattermost | |
| Issues | |
| Open • Help Wanted • Bug Day | |
| Contribute | |
| Browse Source • Project Set File |
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.
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
- Download Gyrex, unzip and run.
- Open Admin Console (by default running on http://localhost:3110/) and perform initial configuration
Concepts & Features
Modularity
Gyrex is based on OSGi/Equinox and completely modular. It consists of components implementing key features 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 uses 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/update them into a server.
Cloud
With Gyrex it's possible to build your own private cloud platform. Gyrex integrates with ZooKeeper in order to allow easy discovery and management of nodes. You'll be able to appoint and retire nodes in your cloud quickly and distribute applications and tasks among them.
Web
The highly scalable and performant Jetty web engine is also included with Gyrex. It allows for seamless development and deployment of pure OSGi based web application. You can start with a single web application using the OSGi HttpService. Additionally, Gyrex provides an OSGi service for deploying and managing many application on different HTTP channels (secure, non-secure, different ports, etc.) on various nodes in your cloud. It's also possible to run multiple instances of the same application for multiple tenants including full separation of HTTP sessions, database connections, etc.
Development Mode
Gyrex allows servers to run in development mode. This allows to operate a server either in production or development mode. Typically, a fresh server installation initially runs in development mode and must be configured to not run in development mode. Depending on the selected mode, different default settings are applied. For example, a non-development system will user more strict defaults regarding security and may not expose as much information to end users as a development system. In contrast, a development system may run with more convenient defaults which does not require developers to perform a time-consuming system setup procedure.
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 runtime workspace location (aka. OSGi instance directory, Eclipse workspace). The configuration file must be <runtime-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>
Cloud
The Gyrex cloud functionality is implemented based on ZooKeeper. When running in development mode, an embedded ZooKeeper server is started automatically so you don't have to configure anything at all. For production environments we highly recommend running a standalone ZooKeeper ensemble. Please have a look at the ZooKeeper Administrator's Guide for details on how to setup your own ensemble.
Connect to ZooKeeper
The first step is to connect each node with the ZooKeeper cluster. This can be done using the OSGi console or the Gyrex Admin UI.
Connect a node to ZooKeeper:
osgi> cloud setConnectString <zookeeper-connect-string> ... osgi>
The zookeeper-connect-string can be any valid ZooKeeper connection string. In its simplest it's just a hostname or IP address.
To provide an zookeeper-connect-string without using the osgi console or the Gyrex Admin UI, add the following line to the configuration/config.ini
... gyrex.zookeeper.connectString=<zookeeper-connect-string>
Node Management
An essential part of a cloud is node membership. Node membership in Gyrex is implemented by explicit approval of nodes. Each node has a unique identifier. Upon first start a new one is generated. It's also possible to manually set node ids. However, you need to ensure that node ids are unique. No two nodes with the same identifier are allows to join the cloud.
After a new node joins a cloud it will be registered with a pending state. In this state the node is not allowed to participate in any cloud activity other than node registration. An administrator need to explicitly approve the node first. Once the node has been approved it will become online.
Tags may be assigned to nodes. They will play an important role when distributing functionality and responsibilities within your cloud.
Console Commands
Two commands are available in the Equinox OSGi console for managing and analyzing the cloud. They both come with a small syntax help
osgi> help [...] ---CloudConsoleCommands--- cloud <cmd> [args] approve <NODEID> - approves a node ls pending|approved|online - list nodes retire <NODEID> - retires a node setConnectString <CONNECTSTRING> - sets the connect string for the local node setOffline - sets the current node offline setOnline - sets the current node on-line setTags <nodeId> [-t <tag> [-t <tag>]] - set tags for a node ---ZooKeeperConsoleCommands--- zk <cmd> [args] create <PATH> - creates a path in ZK get <PATH> - prints the content of the node at the specified path as a string ls <PATH> [-r] - lists the specified path reconnect - reconnects the ZooKeeper gate rm <PATH> [-r] - removes the specified path set <PATH> - sets the content of the node at the specified path as a string stat <PATH> - prints ZK stats of the specified path sync <PATH> - performs ZK sync on the specified path [...] osgi>
List pending (unapproved) nodes:
osgi> cloud ls pending [nodeId] (hostname) ... osgi>
Approve a node:
osgi> cloud approve <nodeId>