Running the GTN website online using GitPod

Authors: orcid logoAvatarSaskia Hiltemann
Overview
Questions:

  • How can I get a preview of the GTN website using GitPod?

Objectives:

  • Preview the GTN website online via GitPod

  • Make changes to the GTN website and preview those changes

Time estimation: 15 minutes
Supporting Materials:
Last modification: Oct 18, 2022
License: Tutorial Content is licensed under Creative Commons Attribution 4.0 International License The GTN Framework is licensed under MIT

Introduction

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. Introduction
  2. Setting up Gitpod
  3. The GitPod Workspace
  4. Build and preview the GTN website
  5. Editing Training Materials on GitPod
  6. Saving your changes back to GitHub
  7. Closing your GitPod Workspace

Setting up Gitpod

Hands-on: Setting up GitPod
  1. Create a fork of the GTN GitHub repository

    If you already have a fork, fantastic! But a common issue is that the main branch gets outdated, or your fork was from before we renamed the master branch to main.

    • Start by browsing to your fork in GitHub
    • Check the default branch that is shown? Does it say master? Then you need to update it. (Note - don’t just switch branches from “master” to “main”, follow the instructions below to reset the default branch to “main”.)
      1. Go to your fork’s settings (Click on the gear icon called “Settings”)
      2. Find “Branches” on the left
      3. If it says master you can click on the ⇆ icon to switch branches.
      4. Select main (it may not be present).
      5. If it isn’t present, use the pencil icon to rename master to main.
      6. Now you can update it in the next step

    • Is your fork using main? Fantastic, but you might need to update it. GitHub has a built in feature for this as shown below:

      Github with the top bar of a repository shown, the button for 'Fetch Upstream' has been clicked.

  2. Open your browser and navigate to gitpod.io
  3. Log in with GitHub GitPod sign-in menu with various options, including GitHub.
  4. Copy the link to your fork of the GTN, e.g. https://github.com/shiltemann/training-material

  5. In the browser’s address bar, prefix the entire URL with gitpod.io/# and press Enter.

    For example, gitpod.io/#https://github.com/<your username>/training-material

    1. To make this even easier, you can install the GitPod browser extension
    2. Now it is just a single click to open any GitHub repository in GitPod screenshot of the button the GitPod browser extension adds to GitHub repository .
  6. Gitpod will now configure your environment. This may take some time progress indicator of GitPod first setup.
  7. Once the setup is finished, you should see a page something like this: GitPod welcome screen.

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.

GitPod welcome screen.

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

    output in the terminal after issuing the make serve-gitpod command.

  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 need to click ‘Try Again’ to load the GTN.

      gitpod with the GTN open in the right panel, but saying "Try again".

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

    output in the terminal after the build process has completed .

    screenshot of firefox permissions dialog which shows blocked windows and an allow menu. 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.

screenshot of gitpod's code editor with a tutorial open, and the GTN preview on the right.

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

    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. we changed the title of the tutorial in the text editor window. the terminal shows a message stating the website is being regenerated.
  4. Move to the top right panel where the GTN is previewed and refresh the frame
    • Firefox: right-click -> This Frame -> Reload Frame
    • Chrome: right-click -> Reload frame
    • You can also open the preview in it’s own brower tab, using the 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: The updated preview with our changed tutorial title.

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 “master” or “main”) button on the bottom of the page with the current branch.
      • 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 button on the left menu to show changed files.
      • Click on the “+” icon next to the file we edited to stage changes stage changes button.
      • 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 publish changes button.
  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: link in the terminal to open a PR.

Note: GitPod Permissions

If this is your first time using GitPod, you may need to grant permissions to let GitPod push to your GitHub fork prompt to changes permissions. This will take you through a process to authorize GitPod, and set permissions permission settings for GitPod. 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”

    stop workspace option in the main menu.

Key points

  • GitPod can be used to serve the GTN training materials

Frequently Asked Questions

Have questions about this tutorial? Check out the tutorial FAQ page or the FAQ page for the Contributing to the Galaxy Training Material topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help Forum

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.

Click here to load Google feedback frame

Citing this Tutorial

  1. Saskia Hiltemann, 2022 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. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012 


@misc{contributing-gitpod,
author = "Saskia Hiltemann",
title = "Running the GTN website online using GitPod (Galaxy Training Materials)",
year = "2022",
month = "10",
day = "18"
url = "\url{https://training.galaxyproject.org/training-material/topics/contributing/tutorials/gitpod/tutorial.html}",
note = "[Online; accessed TODAY]"
}
@article{Batut_2018,
    doi = {10.1016/j.cels.2018.05.012},
    url = {https://doi.org/10.1016%2Fj.cels.2018.05.012},
    year = 2018,
    month = {jun},
    publisher = {Elsevier {BV}},
    volume = {6},
    number = {6},
    pages = {752--758.e1},
    author = {B{\'{e}}r{\'{e}}nice Batut and Saskia Hiltemann and Andrea Bagnacani and Dannon Baker and Vivek Bhardwaj and Clemens Blank and Anthony Bretaudeau and Loraine Brillet-Gu{\'{e}}guen and Martin {\v{C}}ech and John Chilton and Dave Clements and Olivia Doppelt-Azeroual and Anika Erxleben and Mallory Ann Freeberg and Simon Gladman and Youri Hoogstrate and Hans-Rudolf Hotz and Torsten Houwaart and Pratik Jagtap and Delphine Larivi{\`{e}}re and Gildas Le Corguill{\'{e}} and Thomas Manke and Fabien Mareuil and Fidel Ram{\'{\i}}rez and Devon Ryan and Florian Christoph Sigloch and Nicola Soranzo and Joachim Wolff and Pavankumar Videm and Markus Wolfien and Aisanjiang Wubuli and Dilmurat Yusuf and James Taylor and Rolf Backofen and Anton Nekrutenko and Björn Grüning},
    title = {Community-Driven Data Analysis Training for Biology},
    journal = {Cell Systems}
}

Congratulations on successfully completing this tutorial!
Developing GTN training material
This tutorial is part of a series to develop GTN training material, feel free to also look at:
  1. Overview of the Galaxy Training Material
  2. Adding auto-generated video to your slides
  3. Adding Quizzes to your Tutorial
  4. Contributing with GitHub via command-line
  5. Contributing with GitHub via its interface
  6. Creating a new tutorial
  7. Creating content in Markdown
  8. Creating Interactive Galaxy Tours
  9. Creating Slides
  10. Design and plan session, course, materials
  11. Generating PDF artefacts of the website
  12. GTN Metadata
  13. Including a new topic
  14. Principles of learning and how they apply to training and teaching
  15. Running the GTN website locally
  16. Running the GTN website online using GitPod
  17. Teaching Python
  18. Tools, Data, and Workflows for tutorials
  19. Updating diffs in admin training