One of the recurring challenges in research computing is not teaching the material itself. It’s getting everyone set up to run it.
Over the past six months, our software development team within Professor Reed Maxwell’s hydrology research lab supported several hands-on events involving Python notebooks, scientific software, and data analysis workflows. These included short courses, a software evaluation workshop, and a teacher professional development program, reaching roughly 30 participants with a wide range of technical backgrounds.
Across all of these events, we had the same goal: minimize time spent troubleshooting installations and maximize time spent engaging with the material.
Our Requirements
Although each event was different, our requirements were largely consistent:
- A way to run Jupyter notebooks easily
- Little or no software installation for participants
- Support for custom scientific software
- The ability to update materials as examples evolve
- Persistent workspaces for multi-day events
- An experience that felt approachable for non-programmers
For many workshop participants, asking them to create a virtual environment or install software ahead of time can quickly become a barrier to participation.
Evaluating the Options
We considered several common approaches.
Google Colab provides a familiar notebook interface and requires no local installation, but environments are temporary and custom software can require additional setup.
Binder offers excellent accessibility and requires no account creation, but publicly hosted Binder resources can be constrained during periods of heavy use.
Docker provides a reproducible environment and is already familiar to many research software engineers. However, requiring participants to install Docker can be challenging, particularly for attendees using government, corporate, or institution-managed laptops.
Ultimately, we decided to try GitHub Codespaces.
Why Codespaces Worked for Us
GitHub Codespaces provides a complete development environment that runs in the cloud and is accessible through a web browser.
For participants, the workflow is simple:
- Create a GitHub account.
- Open the repository.
- Launch a Codespace.
- Start working.
Because the environment is defined within the repository, every participant receives the same setup. This significantly reduces the “it works on my machine” problem that often consumes workshop time.
Codespaces also preserves work between sessions, which was especially useful for multi-day events. Participants could return to the same environment on subsequent days without reinstalling software or repeating setup steps.
Configuration
One feature we especially appreciated is that Codespaces configuration lives directly in the repository through a .devcontainer directory.
For simple projects, this can be as straightforward as installing a list of Python dependencies. More complex environments can reuse existing Dockerfiles, which is exactly what we did for workshops involving ParFlow. Since we already maintained a Docker-based installation process, we were able to leverage that work rather than create a separate environment specifically for training.
This approach also makes workshop materials easier to maintain over time. As notebooks, dependencies, and examples change, the environment configuration can evolve alongside the code in version control.
Lessons Learned
Overall, GitHub Codespaces worked well for our outreach and training use cases. The browser-based experience lowered barriers for participants and reduced the amount of setup support required from instructors.
There were a few limitations. Participants need GitHub accounts, which adds an extra onboarding step. We also occasionally encountered situations where a Codespace needed to be restarted unexpectedly. While these incidents were relatively minor, they are worth keeping in mind when planning a live event.
Despite those drawbacks, Codespaces provided a practical balance of reproducibility, ease of use, and flexibility. For our team, it allowed us to spend less time debugging participant environments and more time focusing on the science and software we actually wanted to teach.