From 9df06576e6163efaf24d891092514368cd8f666d Mon Sep 17 00:00:00 2001
From: Steven Maude <git@stevenmaude.co.uk>
Date: Thu, 29 Jun 2023 18:06:56 +0100
Subject: [PATCH] Add some notes to README

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/README.md b/README.md
index 808f4b5..a1b1eb8 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,88 @@
+# Dev container experiment
+
+This is an experiment to see if
+we can make OpenSAFELY tooling easier for users to install,
+cross-platform and locally.
+
+It contains a `devcontainer.json` that configures a Visual Studio Code dev container.
+This container contains some rudimentary tooling that might get someone setup with OpenSAFELY,
+without installing Python themselves.
+
+## Requirements
+
+* Docker
+* Visual Studio Code
+
+## What gets installed?
+
+* Consult the [devcontainers.json](devcontainer/devcontainers.json) to see everything.
+* In brief:
+  * a Debian installation with Python and Git already installed
+  * Jupyter notebook
+  * a couple of Visual Studio Code extensions,
+    more as an example of how to do that
+  * OpenSAFELY (specified via the `requirements` files)
+
+## Trying out this repository
+
+### Starting up locally
+
+To run locally:
+
+1. Clone this repository with `git clone`.
+1. Change to the repository directory.
+1. Checkout this branch with `git checkout`.
+1. Run Visual Studio Code: `code .`
+1. Visual Studio Code should prompt that there is a dev container configuration
+   and ask if you want to reopen the folder in a container
+   (or go to VSCode's Command Palette and select "Reload in container").
+
+### Starting up via Codespaces
+
+Alternatively you can run this via GitHub Codespaces:
+
+1. Create a new, empty repository of your own under your own GitHub username.
+1. Push a copy (not a fork) of this repository to that remote repository.
+1. View this branch on GitHub, from the branches dropdown in the repository file view.
+1. Select "Code" and open a GitHub Codespace.
+
+(It has to be your own copy,
+because otherwise GitHub tries to open the Codespace under the `opensafely` organisation,
+which, at this time, does not allow me to do so due to billing issues.
+Your personal account gets an allowance of free Codespace usage per month.)
+
+### Running tools
+
+If the dev container starts successfully,
+you should be able to just run commands inside the VSCode terminal,
+which are run inside the dev container.
+
+Things you could try:
+
+* `opensafely run run_all`
+* `jupyter lab`
+* Running ehrQL's sandbox:
+  1. Download the example data:
+     `wget "https://github.com/opensafely-core/ehrql-example-data/archive/refs/heads/main.zip"`
+  2. Unzip the example data:
+     `unzip main.zip`
+  3. Run the sandbox:
+     `opensafely exec ehrql:v0 sandbox ehrql-example-data`
+
+## Potential issues
+
+* There are different ways VSCode can be installed;
+  for example, on Linux, there is a snap version.
+* Rootless Docker doesn't give the correct permissions:
+  https://github.com/microsoft/vscode-remote-release/issues/4646
+
+## Other ideas
+
+* [R Studio dev container installation](https://github.com/revodavid/devcontainers-rstudio)
+* [Installing a full desktop in a dev container](https://web.archive.org/web/20230320153217/https://technology.amis.nl/software-development/run-and-access-gui-inside-vs-code-devcontainers/)
+
+***
+
 # ${GITHUB_REPOSITORY_NAME}
 
 You can run this project via [Gitpod](https://gitpod.io) in a web browser by clicking on this badge: [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/${GITHUB_REPOSITORY})