From 811545e9f5dc47679271f4d8c32fe7311e6d1a38 Mon Sep 17 00:00:00 2001 From: Steven Maude Date: Thu, 6 Jul 2023 13:11:57 +0100 Subject: [PATCH] WIP: Add a basic explanation of GitHub Codespaces This is still an experiment, and depends on: opensafely/research-template#102 being merged to make this work. --- docs/github-codespaces.md | 295 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 296 insertions(+) create mode 100644 docs/github-codespaces.md diff --git a/docs/github-codespaces.md b/docs/github-codespaces.md new file mode 100644 index 000000000..db9dc7fc1 --- /dev/null +++ b/docs/github-codespaces.md @@ -0,0 +1,295 @@ +!!! warning + + GitHub Codespaces support is still being tested. + This documentation is subject to change. + +The OpenSAFELY research template contains a configuration +to allow you to run OpenSAFELY +**without any installation required on your own computer**. + +This uses GitHub Codespaces. +GitHub provide users with a free monthly quota of Codespaces use. + +This page: + +* explains what GitHub Codespaces is +* explains how to run some OpenSAFELY features in GitHub Codespaces +* briefly explains some features of GitHub Codespaces + and directs the reader to GitHub's documentation for more details + +You only require a web browser to follow the instructions in this page. + +## What is GitHub Codespaces? + +[Codespaces](https://github.com/features/codespaces) is a coding environment +hosted online by GitHub. +Codespaces can be accessed via your web browser +without any additional installation. + +A codespace provides: + +* a "virtual machine" — a computer running as software inside another computer + — that is hosted by GitHub +* a Visual Studio Code environment + for editing your project and running commands + +When you open a codespace in browser, +you get access to the Visual Studio Code environment. +Through that interface, +you can run commands inside the codespace's virtual machine. +This is just as if it were a real desktop or laptop that you were working on, +but does not require any installation. + +This removes the need to have anything other than a web browser installed +to work on OpenSAFELY projects. + +!!! info + A codespace refers specifically to such a virtual machine environment, + that contains a copy of your code to work on. + + This is not to be confused with a "code repository" + which is where code gets published on GitHub. + +## Create a GitHub account + +Before starting with OpenSAFELY in GitHub Codespaces, +you will need a free GitHub account: + +1. Create a free GitHub account, + if you do not already have one. +1. Login to that GitHub account. + +## Working on OpenSAFELY projects via GitHub Codespaces + +To start a Codespace, +you need to create a code repository that you can launch a codespace from. + +We will use the OpenSAFELY research template +as a basis for our code. + +### Create a code repository for your work + +You only need to create a code repository once for a particular project: + +1. Create a new research code repository *under your own username* + based on the research template. + +!!! warning + + This step will enable you to work on your OpenSAFELY research code in Codespaces, + and check that it would work with OpenSAFELY. + + **It will not allow you to run code on OpenSAFELY's platform.** + + For that, you would have to request that your repository is transferred to the `opensafely` organization. + Existing OpenSAFELY users typically create a repository within the `opensafely` organization. + +### Launch a codespace + +Once you have a code repository created, +you can launch a codespace from that repository: + +1. Navigate to the newly created research repository. +1. Click the "Code" button +1. + +### Navigating the codespace + +When this finishes launching, +you should see a Visual Studio Code editor with three panes: + +* on the left, the file explorer +* a terminal at the bottom-right +* a file editor at the upper-right + +### Editing code + +The file explorer shows the contents of your code repository. +You can open files by double-clicking them. + +### Updating files in the repository + +This is a two-step process. + +1. Save a file in Visual Studio Code. + This only saves the file locally inside the Codespace. + These changes will not yet show up in your GitHub code repository. +1. Use the Source Control view to add, commit and publish those changes + to your GitHub repository. + If you are unfamiliar with Visual Studio Code and GitHub, + [GitHub has a guide on using this](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes). + +When you update files by publishing to the repository's `main` branch, +this should trigger an automated check of whether your code will run in OpenSAFELY. +These checks can be viewed from the Actions tab, +accessed via your repository on GitHub's +You should be able to see an automated check running on the new version of your code. + +!!! info + + If you are comfortable with Git, + you can also [create and switch between different branches in the codespace](https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace), + +# A quick overview of what is included in the codespace + +Now that we have a GitHub codespace running, +we can use OpenSAFELY. + +Here is a short and non-exhaustive guide to how things work. + +### Running the OpenSAFELY CLI + +* You can run the OpenSAFELY CLI in GitHub Codespaces. + In the Visual Studio Code terminal, type `opensafely` and press ++Enter++. +* You should see the OpenSAFELY CLI help prompt. +* See the OpenSAFELY CLI documentation for more. + +#### Running the example cohort-extractor project + +* In the Visual Studio Code terminal, + type `opensafely run run_all` and then press ++Enter++ + to run the existing project. + +### Following the ehrQL tutorial + +!!! warning + + The default research template repository still uses the older cohort-extractor. + This makes getting started with ehrQL require some extra steps. + + This process will be improved in future. + +You will need to download the ehrQL example data by the following process: + +1. Ensure you are in the repository's top-level by changing directory to + it with `cd ~` +1. Create a new tutorial directory with: `mkdir learning-ehrql` +1. Download files: `wget …` +1. Unzip files: `unzip …` +1. You should see the files. +1. You can now remove the zipped file: `rm …` +1. Change into the tutorial directory with `cd learning-ehrql` + +With that done, you can proceed to "Running ehrQL". +It may be useful to read the tutorial "Installation and setup" page, +but everything else will then be ready for you. + +## Other features for development + +### Running Jupyterlab + +* In the Visual Studio Code terminal, + type `opensafely jupyter` and then press ++Enter++ + to launch the Jupyterlab server. +* Your web browser should open a new tab or window + or prompt you if you want to open a new tab or window. + This new tab or window allows you to use the Jupyterlab server. +* If this tab or window does not display, + you can navigate to the Ports tab in the terminal, + which will show the web address to the running server. + Click on that link to access the Jupyterlab server. +* You can edit and save files in your codespace from within Jupyterlab. + + !!! warning + + You will still need to use Visual Studio Code to publish those changes made in your codespace, + to your code repository + [as detailed above](#updating-files-in-the-repository). + +### Running command-line Python + +* In the Visual Studio Code terminal, + type `opensafely exec python` and then press ++Enter++ + to start command-line Python. + +### Running command-line R + +* In the Visual Studio Code terminal, + type `opensafely exec r` and then press ++Enter++ + to start command-line R. + +!!! info + + We may look into providing a better experience for developing R code in future. + +### Running command-line Stata + +!!! info + + This has not yet been tested, + but could be added in future. + +## GitHub Codespaces computer resources + +The default codespace has 2 computer processor cores (CPU cores) and 4 GB memory (RAM). +In some cases, +you may find that OpenSAFELY projects exceed the available RAM. + +GitHub Codespaces does have virtual machines with more CPU cores and RAM, +but these will use the free quota more quickly. + +It is possible to configure what virtual machine type the codespace has when launching the codespace. +See [GitHub's explanation of configuring advanced options](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository?tool=webui#creating-a-codespace-for-a-repository) for a codespace. + +It is also possible to [change a virtual machine type for an existing codespace](https://docs.github.com/en/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#changing-the-machine-type). + +## GitHub Codespaces billing + +GitHub gives all users a free and decent-sized monthly quota for Codespaces. +This is accessible without a paid account. +See [GitHub's pricing details](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). + +!!! note + + You will not get billed for using Codespaces, + unless you both: + + * set a Codespaces spending limit + * and add a payment method + + Without billing configured, + if you run out of free quota, + GitHub will only block you from using Codespaces until the next monthly cycle starts. + +### Managing codespaces + +If you close a codespace in your browser, +it still continues running. +You can return to an open codespace from the code repository. + +It is useful to stop or delete codespaces to prevent them from using your quota unnecessarily. + +#### Stopping a codespace + +See GitHub's documentation for how to stop a codespace. + +This stops a codespace running, +but allows you to restart it. + +Stopped codespaces still incur storage usage, +but not CPU usage. + +#### Deleting a codespace + +See GitHub's documentation for how to delete a codespace. + +Unlike *stopping* a codespace, +this removes the codespace entirely, + +Once deleted, the codespace will not incur any usage + +#### Idle timeout + +A codespace will eventually stop when it is not being used.. +This is a useful feature to prevent you from wasting free or paid Codespaces credit. +This setting can be configured to give a longer or shorter duration. +[See the GitHub documentation](https://docs.github.com/en/codespaces/customizing-your-codespace/setting-your-timeout-period-for-github-codespaces). + +!!! info + + We are still investigating how we can make Codespaces more useful + for researchers working on OpenSAFELY projects. + + Please feel free to ask us questions, + tell us about problems you find, + or give us any other feedback. diff --git a/mkdocs.yml b/mkdocs.yml index b0cbd779e..4bf1bce76 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,6 +35,7 @@ nav: - Overview: install-intro.md - Managing Gitpod workspaces: gitpod-workspaces.md - GitHub and Git: install-github-and-git.md + - Running OpenSAFELY in GitHub Codespaces: github-codespaces.md - Python: install-python.md - Docker: install-docker.md - OpenSAFELY CLI: opensafely-cli.md