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
`galaxy`	`systemctl start galaxy.target && journalctl -f -u 'galaxy-*'`
`galaxyctl start`	`systemctl start galaxy.target`
`galaxyctl start SERVICE ...`	`systemctl start galaxy-SERVICE.service galaxy-...`
`galaxyctl restart`	`systemctl restart galaxy.target`
`galaxyctl restart SERVICE ...`	`systemctl restart galaxy-SERVICE.service galaxy-...`
`galaxyctl graceful`	`systemctl reload-or-restart galaxy.target`
`galaxyctl graceful SERVICE ...`	`systemctl reload-or-restart galaxy-SERVICE.service galaxy-...`
`galaxyctl stop`	`systemctl start galaxy.target`
`galayxctl follow`	`journalctl -f -u 'galaxy-*'`