Basic Usage¶
A basic example of starting and running a simple Galaxy server from a source clone in the foreground is provided in the ref:Quick Start guide. This section covers more typical usage for production Galaxy servers.
Managing a Single Galaxy¶
If you have not installed Gravity separate from the Galaxy virtualenv, simply activate Galaxy’s virtualenv, which will
put Gravity’s galaxyctl and galaxy commands on your $PATH:
$ . /srv/galaxy/venv/bin/activate
$ galaxyctl --help
Usage: galaxyctl [OPTIONS] COMMAND [ARGS]...
Manage Galaxy server configurations and processes.
Options:
-d, --debug Enables debug mode.
-c, --config-file FILE Gravity (or Galaxy) config file to operate on. Can
also be set with $GRAVITY_CONFIG_FILE or
$GALAXY_CONFIG_FILE
--state-dir DIRECTORY Where process management configs and state will be
stored.
-h, --help Show this message and exit.
Commands:
configs List registered config files.
deregister Deregister config file(s).
exec Run a single Galaxy service in the foreground, with logging...
follow Follow log files of configured instances.
graceful Gracefully reload configured services.
instances List all known instances.
pm Invoke process manager (supervisorctl, systemctl) directly.
register Register config file(s).
rename Update path of registered config file.
restart Restart configured services.
show Show details of registered config.
shutdown Shut down process manager.
start Start configured services.
status Display server status.
stop Stop configured services.
update Update process manager from config changes.
If you run galaxy or galaxyctl from the root of a Galaxy source checkout and do not specify the config file
option, config/galaxy.yml or config/galaxy.yml.sample will be automatically used. This is handy for working with
local clones of Galaxy for testing or development. You can skip Galaxy’s lengthy and repetitive run.sh configuration
steps when starting and stopping Galaxy in between code updates (you should still run run.sh after performing a
git pull to make sure your dependencies are up to date).
Gravity can either run Galaxy via the supervisor process manager (the default) or systemd. For production servers, it is recommended that you run Gravity as root in systemd mode. See the Managing a Production Galaxy section for details.
As shown in the Quick Start, the galaxy command will run a Galaxy server in the foreground. The galaxy command
is actually a shortcut for two separate steps: 1. read the provided galaxy.yml and write out the corresponding
process manager configurations, and 2. start and run Galaxy in the foreground using the process manager (supervisor).
You can perform these steps separately (and in this example, start Galaxy as a backgrounded daemon instead of in the
foreground):
$ galaxyctl update
Adding service gunicorn
Adding service celery
Adding service celery-beat
$ galaxyctl start
celery STARTING
celery-beat STARTING
gunicorn STARTING
Log files are in /srv/galaxy/var/gravity/log
When running as a daemon, the stop subcommand stops your Galaxy server:
$ galaxyctl stop
celery-beat: stopped
gunicorn: stopped
celery: stopped
All processes stopped, supervisord will exit
Shut down
Most Gravity subcommands (such as stop, start, restart, …) are straightforward, but a few subcommands are
worth pointing out: update, graceful, and exec. All subcommands are documented in the
Subcommands section and their respective --help output.
Managing a Production Galaxy¶
By default, Gravity runs Galaxy processes under supervisor, but setting the process_manager option to systemd
in Gravity’s configuration will cause it to run under systemd instead. systemd is the default init system under most
modern Linux distributions, and using systemd is strongly encouraged for production Galaxy deployments.
Gravity manages systemd service unit files corresponding to all of the Galaxy services that it is aware of, much like
how it manages supervisor program config files in supervisor mode. If you run galaxyctl update as a non-root user,
the unit files will be installed in ~/.config/systemd/user and run via systemd user mode. This can be useful for
testing and development, but in production it is recommended to run Gravity as root, so that it installs the service
units in /etc/systemd/system and are managed by the privileged systemd instance. Even when Gravity is run as root,
Galaxy itself still runs as a non-root user, specified by the galaxy_user option in the Gravity configuration.
It is also recommended, when running as root, that you install Gravity independent of Galaxy, rather than use the copy installed in Galaxy’s virtualenv:
# python3 -m venv /opt/gravity
# /opt/gravity/bin/pip install gravity
Caution
Because systemd unit file names have semantic meaning (the filename is the service’s name) and systemd does not have
a facility for isolating unit files controlled by an application, Gravity considers all unit files in the unit dir
(/etc/systemd/system) that are named like galaxy-* to be controlled by Gravity. If you have existing unit
files that are named as such, Gravity will overwrite or remove them.
In systemd mode, and especially when run as root, some Gravity options are required:
gravity:
process_manager: systemd
# required if running as root
galaxy_user: GALAXY-USERNAME
# optional, defaults to primary group of the user set above
galaxy_group: GALAXY-GROUPNAME
# required
virtualenv: /srv/galaxy/venv
# probably necessary if your galaxy.yml is not in galaxy_root/config
galaxy_root: /srv/galaxy/server
See the Configuration section for more details on these options and others.
The log_dir option is ignored when using systemd. Logs are instead captured by systemd’s logging facility,
journald.
You can use galaxyctl to manage Galaxy process starts/stops/restarts/etc. and follow the logs, just as you do under
supervisor, but you can also use systemctl and journalctl directly to manage process states and inspect logs
(respectively). Only galaxyctl update is necessary, in order to write and/or remove the appropriate systemd service
units based on your configuration. For example:
# export GRAVITY_CONFIG_FILE=/srv/galaxy/config/galaxy.yml
# . /srv/galaxy/venv/bin/activate
(venv) # galaxyctl update
Adding service galaxy-gunicorn.service
Adding service galaxy-celery.service
Adding service galaxy-celery-beat.service
After this point, operations can be performed with either galaxyctl or systemctl. Some examples of equivalent
commands:
Gravity |
systemd |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|