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 GitHub CodeSpaces! Everybody gets 60 free hours of CodeSpaces per month

Agenda

In this tutorial, you will learn how to contribute to the GTN website:

1. Launching CodeSpaces
2. The VScode environment
3. Build and preview the GTN website
4. Editing Training Materials on CodeSpaces
5. Saving your changes back to GitHub
6. Closing your CodeSpace

Launching CodeSpaces

Hands-on: Setting up GitPod

1. Navigate to the GTN GitHub repository, github.com/galaxyproject/training-material

2. Click on the green Code button

3. At the top, switch to the CodeSpaces tab

4. Click on Create codespace on main
   • Note: if you switch to a specific branch in GitHub first, you can create a codespace for that branch
5. This will setup a Visual Studio Code environment for you
   • It may take a couple minutes to finish setting everything up
   • In this environment you can also build the GTN website to preview your changes
   • When everything is ready, you should see something like this:

   

The VScode environment

Let’s have a closer look at your CodeSpaces window:

• 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 preview

   • This will take 2-3 minutes to complete

   

2. When the build process is finished, a preview window will automatically open (at the top right)
   • The preview will show the GTN 404 (codespace doesnt know what to show)
   • Just click on Return to homepage.

   Tip: Window not opening?

   If the preview window doesn’t open for you, or if you close it and want to reopen it, you can always do so as follows:

   1. Go to the Ports tab of the bottom panel

      

   2. Hover over the link in the Forwarded Address column, 3 icons should appear

      

   3. Click on:

      • The world/globe icon to open the GTN preview in a new window, or
      • Or, click on the window icon to the right of the globe icon to preview the GTN in a tab inside the codespaces environment

3. If you opened the GTN preview inside the codespace, your window will now look something like this:

   

   Tip: Not opening?

   Some browsers block popups by default, you may need to allow CodeSpaces to show popups in your browser.

Editing Training Materials on CodeSpaces

Now that you have the codespace 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
   

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

   

4. Save the file
   • CTRL+S to save the file
   • You should immediately see a message in the terminal saying “regenerating”. CodeSpaces has detected your changes and is rebuilding the website.

   

5. Move to the top right panel where the GTN is previewed and refresh the website
   • 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)

   Tip: Reload not working?

   It is possible that this reload button gives you the 404 again, in that case there are 2 solutions

   1. Right-click in the preview panel, and choose
      • Chrome: “Reload Frame”
      • Firefox: “This Frame -> Reload Frame”
   2. Open the preview in it’s own browser tab
      • Click the galaxy_instance button at the top-right corner of the preview window

6. 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: Comitting changes

First we commit our changes inside the codespace:

1. Go to the “Source Control” icon on the left menu bar (it should have a blue dot on it)
2. You should see your changed file (tutorial.md)
3. Hover over the file name, and *click on the plus icon* to stage it
4. Enter a commit message (e.g. “updated tutorial title)
5. Click on the green Commit button

Next, we will push these changes to a branch/fork. We will do this from outside of our codespace for convenience.

Hands-on: Pushing changes to GitHub

1. In your browser (outside of codespaces), navigate to the GTN GitHub page
2. Click on the green Code button again
3. Click on the 3-dots menu to the right of your (randomly generated) codespace name
4. Choose Export changes to a branch
   • For you, it could be Export changes to fork
5. Once it is done, click See branch button
   • This will take you to the new branch
   • Click the Compare & pull request button to create a PR for your changes

Closing your CodeSpace

Everybody gets 60 hours per month for free on CodeSpaces. Your codespace will automatically shut down after 30 minutes of inactivity, but it is always a good idea to close your CodeSpace when you are finished with it, to conserve your quotum.

Hands-on: Shutting down your CodeSpace

1. Return to the GTN GitHub page

2. Click on the green Code button again

3. Under the Codespaces tab, you should see your running codespace

   

4. Click on the 3-dots menu to the right of your (randomly generated) codespace name

5. In this menu you can quit your codespace in two ways:

   • Stop codespace: your changes will be kept and you can restart the codespace later

   • Delete your codespace. Any changes you did not commit and push to GitHub are lost.

   • In this menu you can also resume a stopped codespace by simply clicking Open in Browswer

Congrats! You learned how to contribute to the GTN by using the CodeSpaces environment!

You've Finished the Tutorial

Please also consider filling out the Feedback Form as well!

Key points

• GitHub CodeSpaces can be used to change and preview the GTN training materials without installing anything on your machine

• Everybody gets 60 free hours per month on CodeSpaces

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

                   

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. Contributing with GitHub via its interface
5. Generating PDF artefacts of the website
6. Tools, Data, and Workflows for tutorials
7. Teaching Python
8. Running the GTN website online using GitHub CodeSpaces
9. Design and plan session, course, materials
10. GTN Metadata
11. Running the GTN website online using GitPod
12. Adding auto-generated video to your slides
13. Including a new topic
14. Adding Quizzes to your Tutorial
15. Principles of learning and how they apply to training and teaching
16. Updating diffs in admin training
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

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/running-codespaces/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

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