From fbbcccb35c2b8c2c602f18a58b2f71afb9f005bb 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 | 194 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 195 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..bd13d2231 --- /dev/null +++ b/docs/github-codespaces.md @@ -0,0 +1,194 @@ +!!! 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. + +## 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. + +## 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 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). + +## A quick guide to OpenSAFELY features + +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++. + +* See the OpenSAFELY CLI documentation for more. + +### + +### 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. + +#### Deleting a codespace + +See GitHub's documentation for how to delete a codespace. + +Unlike *stopping* a codespace, +this removes the codespace entirely, + +Once deleted, + +#### 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