This project is a Python server application that allows a Galaxy server to run jobs on remote systems (including Windows) without requiring a shared mounted file systems. Unlike traditional Galaxy job runners - input files, scripts, and config files may be transferred to the remote system, the job is executed, and the results are transferred back to the Galaxy server - eliminating the need for a shared file system.

Full documentation for the project can be found on Read The Docs.

Configuring Galaxy

Galaxy job runners are configured in Galaxy's job_conf.xml file. Some small examples of how to configure this can be found here, but be sure to check out job_conf.xml.sample_advanced in your Galaxy code base or on Github for complete information.

Quickstart

Full details on different ways to install Pulsar can be found in the install section of the documentaiton, but if your machine has the proper Python dependencies available it can be quickly download and a test job run with:

$ mkdir pulsar
$ cd pulsar
$ python3 -m venv venv
$ . venv/bin/activate    # venv\Scripts\activate.bat on Windows
$ pip install 'pulsar-app[web]'
$ pulsar-config
$ pulsar --daemon        # just `pulsar` on Windows
$ pulsar-check           # runs a test job

Please note that as of the 0.14.0 release, Pulsar no longer supports any version of Python 2. The minimum supported Python version is 3.5.

The configuration documentation has many details on securing your Pulsar server and enabling advanced features such as cluster integration and message queue communication.

Development and Testing

The recommended approach to setting up a development environment for Pulsar on Linux or macOS is rougly as follows:

$ git clone https://github.com/galaxyproject/pulsar
$ cd pulsar
$ python3 -m venv .venv
$ . .venv/bin/activate    # .venv\Scripts\activate on Windows
$ pip install -e '.[web]'
$ pip install -r dev-requirements.txt

The -e flag to pip installs Pulsar in "editable" mode, meaning that changes you make to the source code will be reflected when running the pulsar commands installed in the virtual environment.

This project is distributed with unit and integration tests (many of which will not run under Windows), the following command will install the needed python components to run these tests. The following command will then run these tests:

$ make tests

The following command will then produce a coverage report corresponding to this test and place it in the coverage_html_report subdirectory of this project.:

$ coverage html

Check out the Contributing documentation for many more details on developing and contributing to Pulsar.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Support

This documentation is an incomplete work in progress. There are more ways to configure and use Pulsar than are documented, and a growing number of Pulsar experts who would be more than happy to answer your questions and help with any problems you may run in to while setting up a Pulsar deployment. Please do not hesitate to reach out on the Galaxy Admins Gitter Channel

History

0.15.6 (2024-01-15)

• Allow tus uploads to Galaxy. Pull Request 351

0.15.5 (2023-09-15)

• Add catchall OSError to recoverable exceptions (thanks to @mvdbeek). Pull Request 338

0.15.4 (2023-08-29)

• Add .readthedocs.yaml (thanks to @natefoo). Pull Request 332
• Add explicit TimeoutError catching (thanks to @mvdbeek). Pull Request 337
• Update galaxy-job-metrics requirement (thanks to @cat-bro). Pull Request 334

0.15.3 (2023-07-20)

• Fix Pulsar consumer state after ConnectionResetError. Pull Request 331
• User auth plugins (thanks to @SergeyYakubov). Pull Request 321

0.15.2 (2023-05-02)

• Fix Pulsar and Pulsar client reconnection to AMQP server. Pull Request 324
• Reduce verbosity of timeout exception catching. Pull Request 325

0.15.1 (2023-04-13)

• No changes, working around pypi isssue.

0.15.0 (2023-04-13)

• Updated Galaxy+Pulsar container. Pull Request 306
• Rework container execution - generalize Kubernetes execution to allow it to work without a message queue and to allow TES execution based on pydantic-tes (). Pull Request 302
• Add documentation and diagrams for container execution scenarios. Pull Request 302
• Rework integration tests to use pytest more aggressively.
• Fixes to CI to run more tests that weren't being executed because Tox was not sending environment variables through to pytest.
• Add option amqp_key_prefix to direct task queue naming while retaining simple default manager names and such in container scheduling deployments. Pull Request 315
• Various typing and CI fixes. Pull Request 312, Pull Request 319
• Fixes for extra_file handling. Pull Request 318
• Separate tool_stdio and job_stdio handling. Pull Request 318
• Re-import MEMORY_STATEMENT.sh from Galaxy. Pull Request 297
• Add support for logging to sentry. Pull Request 322

0.14.16 (2022-10-04)

• Fix small regression related to building URLs for client action mapping.

0.14.15 (2022-10-03)

• Fix small regressions bugs in 0.14.14 - updating runner util code was bigger swap over than it seemed.

0.14.14 (2022-10-30)

• Bring in updated Galaxy runner util code. Pull Request 303
• Fix recovering "lost" jobs where the job directory does not exist at startup/recovery time (thanks to @natefoo). Pull Request 301
• Use urlencode to encode path (thanks to @mvdbeek). Pull Request 299
• Support the k8s_job_ttl_secs_after_finished option as in the Galaxy Kubernetes runner (thanks to @natefoo). Pull Request 287

0.14.13 (2021-12-06)

• Don't pass all environment variables to jobs launched by Manager (thanks to @nsoranzo). Pull Request 295
• Drop legacy job conf for Galaxy framework tests, test against metadata_strategy: extended (thanks to @mvdbeek). Pull Request 294

0.14.12 (2021-11-10)

• Fixes to bring HOME and temp directory handling closer to Galaxy native runners.
• Enable globbed from_work_dir outputs for remote metadata.

0.14.11 (2021-07-19)

• Fix and test for returncode handling in certain cases. Pull Request 274
• Modernize tox. Pull Request 271

0.14.10 (2021-07-17)

• Don't error out if annotated galaxy.json is absent. Pull Request 270

0.14.9 (2021-07-16)

• Implement dynamic file sources abstraction for parsing files to transfer from galaxy.json files. Pull Request 269
• Use tool classes to only test remote Galaxy tools. Pull Request 266
• Run Galaxy framework tests against dev and master branches of Galaxy (thanks to @mvdbeek). Pull Request 264

0.14.8 (2021-07-14)

• Fix Galaxy composite input references. Pull Request 262
• Run galaxy's tool framework tests against this repo's pulsar (thanks to @mvdbeek). Pull Request 259

0.14.7 (2021-07-13)

• Accept description of tool files to transfer from Galaxy. Pull Request 261
• Support globs in from_work_dir outputs (thanks to @natefoo). Pull Request 257
• Fix loading the Galaxy dependency resolvers config, plus additional config directory fixes (thanks to @natefoo). Pull Request 256

0.14.6 (2021-05-24)

• Fix for newer Galaxy tool profiles having isolated home directories.

0.14.5 (2021-04-15)

• Potential fix for setting file actions via job destination parameters.

0.14.4 (2021-04-14)

• Re-attempt release process - published wrong branch with 0.14.3.

0.14.3 (2021-04-13)

• Allow transferring fewer files from Pulsar when using extended metadata with Galaxy.

0.14.2 (2021-02-15)

• Fix the use of requests, limits, and walltime with coexecution pods. Pull Request 246

0.14.1 (2021-02-02)

• Fix the use of named managers with coexecution pods. Pull Request 242

0.14.0 (2020-09-17)

• fix the PyYAML "load() deprecation" warning (thanks to @gmauro). Pull Request 232
• Set the DRMAA workingDirectory to the job's working directory Pull Request 230
• Fix a unicode issue and polish a bit of variables (thanks to @gmauro). Pull Request 229
• Respond to MQ messages requesting status updates. Pull Request 228
• Fix REST connections broken with Py3 using standard transport Issue 227 Pull Request 231
• Drop Python 2.7 support in standard transport, drop Python 2.7 tests and fix Python 3.7 wheel install test, general test debugging enhancements. Pull Request 231
• drop python 2.6 and add 3.7 and update the testing infrastructure to a more recent Ubuntu setup (thanks to @bgruening). Pull Request 226
• Use is_alive in favour of isAlive for Python 3.9 compatibility (thanks to @tirkarthi). Issue 224 Pull Request 225
• Request and register ports for Galaxy ITs when using Kubernetes. Pull Request 223
• Implement killing k8s jobs. Pull Request 221
• Respond to MQ messages requesting status updates. Pull Request 228
• Drop python 2.6 and add 3.7 and update the testing infrastructure to a more recent Ubuntu setup (thanks to @bgruening). Pull Request 226
• Add a more descriptive message in case of error parsing an external id (thanks to @gmauro). Pull Request 213
• Use requests (thanks to @mvdbeek). Pull Request 216
• Use is_alive in favour of isAlive for Python 3.9 compatibility (thanks to @tirkarthi). Pull Request 225
• Debug connection string for AMQP. Pull Request 217
• Various small Kubernetes fixes and enhancements. Pull Request 218, Pull Request 219
• Improvements and fixes to container handling. Pull Request 202
• Fix a typo in exception logging thanks to @erasche. Pull Request 203
• Cleanup config file handling a bit by removing branch for very old Pulsar servers likely no longer supported. Pull Request 201

0.13.1 (2020-09-16)

• Pinned all listed requirements. This is the final version of Pulsar to support Python 2.

0.13.0 (2019-06-25)

• Various improvements and simplifications to Kubernetes job execution.

0.12.1 (2019-06-03)

• Retry botched release that didn't include all relevant commits.

0.12.0 (2019-06-03)

• Revise Python Galaxy dependencies to use newer style Galaxy decomposition. galaxy-lib can no longer be installed in Pulsar's environment, so you will likely need to rebuild your Pulsar virtualenv for this release. Pull Request 187
• Add a Dockerfile for Pulsar with CVMFS (thanks to @nuwang and @afgane). Pull Request 166
• Various small improvements to Kubernetes pod execution environment. Pull Request 190
• Improve readme linting. Pull Request 186
• Update example docs for Condor (thanks to @bgruening). Pull Request 189

0.11.0 (2019-05-16)

• Implement staging Galaxy metadata input files in the client. 39de377
• Fix 'amqp_ack_republish_time' in sample (thanks to @dannon). Pull Request 185
• Updated amqp_url in job_conf_sample_mq_rsync.xml (thanks to @AndreasSko). Pull Request 184
• Use wildcard char for pulsar version (thanks to @VJalili). Pull Request 181
• Refactor toward more structured inputs. f477bc4
• Refactor toward passing objectstore identifying information around. Pull Request 180
• Rework imports for new Galaxy library structure. da086c9
• Revert empty input testing, it really probably should cause a failure to transfer a non-existent file. 8bd5511
• Better client mapper documentation. b6278b4

0.10.0 (2019-05-06)

• Implement support for Kubernetes two container pod jobs - staging and tool execution as separate containers in the same job's pod. Pull Request 176, Pull Request 178

0.9.1 (2019-05-01)

• Fix duplicate inputs being a problem when staging Galaxy files. Pull Request 175
• Fix deprecated assertEquals() (thanks to @nsoranzo). Pull Request 173
• Fix a method missing problem. Pull Request 174
• Sync "recent" galaxy runner util changes. Pull Request 177

0.9.0 (2019-04-12)

• Add configuration parameter to limit stream size read from disk. Pull Request 157
• Pass full job status for failed and lost jobs. Pull Request 159
• Improve message handling if problems occur during job setup/staging. Pull Request 160
• Rework preprocessing job state to improve restartability and reduce job loss. This change should be applied while no jobs are running. Pull Request 164
• Add support for overriding config through environment variables (thanks to @nuwang). Pull Request 165
• Minor docs updates (thanks to @afgane). Pull Request 170
• Python 3 fixes in Pulsar client (thanks to @mvdbeek). Pull Request 172

0.8.3 (2018-02-08)

• Create universal wheels to enable Python 3 support when installing from PyPI (thanks to @nsoranzo). Pull Request 156

0.8.1 (2018-02-08)

• Update link for logo image. Pull Request 145
• Minor error and log message typos (thanks to @blankenberg). Pull Request 146, Pull Request 153
• Fixes/improvements for catching quoted tool files. Pull Request 148
• Fix config sample parsing so run.sh works out of the box. Pull Request 149

0.8.0 (2017-09-21)

• Support new features in Galaxy job running/scripting so that Pulsar respects $GALAXY_VIRTUAL_ENV and $PRESERVE_GALAXY_ENVIRONMENT. Fix remote metadata in cases where the tool environment changes the python on $PATH. Pull Request 137
• Precreate Galaxy tool outputs on the remote before executing (fixes a bug related to missing output files on stage out). Pull Request 141
• Support the remote_transfer file action without setting the jobs_directory destination param Pull Request 136
• Fix invalid character in job managers documentation (thanks to @mapa17). Pull Request 130
• Fix conda_auto_* option resolution and include a sample dependency_resolvers_conf.xml (thanks to @mapa17). Pull Request 132
• Fix tox/Travis tests. Pull Request 138, Pull Request 139, Pull Request 140
• Fix a bug with AMQP acknowledgement. Pull Request 143

0.7.4 (2017-02-07)

• Fix Conda resolution and add a test case. 11ce744
• Style fixes for updated flake8 libraries. 93ab8a1, 3573341
• Remove unused script. 929bffa
• Fixup README. 629fdea

0.7.3 (2016-10-31)

• Fix "AttributeError" when submitting a job as a real user. Pull Request 124, Issue 123

0.7.2 (2016-08-31)

• Fix bug causing loops on in response to preprocessing error conditions.

0.7.1 (2016-08-29)

• Do a release to circumvent a tool version logic error in Galaxy ( released Galaxy versions think 0.7.0 < 0.7.0.dev3).

0.7.0 (2016-08-26)

• Update Makefile to allow release pulsar as an application and a library for Galaxy at the same time.
• Small update to test scripts for TravisCI changes.
• Improvements for embedded Galaxy runner. (TODO: fill this out)
• Remove support for Python 2.6. 60bf962
• Update docs to describe project goverance and reuse Galaxy's Code of Conduct. 7e23d43, dc47140
• Updated cluster slots detection for SLURM from Galaxy. cadfc5a
• Various changes to allow usage within Galaxy as a library. ce9d4f9
• Various changes to allow embedded Pulsar managers within Galaxy. ce9d4f9, d262323, 8f7c04a
• Introduce a separate working and metadata directory as required for Galaxy 16.04 that requires this separation. 6f4328e
• Improve logging and comments. 38953f3, a985107, ad33cb9
• Add Tox target for Python 2.7 unit testing. d7c524e
• Add Makefile command for setup.py develop. fd82d00

0.6.1 (2015-12-23)

• Tweak release process that left 0.6.0 with an incorrect PyPI description page.

0.6.0 (2015-12-23)

• Pulsar now depends on the new galaxy-lib Python package instead of manually synchronizing Python files across Pulsar and Galaxy.
• Numerous build and testing improvements.
• Fixed a documentation bug in the code (thanks to @erasche). e8814ae
• Remove galaxy.eggs stuff from Pulsar client (thanks to @natefoo). 00197f2
• Add new logo to README (thanks to @martenson). abbba40
• Implement an optional awknowledgement system on top of the message queue system (thanks to @natefoo). Pull Request 82 431088c
• Documentation fixes thanks to @remimarenco. Pull Request 78, Pull Request 80
• Fix project script bug introduced this cycle (thanks to @nsoranzo). 140a069
• Fix config.py on Windows (thanks to @ssorgatem). Pull Request 84
• Add a job manager for XSEDE jobs (thanks to @natefoo). 1017bc5
• Fix pip dependency installation (thanks to @afgane) Pull Request 73

0.5.0 (2015-05-08)

• Allow cURL downloader to resume transfers during staging in (thanks to @natefoo). 0c61bd9
• Fix to cURL downloaders status code handling (thanks to @natefoo). 86f95ce
• Fix non-wheel installs from PyPI. Issue 72
• Fix mesos imports for newer versions of mesos (thanks to @kellrott). fe3e919
• More, better logging. 2b3942d, fa2b6dc

0.4.0 (2015-04-20)

• Python 3 support. Pull Request 62
• Fix bug encountered when running pulsar-main and pulsar-config commands as scripts. 9d43ae0
• Add pulsar-run script for issues commands against a Pulsar server (experimental). 3cc7f74

0.3.0 (2015-04-12)

• Changed the name of project to Pulsar, moved to Github.
• New RESTful web services interface.
• SCP and Rsync file staging options added by E. Rasche. Pull Request
• Allow YAML based configuration.
• Support for more traditional pip/setup.py-style installs.
• Dozens of smaller bugfixes and documentation updates.

0.2.0

• Last version named the LWR - found on BitBucket.
• Still supported in Galaxy as of 15.03 the release.
• Introduced support for submitting to various queueing systems, operation as a Mesos framework, Docker support, and various other advanced deployment options.
• Message queue support.
• Framework for configurable file actions introduced.

0.1.0

• Simple support for running jobs managed by the Python LWR web process.

0.0.1

• See the original announcement and initial commit.