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.