In this tutorial, you will learn how to provision your Galaxy instance to support training modules from the GTN repository.

Tutorials in this repository are all supplemented with files describing the technical requirements to run them. This makes it easy to automate installation of tutorial requirements.

• data-library.yaml: describes the input datasets
• data-manager.yaml: describes the reference data required by tools
• workflows folder: contains one or more workflows with all steps in the tutorial
• tours folder: contains one or more yaml files describing interactive tours

Comment: Requirements

For more information about how to create these files, please see our module on specifying the technical requirements for your tutorial.

For just the list of Ephemeris commands needed for installation, skip to the Quickstart section at the end of this tutorial.

Agenda

In this tutorial, we will deal with:

1. Prepare for installation
   1. Start a local Galaxy
   2. Find your Galaxy API key
   3. Install Ephemeris
2. Installing tutorial requirements
   1. Installing an entire topic
   2. Installing a subset of components
3. Quickstart
4. Conclusion

Prepare for installation

If you have a Galaxy server already running somewhere and would like to support one or more training modules, ephemeris can be used to easily install all the required tools, reference data, data libraries, tours and workflows.

For the purposes of this training, we will create a Galaxy instance running on localhost:8080, but these instructions can be adapted for use with any Galaxy instance by replacing this value with the URL or IP address of your Galaxy server.

Start a local Galaxy

To setup a Galaxy server locally, we will first clone the Galaxy github repository, make a few small edits to the galaxy.yaml configuration file, and then start the server.

Hands-on: Setup a local Galaxy instance

1. Clone the github repository

   git clone https://github.com/galaxyproject/galaxy.git
   cd galaxy
   

2. Add yourself as admin user in config/galaxy.yaml

   cp config/galaxy.yml.sample config/galaxy.yml
   

   open the galaxy.yml file with your favorite editor and edit the following line with your email address:

   admin_users: user@example.org
   

3. Start Galaxy

   sh run.sh
   

   Galaxy will now install all its requirements, which may take a few minutes, when all is finished installing, you should see something like this in your screen:

   Starting server in PID 9560.
   serving on http://localhost:8080
   

4. Open Galaxy
   • Open a web browser
   • Navigate to localhost:8080 to access Galaxy

Find your Galaxy API key

In order to install the tutorial requirements, we will need the API key of an admin user.

Hands-on: Obtain Galaxy API key

1. Register an account on Galaxy using the email address you added to the config/galaxy.yml file
   • Once logged in, verify that you have a menu item named Admin in your top menu bar.
2. Go to your User -> Preferences in the top menu bar, then click on Manage API key
3. Click on Create a new key to generate an API key
   • Copy your API key to somewhere convenient, you will need it throughout this tutorial

Install Ephemeris

To install to training requirements to our Galaxy, we will use Ephemeris, let’s install it now:

Hands-on: Install Ephemeris

# optional: create a virtual environment
virtualenv .venv; . .venv/bin/activate

# install ephemeris
pip install ephemeris

Installing tutorial requirements

We have created a small bash script to automatically install all of a tutorial’s requirements to an existing Galaxy. It’s located in this repository under: bin/install_tutorial_requirements.sh

In this example we will install the requirements for the Reference-based RNASeq tutorial to the Galaxy instance running on localhost.

Hands-on: Install a tutorial

1. If you have not done so yet, clone the training material github repo:

   git clone https://github.com/galaxyproject/training-material.git
   cd training-material
   

2. Run the script to install the RNASeq tutorial

   bin/install_tutorial_requirements.sh topics/transcriptomics/tutorials/ref-based http://localhost:8080 <api key>
   

Installation may take some time. This script will automatically install the tools, create a data library and populate it with the input datasets from Zenodo, install and publish the workflows, and run any data managers that might be required.

The only thing the script cannot currently automate is the installation of the interactive tours. We will now do this manually by copying the contents of the tours folder to our Galaxy instance, in the folder $GALAXY_ROOT/config/plugins/tours

Hands-on: Install the interactive Tours

1. Copy the tour.yaml file from the training materials repo to Galaxy

   cp -r topics/transcriptomics/tutorials/ref-based/tours/ $GALAXY_ROOT/config/plugins/tours
   

Installing an entire topic

If you would like to install all the requirements for every tutorial within an entire topic, you can use the script in bin/install_topic_requirements.sh

Installing a subset of components

If you would like to pick and choose what to install for each tutorial, below are descriptions of the commands used to install each of the components (tools, workflows, reference data, data libraries, tours) please see the Quickstart section for the individual commands used by the script

Quickstart

Below is the list of commands used in this tutorial.

Using the scripts in this repository:

# Make sure you are in the root of the training-material repo
cd <training-materials repo root>

# install single tutorial
bin/install_tutorial_requirements.sh topics/<yourtopic>/tutorials/<yourtutorial> <Galaxy URL> <API key>

# install entire topic
bin/install_topic_requirements.sh topics/<yourtopic> <Galaxy URL> <API key>

Using ephemeris directly:

# install tools
shed-tools install -g <Galaxy URL> -a <API key> -t <(curl https://training.galaxyproject.org/training-material/api/topics/<topic>/tutorials/<tutorial>/tutorial.json | jq .admin_install_yaml -r)

# create data library with input datasets
setup-data-libraries -g <Galaxy URL> -a <API key> -i topics/<topic>/tutorials/<tutorial>/data-library.yaml

# install reference data
run-data-managers -g <Galaxy URL> -a <API key> --config topics/<topic>/tutorials/<tutorial>/data-manager.yaml

# install workflows
workflow-install --publish-workflows -g <Galaxy URL> -a <API key> -w topics/<topic>/tutorials/<tutorial>/workflows

# install tours
copy the contents of the "tours" directory for the tutorial to Galaxy's "config/plugins/tours/"

When data libraries are created, depending on the server settings, they may be created privately. You will need to fix their permissions either through the UI or the API if you have many datasets. UseGalaxy.eu uses a script to correct the permissions.

Conclusion

You've Finished the Tutorial

Please also consider filling out the Feedback Form as well!

Key points

• Technical requirements have been defined for all the training materials

• Ephemeris can be used to automatically install these requirements to an existing Galaxy

• Convenience scripts are provided in the training material repository allow for easy installation

• Docker images can easily be created per topic

Frequently Asked Questions

Feedback

Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.

Citing this Tutorial

1. Saskia Hiltemann, Bérénice Batut, Set up a Galaxy for Training (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/teaching/tutorials/setup-galaxy-for-training/tutorial.html Online; accessed TODAY
2. Hiltemann, Saskia, Rasche, Helena et al., 2023 Galaxy Training: A Powerful Framework for Teaching! PLOS Computational Biology 10.1371/journal.pcbi.1010752
3. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

BibTeX

@misc{teaching-setup-galaxy-for-training,
author = "Saskia Hiltemann and Bérénice Batut",
	title = "Set up a Galaxy for Training (Galaxy Training Materials)",
	year = "",
	month = "",
	day = ""
	url = "\url{https://training.galaxyproject.org/training-material/topics/teaching/tutorials/setup-galaxy-for-training/tutorial.html}",
	note = "[Online; accessed TODAY]"
}
@article{Hiltemann_2023,
	doi = {10.1371/journal.pcbi.1010752},
	url = {https://doi.org/10.1371%2Fjournal.pcbi.1010752},
	year = 2023,
	month = {jan},
	publisher = {Public Library of Science ({PLoS})},
	volume = {19},
	number = {1},
	pages = {e1010752},
	author = {Saskia Hiltemann and Helena Rasche and Simon Gladman and Hans-Rudolf Hotz and Delphine Larivi{\`{e}}re and Daniel Blankenberg and Pratik D. Jagtap and Thomas Wollmann and Anthony Bretaudeau and Nadia Gou{\'{e}} and Timothy J. Griffin and Coline Royaux and Yvan Le Bras and Subina Mehta and Anna Syme and Frederik Coppens and Bert Droesbeke and Nicola Soranzo and Wendi Bacon and Fotis Psomopoulos and Crist{\'{o}}bal Gallardo-Alba and John Davis and Melanie Christine Föll and Matthias Fahrner and Maria A. Doyle and Beatriz Serrano-Solano and Anne Claire Fouilloux and Peter van Heusden and Wolfgang Maier and Dave Clements and Florian Heyl and Björn Grüning and B{\'{e}}r{\'{e}}nice Batut and},
	editor = {Francis Ouellette},
	title = {Galaxy Training: A powerful framework for teaching!},
	journal = {PLoS Comput Biol} Computational Biology}
}

                   

Galaxy Administrators: Install the missing tools

You can use Ephemeris's shed-tools install command to install the tools used in this tutorial.

shed-tools install [-g GALAXY] [-a API_KEY] -t <(curl https://training.galaxyproject.org/training-material/api/topics/teaching/tutorials/setup-galaxy-for-training/tutorial.json | jq .admin_install_yaml -r)

Alternatively you can copy and paste the following YAML

---
install_tool_dependencies: true
install_repository_dependencies: true
install_resolver_dependencies: true
tools: []

Feedback

5 stars	2
4 stars	1

No feedback has been recieved yet for this training. Be the first one by filling in the feedback form from above.