If you are working on your own training materials and want preview them online without installing anything on your computer, you can do this using GitPod!

Agenda

In this tutorial, you will learn how to run a local instance of the GTN website:

1. Setting up Gitpod
2. The GitPod Workspace
3. Build and preview the GTN website
4. Editing Training Materials on GitPod
5. Saving your changes back to GitHub
6. Closing your GitPod Workspace

Setting up Gitpod

Hands-on: Setting up GitPod

1. Create a fork of the GTN GitHub repository

   Tip: Forking the GTN repository

   • Go on the GitHub repository: github.com/galaxyproject/training-material
   • Click on the Fork button (top-right corner of the page)

   

2. Already have a fork of the GTN? Make sure it is up to date.

   Tip: Updating the default branch from master to main

   If you created your fork a long time ago, the default branch on your fork may still be called master instead of main

   1. Point your browser to your fork of the GTN repository
      • The url will be https://github.com/<your username>/training_material (replacing with your GitHub username)

   2. Check the default branch that is shown (at top left).

      

   3. Does it say main?
      • Congrats, nothing to do, you can skip the rest of these steps

   4. Does it say master? Then you need to update it, following the instructions below

   5. Go to your fork’s settings (Click on the gear icon called “Settings”)
   6. Find “Branches” on the left
   7. If it says master you can click on the ⇆ icon to switch branches.
   8. Select main (it may not be present).
   9. If it isn’t present, use the pencil icon to rename master to main.

   Tip: Syncing your Fork of the GTN

   Whenever you want to contribute something new to the GTN, it is important to start with an up-to-date branch. To do this, you should always update the main branch of your fork, before creating a so-called feature branch, a branch where you make your changes.

   1. Point your browser to your fork of the GTN repository
      • The url will be https://github.com/<your username>/training_material (replacing ‘your username’ with your GitHub username)

   2. You might see a message like “This branch is 367 commits behind galaxyproject/training-material:main.” as in the screenshot below.

      

   3. Click the Sync Fork button on your fork to update it to the latest version.

   4. TIP: never work directly on your main branch, since that will make the sync process more difficult. Always create a new branch before committing your changes.

3. Open your browser and navigate to gitpod.io/login
   • Note: don’t leave the /login part of the URL off, it will lead you to a different flavour of GitPod. We are using Gitpod classic
4. Log in with GitHub
5. Click on Configure your own repository under the Workspaces menu
6. Under Select a repository choose your fork, e.g. https://github.com/shiltemann/training-material
7. Click continue
   • This will create an enviroment where you can make changes to the GTN and preview them
   • Note: It can take quite some time to start up the first time (15-30 minutes)
   • We can make future starts a lot faster using prebuilds (see tip box below), you can configure this now while you wait

   

   Tip: Enabling Prebuilds for your GitPod workspace

   Prebuilds can speed up the launch of your GitPod workspace after the first time. When this is enabled, starting a workspace will check if there is a previous build to reuse. This should bring startup times down to 3-5 minutes.

   Enable Prebuilds

   1. On the GitPod website, click on your name in the top left of the screen
   2. Select Repositories
   3. Add your fork as a repository
   4. On the left, click Prebuild settings
   5. Click the slider in front of Prebuilds are disabled to toggle the setting
   6. Set Branch Filter to Default Branch

   

   Run a prebuild now

   1. In GitPod, click on your name in the top left of the screen
   2. Select Prebuilds
   3. Click Run a Prebuild
   4. Select a Repository: your fork
   5. Click Run Prebuild
      • This will also take a bit of time to complete
      • In the future, it will automatically refresh this prebuild every 20 commits, so you only have to do this once

   Note: Prebuilds expire if you haven’t used them in 7 days, so if you have taken a longer break from GTN you might have to wait longer again the first time. But otherwise it should bring the launch time down to around 3-5 minutes.

8. Once the setup is finished, you should see a page something like this:

   Tip: Make this even easier with the GitPod browser extension!

   1. To make this even easier, you can install the GitPod browser extension
      • Firefox
      • Chrome or Edge
   2. Now it is just a single click to open any GitHub repository in GitPod

The GitPod Workspace

Let’s have a closer look at the GitPod workspace:

• Left: Here you see all the files in the GTN repository
• Top: This is the main window where you can view and edit files
• Bottom: Terminal window. Here you can type commands (e.g. to build the website preview) and read output and error messages.

Build and preview the GTN website

Before we start making any changes, let’s build the website and get a live preview.

Hands-on: Setting up GitPod

1. In the terminal window (bottom), type the following command: make serve-gitpod

   

2. The first time you run this command, it will install some dependencies, so it may take a little bit of time (a few minutes)
   • Next times will be a lot faster! (~30 seconds)
3. When the build process is finished, the terminal will show you a link, and a window should popup with a preview on the right.

   • You may have to click the “Try Again” button if the preview was generated before the site building completed

     

   • Click on the link in the terminal to see the GTN in full-screen: Server address: http://127.0.0.1:4000/training-material/

   

   Tip: Not opening?

   Some browsers block popups by default, you may need to allow GitPod to show popups in order to click links.

4. This will take you to a preview of the GTN website
   • Note: It will take you the 404 page because GitPod doesn’t know the location of the GTN homepage, but from here you can just click the homepage button.

Editing Training Materials on GitPod

Now that you have the GitPod environment working and we have a live preview up, let’s make some changes to the GTN materials and get an instant preview.

Scenario: You have spotted a typo in one of the tutorials, and would like to fix this and see the resulting GTN webpage.

Hands-on: Make and view changes

1. In the preview of the GTN website, open the following tutorial:
   • Topic: “Introduction to Galaxy Analyses” topic
   • Tutorial: “A Short Introduction to Galaxy””
   • We will edit this tutorial and watch the live preview window for the effects

2. On the file browser on the left, open the following file:

   topics/introduction/tutorials/galaxy-intro-short/tutorial.md
   

   Tip: Finding files faster?

   You can use the key combination ctrl-p to launch the file search dialog and simply enter the text topics/introduction/tutorials/galaxy-intro-short/tutorial.md

3. Change the title of the tutorial
   • From: “A Short Introduction to Galaxy”
   • To: “A Short and Cool Introduction to Galaxy”

   

   • You should immediately see a message in the terminal saying “regenerating”. GitPod has detected your changes and is rebuilding the website.

   

4. Move to the top right panel where the GTN is previewed and refresh the frame
   • galaxy-refresh Refresh button in front of the address bar of the preview panel
   • You can also open the preview in it’s own brower tab, using the galaxy_instance button at the top-right corner of the preview window. Then you can reload the page the regular way (e.g. F5 or ctrl + r or the reload button in the browser)
5. You should see the change you made:

In this way you can edit files in the text editor, and see the effects in the website preview.

Saving your changes back to GitHub

When you have finished your changes, it all looks good in the preview, you want to save your changes back to GitHub so that you can either continue later, or make a Pull Request to the GTN to contribute your changes.

Hands-on: Save changes

1. Option 1: via the terminal
   • Hit ctrl+c if your preview was still running to stop it
   • Create a new branch, commit your changes, push changes:

   git checkout -b fix-title
   git commit -m "update tutorial title" topics/introduction/tutorials/galaxy-intro-short/tutorial.md
   git push origin fix-title
   

2. Option 2: via the web interface
   • Create a new branch:
     • On the bottom-left, click on the branch logo (probably labelled “main”)
     • Enter fix-title as the name for your new branch (at top of window)
     • Choose “+ Create new branch…” from the dropdown
   • Commit changes:
     • On the left menu, click on the “changed files” tab
     • Click on the “+” icon next to the file we edited to stage changes
     • Hit the checkmark icon at the top to commit the changes
     • Enter a commit message (top of window) - Publish changes
   • Click the cloud button at bottom left to publish your changes
3. Your changes are now saved to your fork, and you can make a PR via the GitHub interface.
   • If you used option 1 and want to do that right away, you can click on the link in the terminal:

Tip: GitPod Permissions

If this is your first time using GitPod, you may need to grant permissions to let GitPod push to your GitHub fork This will take you through a process to authorize GitPod, and set permissions If it doesn’t take you to GitPod’s permission page because your browser blocks popups, you can set them on this page.

Closing your GitPod Workspace

Everybody gets 50 hours per month for free on GitPod, so it is wise to close your GitPod workspace when you are finished with it, to conserve your quotum.

Hands-on: Shutting down your GitPod workspace

1. Click on the menu button at the top left corner of the screen
   • Choose “Gitpod: Stop Workspace”

   

You've Finished the Tutorial

Please also consider filling out the Feedback Form as well!

Key points

• GitPod can be used to serve the GTN training materials

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, Running the GTN website online using GitPod (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/contributing/tutorials/gitpod/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{contributing-gitpod,
author = "Saskia Hiltemann",
	title = "Running the GTN website online using GitPod (Galaxy Training Materials)",
	year = "",
	month = "",
	day = "",
	url = "\url{https://training.galaxyproject.org/training-material/topics/contributing/tutorials/gitpod/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}
}

                   

Developing GTN training material

This tutorial is part of a series to develop GTN training material, feel free to also look at:

1. Contributing with GitHub via command-line
2. Overview of the Galaxy Training Material
3. Creating Interactive Galaxy Tours
4. Including a new topic
5. Teaching Python
6. GTN Metadata
7. Tools, Data, and Workflows for tutorials
8. Running the GTN website online using GitHub CodeSpaces
9. Adding Quizzes to your Tutorial
10. Adding auto-generated video to your slides
11. Principles of learning and how they apply to training and teaching
12. Design and plan session, course, materials
13. Running the GTN website online using GitPod
14. Contributing with GitHub via its interface
15. Updating diffs in admin training
16. Generating PDF artefacts of the website
17. Running the GTN website locally using the command line
18. Creating a new tutorial
19. Single Cell Publication - Data Plotting
20. FAIR Galaxy Training Material
21. Single Cell Publication - Data Analysis
22. Creating content in Markdown
23. Creating Slides
24. Updating tool versions in a tutorial

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/contributing/tutorials/gitpod/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	3
4 stars	1
3 stars	2

August 2024

• 3 stars: Liked: Everything is described very extensively and nicely and it's easy to follow Disliked: Unfortunately, I wasn't able to get through the "Build and preview the GTN website" and "Editing Training Materials on GitPod", I can modify the md template, but it doesn't get reflected in the preview. Clicking on the server address also throws me an error :/

March 2023

• 5 stars: Liked: Good alternative to local running of GTN, thanks

November 2022

• 4 stars: Liked: step by step, screenshots, global structure of the training content, indications when things seem to get wrong when in fact it is not, good job! Disliked: Difficult to know what to do when GitPod sends back an error after the "make serve-gitpod" command instead of serving a preview of GTN. I can guess it is a GitPod problem and not a GTN tutorial problem, still I feel helpless not knowing what to do to solve this problem.

October 2021

• 5 stars: Liked: Very detailed Disliked: It would help if the sites name and the drop-down button at the top is static. So even when I scroll to to end of this page, I can easily click on the drop-down button and access other files without having to scroll all the way back up

July 2021

• 5 stars: Liked: Very complete, sufficiently detailed to allow non-computer-science people to go through this with all the questions we could have being answered. Disliked: The video from GCC2021 training week corresponding to this topic is also very well. Maybe a link to this video for people who need to see things in movement to be reassured would be nice :)