Scripts¶
This section describes some of the various scripts that are distributed with Pulsar.
pulsar
(*nix)¶
Installing Pulsar will install the pulsar
script. It is a lightweight
wrapper abstracting out a few different ways to run Pulsar. Pulsar can easily
be run inside a variety wsgi servers or stand-alone without a web server using
pulsar-main
- the pulsar
script shouldn’t be considered a best
practice - it merely provides a minimal level of convenience that may be
useful in some deployment scenarios.
Very simply, pulsar
will source local_env.sh
if it is present (to
configure things like DRMAA_LIBRARY_PATH
) and then determine which
external application to use to run Pulsar (either a WSGI server or pulsar-
main
) and delegate to that method.
pulsar
can be passed the --mode
argument to explicitly describe which
application should be used to run Pulsar. If --mode
unspecified,
pulsar
will check the PATH
and launch look for (in order) uwsgi
,
circusd
, chaussette
, and finally paster
to determine which mode to
use.
paster
mode¶
Paste is installed with Pulsar and so is the fallback mode if none of the other web servers is available.
In this mode, Pulsar can be launched using the command:
pulsar
This will run the server in your terminal (not as a daemon) and the server will run as long as this command is running. To run Pulsar as a daemon, use the command:
pulsar --daemon
This will run Pulsar in daemon mode (i.e. run in the background). In daemon
mode, paster creates a pid file in the current directory called paster.pid
and a log file paster.log
. The daemon can be stopped using the command:
pulsar --stop-daemon
webless
mode¶
This mode can be used to launch Pulsar without a web server. This only makes
sense if a message_queue_url
is defined in app.yml
and the client (e.g
Galaxy) configures all staging to be triggered remotely (this is the default for the Galaxy job runner galaxy.jobs.runners.pulsar:PulsarMQJobRunner
).
See the documentation for the pulsar-main
for the arguments that may be
supplied to pulsar
in this mode.
Other Modes¶
pulsar-config
will configure sections in server.ini
that allow Pulsar
to be launched using uWSGI, Cirucs, and Chaussette. pulsar
will launch
these servers when --mode
is specified as uwsgi
, circus
,
chaussette
respectively.
See the documentation for the respective application for a full description of the arguments that can be used to configure that web server. Presumably each of these servers is more performant and better maintained than Paste but Paste is cross-platform and makes it trivial to configure SSL and so it remains the default for Pulsar for now.
pulsar
(Windows)¶
pulsar
is a lightweight wrapper around paster serve
(see docs). It will check the current
directory for a server.ini
file and launch the described Pulsar server using Paste.
pulsar-main
¶
Usage:
pulsar-main [-h] [-c CONFIG_DIR] [--ini_path INI_PATH]
[--app_conf_path APP_CONF_PATH] [--app APP] [-d]
[--daemon-log-file DAEMON_LOG_FILE] [--pid-file PID_FILE]
Help
Stand-alone entry point for running Pulsar without a web server.
In its simplest form, this method will check the current directory for an
app.yml and run the corresponding configuration as a standalone applciation.
This makes sense when app.yml
contains a message_queue_url
option so
Pulsar is configured to listen to a message queue and doesn’t require a web
server.
The following commands can be used to bootstrap such a setup.:
mkdir pulsar-mq-config
cd pulsar-mq-config
pulsar-config --mq
pulsar-main
This script can be used in a standalone fashion, but it is generally better to
run the pulsar
script with --mode webless
- which will in turn
delegate to this script.
Options:
-h, --help show this help message and exit
-c CONFIG_DIR, --config_dir CONFIG_DIR
Default directory to search for relevant Pulsar
configuration files (e.g. app.yml, server.ini).
--ini_path INI_PATH Specify an explicit path to Pulsar's server.ini
configuration file.
--app_conf_path APP_CONF_PATH
Specify an explicit path to Pulsar's app.yml
configuration file.
--app APP
-d, --daemonize Daemonzie process (requires daemonize library).
--daemon-log-file DAEMON_LOG_FILE
Log file for daemon, if --daemonize supplied.
--pid-file PID_FILE Pid file for daemon, if --daemonize supplied (default
is pulsar.pid).
pulsar-config
(Windows)¶
Usage:
pulsar-config [-h] [--directory DIRECTORY] [--mq] [--no_logging]
[--host HOST] [--private_token PRIVATE_TOKEN]
[--port PORT] [--install] [--force]
Help
Initialize a directory with a minimal pulsar config.
Options:
-h, --help show this help message and exit
--directory DIRECTORY
Directory containing the configuration files for
Pulsar.
--mq Write configuration files for message queue server
deployment instead of more traditional RESTful web
based pulsar.
--no_logging Do not write Pulsar's default logging configuration to
server.ini and if uwsgi is configured do not configure
its logging either.
--host HOST Host to bind Pulsar to - defaults to localhost.
Specify 0.0.0.0 to listen on all interfaces.
--private_token PRIVATE_TOKEN
Private token used to authorize clients. If Pulsar is
not protected via firewall, this should be specified
and SSL should be enabled. See https://pulsar.readthed
ocs.org/en/latest/configure.html for more information
on security.
--port PORT Port to bind Pulsar to (ignored if --mq is specified).
--install Install optional dependencies required by specified
configuration (e.g. drmaa, supervisor, uwsgi, etc...).
--force Overwrite existing files if they already exist.
pulsar-config
(*nix)¶
Usage:
pulsar-config [-h] [--directory DIRECTORY] [--mq] [--no_logging]
[--supervisor] [--wsgi_server {paster,uwsgi}]
[--libdrmaa_path LIBDRMAA_PATH] [--host HOST]
[--private_token PRIVATE_TOKEN] [--port PORT] [--install]
[--force]
Help
Initialize a directory with a minimal pulsar config.
Options:
-h, --help show this help message and exit
--directory DIRECTORY
Directory containing the configuration files for
Pulsar.
--mq Write configuration files for message queue server
deployment instead of more traditional RESTful web
based pulsar.
--no_logging Do not write Pulsar's default logging configuration to
server.ini and if uwsgi is configured do not configure
its logging either.
--supervisor Write a supervisord configuration file for managing
pulsar out as well.
--wsgi_server {paster,uwsgi}
Web server stack used to host Pulsar wsgi application.
--libdrmaa_path LIBDRMAA_PATH
Configure Pulsar to submit jobs to a cluster via DRMAA
by supplying the path to a libdrmaa .so file using
this argument.
--host HOST Host to bind Pulsar to - defaults to localhost.
Specify 0.0.0.0 to listen on all interfaces.
--private_token PRIVATE_TOKEN
Private token used to authorize clients. If Pulsar is
not protected via firewall, this should be specified
and SSL should be enabled. See https://pulsar.readthed
ocs.org/en/latest/configure.html for more information
on security.
--port PORT Port to bind Pulsar to (ignored if --mq is specified).
--install Install optional dependencies required by specified
configuration (e.g. drmaa, supervisor, uwsgi, etc...).
--force Overwrite existing files if they already exist.
pulsar-check
¶
Usage:
Script used to run an example job against a running Pulsar server.
Help
Exercises various features both the Pulsar client and server.
Options:
-h, --help show this help message and exit
--url=URL URL of the Pulsar web server to target.
--private_token=PRIVATE_TOKEN
Private token used to authorize client, if the Pulsar
server specified a private_token in app.yml this must
match that value.
--transport=TRANSPORT
Specify as 'curl' to use pycurl client for staging.
--cache Specify to test Pulsar caching during staging.
--test_errors Specify to exercise exception handling during staging.
--suppress_output
--disable_cleanup Specify to disable cleanup after the job, this is
useful to checking the files generated during the job
and stored on the Pulsar server.