Galaxy is a lightweight software deployment and management tool.
Ruby Java Shell
Clone or download
Pull request Compare This branch is 16 commits ahead, 28 commits behind hgschmie:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This is the Trumpet specific fork of By now, it significantly differs from the original galaxy code base that agents and console are no longer compatible with the original version. This might change in the future (i.e. they become compatible again).

If you are using this fork, you are pretty much on your own. Good luck!



Galaxy is a lightweight software deployment and management tool. We use it at Ning to manage the Java cores and Apache httpd instances that make up the Ning platform (


Galaxy has four components:

  • Agent

  • Console

  • Command-line client

  • Gepo


The Galaxy agent, galaxy-agent, is a Ruby process responsible for managing deployments, starting and stopping processes, and registering with the console. One galaxy-agent process runs on each host (physical machine, Solaris zone, Virtual Machine) managed by Galaxy.

By default, it runs as the xncore user.

Each agent can manage a single software deployment at a time. For this reason, Galaxy is commonly used with OS virtualization (e.g., Solaris zones), wherein new OS instances, and thus Galaxy agent instances, can be instantiated with low overhead.


The Galaxy console, galaxy-console, is a Ruby process responsible for receiving announcements from agents, logging state changes, and providing an agent list to the command-line tool.

Typically, each environment (e.g. production, QA, development) has its own console.

Command-line client

The galaxy command-line client is the primary user interface to the Galaxy system. It retrieves a list of agents from the console, and contacts individual agents to do its work. Cores can be assigned (deployed), cleared (undeployed), updated, started, and stopped from the command-line tool.

The user must specify which console to use, either through a command-line argument (-c) or an environment variable (GALAXY_CONSOLE).


Gepo is the Galaxy software depot. It is a web-accessible repository that contains applications binaries and configuration properties.

Typically, the configuration files are stored in a SCM repository (subversion, git, …), and the binary packages are stored in a single flat directory on the file system.

Gepo is not part of the Galaxy code base but rather an external webserver that needs to be setup.

Gepo architecture tips

The Gepo SCM server should have two top-level directories:

  • config/: The root of a hierarchical directory structure defining a “config path” that contains configuration files

  • binaries/: A flat directory containing application binary packages of the form <type>-<version>-<build>.tar.gz.



Binaries are stored in the binary branch in Gepo.

Config path

Core configuration properties are stored in the config branch in Gepo, usually broken down per environment (each environment should have its own Gonsole):

Subdirectories under the config branch are known as “config path”. Each host managed by Galaxy can be assigned to one config path, which specifies which binaries and properties to download.

Here is an example of a config path, which has three components:



  • <site> specifies the site (datacenter)

  • <ver> specifies the version tag associated with the release

  • <type> specifies the core type abbreviation

The config path may include optional sub-types:


Configuration properties are built by scanning each node of the config path for properties files and merging them to create one file. Properties defined at deeper levels override properties of the same name defined at higher levels.

For example, consider the following files:

uk_datacenter/"Led Zeppelin"
greatest.drummer="John Bonham"
greatest.guitarist="Jimmy Page"

greatest.bassist="Les Claypool"

uk_datacenter/6.5.15/apache/"Dave Matthews Band"
greatest.drummer="Carter Beauford"

The configuration file generated from merging these files would contain:

greatest.guitarist="Jimmy Page"
greatest.bassist="Les Claypool""Dave Matthews Band"
greatest.drummer="Carter Beauford"

Note that this property inheritance/overriding only works on files with names ending in “.properties”. With other files, such as jvm.config or log4j.xml, the file at the deepest level is used as-is.


When a host is assigned a config path, updated to a different config path, updated to the same config path (to force a properties refresh), or cleared, the Galaxy agent begins a new “deployment”.

A deployment is a set of files and directories used to download, manage, and run software releases.

A deployment consists of:

  • A sequence number. All Galaxy agents begin with deployment number 1 and increment for each new deployment. This sequence number is stored in the “deployment” file in the agent's data directory (typically ~xncore/data).

  • A data file describing the deployment core type, build number, and version. The data file is stored in the agent's data directory (typically ~xncore/data); the file name is the same as the deployment sequence number (e.g., ~xncore/data/1).

  • A deployment directory in the agent's deploy directory (typically ~xncore/deploy) that contains the contents of the binary archive downloaded from Gepo.

  • A symbolic link called “current” that points to the current deployment directory.

An example might help illustrate these points. Consider the following directory listings (under ~xncore) for a host that has been assigned to 5 different config paths over its lifetime:

xncore@prod1:~: pwd
xncore@prod1:~: ls -l . data deploy
total 14
drwxr-xr-x 2 xncore xncore 8 Oct 24 04:08 data
drwxr-xr-x 7 xncore xncore 8 Oct 24 04:08 deploy

total 12
-rw-rw-rw- 1 xncore xncore 162 Oct 3 18:16 1
-rw-rw-rw- 1 xncore xncore 162 Oct 12 23:45 2
-rw-rw-rw- 1 xncore xncore 162 Oct 13 00:08 3
-rw-rw-rw- 1 xncore xncore 162 Oct 17 04:58 4
-rw-rw-rw- 1 xncore xncore 164 Oct 24 04:08 5
-rw-rw-rw- 1 xncore xncore 1 Oct 24 04:08 deployment

total 16
drwxr-xr-x 8 xncore xncore 9 Oct 12 13:26 1
drwxr-xr-x 7 xncore xncore 7 Oct 11 19:02 2
drwxr-xr-x 7 xncore xncore 8 Oct 17 04:58 3
drwxr-xr-x 7 xncore xncore 8 Oct 24 04:08 4
drwxr-xr-x 7 xncore xncore 9 Oct 24 04:09 5
lrwxrwxrwx 1 xncore xncore 27 Oct 24 04:08 current -> /home/xncore/deploy/5

xncore@prod1:~:cat data/deployment ; echo # the deployment file does not contain a linefeed

xncore@prod1:~: cat data/5
--- !ruby/object:OpenStruct
:build: 6.5.10-9378
:core_base: /home/xncore/deploy/5
:config_path: /uk_datacenter/6.5.10/apache
:core_type: resolver

xncore@prod1:~: ls -l deploy/current/
total 767612
drwxr-xr-x 2 xncore xncore 5 Oct 23 22:08 bin
drwxr-xr-x 2 xncore xncore 6 Oct 24 04:08 etc
-rw-rw-rw- 1 xncore xncore 392679750 Dec 1 09:06 launcher.log
-rw-rw-rw- 1 xncore xncore 5 Oct 24 04:09
drwxr-xr-x 4 xncore xncore 4 Oct 23 22:07 lib
drwxr-xr-x 15 xncore xncore 15 Oct 16 16:56 static-resources
drwxr-xr-x 3 xncore xncore 5 Oct 23 22:07 test

Old deployment directories are not removed when new deployments are created. Thus, a core which has been assigned, cleared, or updated several times will contain several old versions of binaries and logs. It is safe for users to remove all but the current deployment directory if needed.


Launcher is a script responsible for starting and stopping cores. It is distributed with each core type, and may vary as needed depending on the type of core it maintains.

Galaxy calls launcher to start and stop cores, and to check core status.

Note that you need to write your own launcher scripts as they are deployments specific. See the section “How to Galaxify an application” below.

Launcher can be invoked directly from the command line, allowing cores to be controlled without the galaxy command-line tool. This is useful for debugging:

xncore@prod1# su - xncore
xncore@prod1% cd deploy/current
xncore@prod1% bin/launcher start

xncore@prod1# su - xncore
xncore@prod1% cd deploy/current
xncore@prod1% bin/launcher stop



Mongrel gem.

Getting started

You can run a Gonsole and an agent locally. In two different terminals, run:

% rake run:gonsole
% rake run:gagent

You can now use the command line client to interact with them:

% ruby -Ilib bin/galaxy show-agent -c localhost

local_test local_group online 3.6.3beta

% ruby -Ilib bin/galaxy show-console -c localhost

local_test local_group - unknown - - testbox.local - online

Getting help

Running the galaxy command with -help will display on-line help.

% galaxy -help
galaxy [options] <command> [args]

    -h, --help                       Display a help message and exit
    -c, --console CONSOLE            Galaxy console host (overrides GALAXY_CONSOLE)
    -C, --config FILE                Configuration file (overrides GALAXY_CONFIG)
    -p, --parallel-count THREADS     Maximum number of threads to use, default 25
    -r, --relaxed-versioning         Allow updates to the currently assigned version
    -V                               Display the Galaxy version number and exit
    -y, --yes                        Avoid confirmation prompts by automatically confirming all actions

    -i, --host HOST                  Select a specific agent by hostname
    -I, --ip IP                      Select a specific agent by IP address
    -m, --machine MACHINE            Select agents by physical machine
    -M, --cohabitants HOST           Select agents that share a physical machine with the specified host
    -s, --set SET                    Select 'e{mpty}', 't{aken}' or 'a{ll}' hosts
    -S, --state STATE                Select 'r{unning}' or 's{topped}' hosts
    -A, --agent-state STATE          Select 'online' or 'offline' agents
    -e, --env ENV                    Select agents in the given environment
    -t, --type TYPE                  Select agents with a given software type
    -v, --version VERSION            Select agents with a given software version

    - Filters are evaluated as: set | host | (env & version & type)
    - The HOST, MACHINE, and TYPE arguments are regular expressions (not globs)
    - The default filter selects all hosts



Galaxy requires Ruby 1.8.7 or Ruby 1.9 and Ruby Gems. See


The galaxy command-line client is used to interact with the deployments via the Gonsole. For convenience, the GALAXY_CONSOLE environment variable can be set prior to running the galaxy command, e.g.:


To deploy one core to one machine, you need at least an Agent and a Gonsole running. The Agent needs to run on the same machine where the code is being deployed. The command-line client and the Gonsole can be anywhere (same machine, or not).

Command-line client

Core status is displayed using the 'show' command.

xncore@prod1:~: galaxy show -help
galaxy [options] <command> [args]

Usage for 'show':

    Show software deployments on the selected hosts


    - Show all hosts:
        galaxy show

    - Show unassigned hosts:
        galaxy -s empty show

    - Show assigned hosts:
        galaxy -s taken show

    - Show a specific host:
        galaxy -i show

    - Show all widgets:
        galaxy -t widget show

defines a search filter, and is some combination of:

  • -i <host> => Selects the single host specified by the supplied host name

  • -s <site> => Selects the hosts in the specified site <site>, corresponding to the first node of the config path (e.g., “uk_datacenter”)

  • -v <version> => Selects the hosts running the specified version <version>, corresponding to the second node of the config path (e.g., “6.6”)

  • -t <type> => Selects the hosts running the specified core type <type>, corresponding to the third node (and any subsequent nodes) of the config path (e.g., “apache”, “apache/ssl”, …).

  • -s <set> => Selects the hosts in the specified set, which is one of:

  • a => Selects all hosts running a Galaxy agent

  • t => Selects all hosts that have been assigned a role

  • e => Selects all hosts that have NOT been assigned a role

Other search filters are available; see the Galaxy command-line help for more information.

By default, core sub-types (e.g., “apache/ssl”, “apache/passenger”, etc.) are NOT included in searches for the core super-type (e.g., “apache”). To retrieve cores with a sub-type, append a .* to the core type. Note that some shells require the wildcard to be escaped; bash does not (as long as the current working directory does not contain files matching the glob pattern).

How to Galaxify an application

Two files are required to Galaxify an application:

  • A file uploaded to the desired config path in the Gepo config branch. This file must contain at least one property, type, which defines the _type> portion of the tarball name described below. It may also contain a version property, which defines the <version> portion of the tarball name, which is an arbitrary string that may include a build number, patch date, or other useful information.

A typical file looks like:


Note that if the version property is not specified, it will be inherited from a file located higher up in the Gepo config path.

  • An appropriately named binary archive uploaded to the binaries branch in Gepo. The file name should be: <type>-<version>.tar.gz.

The archive must contain at least one file, bin/xndeploy, that must return a 0 exit status. This script can do whatever is needed to deploy the application being installed. Note that most xndeploy scripts require the Galaxy library to be included in the archive, under lib/galaxy.

If Galaxy is to start and stop processes, a bin/launcher script is also required. This script takes one of “start”, “stop”, “restart”, or “status”, and returns with exit status 0 (stopped), 1 (running), or 2 (unknown).

The archive can contain any other files the application requires, commonly placed under the lib directory. The archive will be extracted to the deployment directory (~xncore/deploy/<sequence number>) and linked to ~xncore/deploy/current for convenience.

Running an agent

Running the galaxy-agent command with no arguments will display on-line help.

xncore@prod1:~: galaxy-agent -help
Usage: galaxy-agent <command> [options]
  Commands, use just one of these
    -s, --start                      Start the agent
    -k, --stop                       Stop the agent
  Options for Start
    -C, --config FILE                Configuration file (overrides GALAXY_CONFIG)
    -i, --host HOST[:PORT]           Hostname this agent manages (default localhost)
    -m, --machine MACHINE            Physical machine where the agent lives
    -c ['http://'|'druby://']HOST[:PORT]
        --console                    Hostname where the console is listening
    -r, --repository URL             Base URL for the repository
    -b, --binaries URL               Base URL for the binary archive
    -d, --deploy-to DIR              Directory where to make deployments
    -x, --data DIR                   Directory for the agent's database
    -f, --fore, --foreground         Run agent in the foreground
    -a, --announce-interval INTERVAL How frequently (in seconds) the agent should announce
  General Options
    -z, --event_listener URL         Which listener to use
    -l, --log LOG                    STDOUT | STDERR | SYSLOG | /path/to/file.log
    -L, --log-level LEVEL            DEBUG | INFO | WARN | ERROR. Default=INFO
    -u, --user USER                  User to run as
    -g, --agent-log FILE             File agent should rediect stdout and stderr to
    -t, --test                       Test, displays as -v without doing anything
    -v, --verbose                    Verbose output
    -V, --version                    Print the galaxy version and exit
    -h, --help                       Show this help

For example:

galaxy-agent -s -i -c -r -b -d ~xncore/deploy -x ~xncore/data

To see the agent debug log on the terminal, append the following to the end of the above command:

-f -l STDOUT -L DEBUG -v

How to create a Gonsole

Same steps as the agent:

xncore@prod1:~: galaxy-console -help
Usage: galaxy-console <command> [options]
  Commands, use just one of these
    -s, --start                      Start the console
    -P, --start-proxy                Start the proxy console
    -k, --stop                       Stop the console
  Options for Start
    -C, --config FILE                Configuration file (overrides GALAXY_CONFIG)
    -i, --host HOST                  Hostname this console runs on
    -a HOST[:PORT]                   Port for Http post announcements
    -p, --ping-interval INTERVAL     How many seconds an agent can be silent before being marked dead
    -f, --fore, --foreground         Run console in the foreground
    -Q, --console-proxied-url URL    Gonsole to proxy
  General Options
    -z, --event_listener URL         Which listener to use
    -l, --log LOG                    STDOUT | STDERR | SYSLOG | /path/to/file.log
    -L, --log-level LEVEL            DEBUG | INFO | WARN | ERROR. Default=INFO
    -g, --console-log FILE           File agent should rediect stdout and stderr to
    -u, --user USER                  User to run as
    -t, --test                       Test, displays as -v without doing anything
    -v, --verbose                    Verbose output
    -V, --version                    Print the galaxy version and exit
    -h, --help                       Show this help

Configuring Galaxy

The preferred method of configuring Galaxy is to write an /etc/galaxy.conf file.

See for up-to-date configuration options.


mvn clean package

The Rakefile has a few rules to build gems, RPM and Solaris packages. See:

rake -T

for more information.

License (see LICENSE-2.0.txt file for full license)

Copyright 2010 Ning

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.