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

@@ -0,0 +1,335 @@
+!!! 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,
+except this virtual machines has been configured for OpenSAFELY use.
+
+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. If you do not already have a GitHub account,
+   go to the GitHub pricing page,
+   and choose to sign up with a free account.
+1. Follow the process on GitHub's site.
+
+## Login to GitHub
+
+Whether you have created a new GitHub account,
+or are using an existing GitHub account,
+make sure that you are logged in to your 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.
+
+Create a new research code repository *under your own username*
+based on the research template.
+
+1. In your web browser,
+   go to the research code template repository.
+1. Follow GitHub's instructions for [creating a new repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template).
+
+!!! info
+
+    To give more details about the choices given
+    when creating a new repository from a template:
+
+    * You can enter any name and description that you choose for your repository.
+    * For this example,
+      it does not matter whether the repository visibility is public or private.
+      If you want others to see it,
+      then you can make it public.
+    * You do not need to select "Include all branches".
+    * You can ignore the mention of "GitHub Apps from GitHub Marketplace" in GitHub's instructions.
+
+!!! 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 research code repository created,
+you can launch a codespace from that repository:
+
+1. In a web browser,
+   go to your newly created research code repository on GitHub.
+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
+
+A codespace is self-contained with its own copy of your repository's files.
+This is just as if you were working on a local copy of the repository on your own computer.
+
+**Changes to the copy of your repository in the codespace do not automatically change the state of your published repository on GitHub.**
+
+To get changes from a codespace to the GitHub repository,
+there 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, non-exhaustive guide to what OpenSAFELY provides in the codespace.
+
+### 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 options.
+
+#### 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.
+* This may take a few moments to download the required files,
+  before it runs.
+
+!!! info
+
+    The research code template is currently based on a legacy cohort-extractor project.
+    In future,
+    we will amend this to work with ehrQL directly.
+
+    ehrQL is replacing cohort-extractor.
+
+### Following the ehrQL tutorial
+
+!!! info
+
+    This process will be simplified considerably 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.
+
+## Use of 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 your 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,
+    you will not get invoiced or charged.
+
+    If you run out of free quota,
+    GitHub can 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.

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