Improve 101 intro, add devcontainer and docker basic instructions

.devcontainer/devcontainer.json

@@ -1,8 +1,14 @@
 {
-    "name": "${localWorkspaceFolderBasename}",
+    "forwardPorts": [8787],
+    "portsAttributes": {
+        "8787": {
+            "label": "RStudio Server",
+            "onAutoForward": "notify"
+        }
+    },
     "remoteUser":"rstudio",
-    "workspaceMount": "source=${localWorkspaceFolder},target=/home/rstudio/lesson,type=bind",
-    "workspaceFolder": "/home/rstudio/lesson",
+    "workspaceMount": "source=${localWorkspaceFolder},target=/home/rstudio/lessons/${localWorkspaceFolderBasename},type=bind",
+    "workspaceFolder": "/home/rstudio/lessons/${localWorkspaceFolderBasename}",
     "mounts": [
         "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/rstudio/.ssh,type=bind,consistency=cached",
         "source=${localEnv:HOME}${localEnv:USERPROFILE}/.gnupg,target=/home/rstudio/.gnupg,type=bind,consistency=cached"
@@ -13,8 +19,13 @@
     },
     "postCreateCommand": {
         "pre_echo": "echo 'Installing lesson prerequisites - please wait...'",
-        "tty": "export GPG_TTY=$(tty)",
-        "pre_prep": "bash -c /home/rstudio/.workbench/ci_lesson_pre_prep.sh"
+        "gpg_reset": "gpgconf --kill all",
+        "lesson_deps": "Rscript /home/rstudio/.workbench/setup_lesson_deps.R",
+        "fortify": "Rscript /home/rstudio/.workbench/fortify_renv_cache.R"
+    },
+    "containerEnv": {
+        "DISABLE_AUTH": "true",
+        "GPG_TTY": "/dev/pts/0"
     },
     "hostRequirements": {
         "cpus": 2

config.yaml

@@ -14,7 +14,7 @@ title: 'Workbench Docs' # FIXME
 created: 2025-06-30
 
 # Comma-separated list of keywords for the lesson
-keywords: 'workbench, sandpaper, pegboard, varnish, The Carpentries, lessons'
+keywords: 'workbench, sandpaper, pegboard, varnish, The Carpentries, lessons, docker, devcontainers'
 
 # Life cycle stage of the lesson
 # possible values: pre-alpha, alpha, beta, stable
@@ -38,31 +38,24 @@ contact: 'team@carpentries.org'
 # individual pages in each dropdown section. Leave blank to
 # include all pages in the folder.
 #
-# Example -------------
-#
-# episodes:
-# - introduction.md
-# - first-steps.md
-#
-# learners:
-# - setup.md
-#
-# instructors:
-# - instructor-notes.md
-#
 # profiles:
 # - one-learner.md
 # - another-learner.md
 
 # Order of episodes in your lesson
 episodes:
-- introduction.md
+- 01-first-lesson.md
 
 # Information for Learners
 learners:
+- setup.md
+- devcontainer.md
+- docker.md
+- faq.md
 
 # Information for Instructors
 instructors:
+- instructor-notes.md
 
 # Learner Profiles
 profiles:

episodes/01-first-lesson.md

@@ -0,0 +1,25 @@
+---
+title: "Building Lessons"
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- How do we build lessons using a local Workbench installation?
+- How do we build lessons using the online GitHub architecture?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- Demonstrate how to use local R and shell Workbench commands 
+- Demonstrate how to build and deploy lessons on GitHub
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Local Lesson Builds
+
+Some stuff
+
+## GitHub Lesson Builds
+
+More stuff

learners/devcontainer.md

@@ -0,0 +1,97 @@
+---
+title: 'Devcontainer Extras'
+---
+
+It is good practice to use separate environments when developing software.
+Many solutions exist across different programming languages and operating systems.
+
+The Workbench needs additional system and R dependencies to work, and these can be time consuming to install.
+As such, we provide specific separate environments using Docker which have all the required dependencies installed for you, so you can get to using the Workbench straight away on any PC or operating system that supports Docker.
+
+:::::::::::::::::::::: prereq
+
+You will need to have followed the [101 Quick Setup](learners/setup.md#101-docker) instructions for Docker to proceed.
+
+We also presume you have installed and are using the VSCode IDE, which can be installed using the following [link](https://code.visualstudio.com/)
+
+:::::::::::::::::::::::::::::
+
+## Using a lesson's devcontainer
+
+The first thing to check is that a lesson supports devcontainers.
+
+::::::::::::::::::::::: callout
+
+### Which lessons support devcontainers?
+
+Any lesson that has:
+
+- A `.devcontainer` folder in the root of its repository
+- and a `Dockerfile` and `devcontainer.json` inside that folder
+
+can be run inside a devcontainer.
+
+An example can be seen in [this repository](https://github.com/carpentries/workbench-docs/tree/main/.devcontainer).
+
+The base workbench templates ([md](https://github.com/carpentries/workbench-template-md/tree/main/.devcontainer) and [rmd](https://github.com/carpentries/workbench-template-rmd/tree/main/.devcontainer)) both specify a `.devcontainer` environment, so new lessons using this template will be able to immediately use devcontainers!
+
+:::::::::::::::::::::::::::::::
+
+Once a lesson has a `.devcontainer` folder, Dockerfile and JSON specification, an IDE like VSCode can be used to setup and run that devcontainer to host your lesson within that IDE.
+This makes it quick and easy to start developing and building a lesson without needing to install any system or R packages or dependencies.
+
+## Running the Workbench
+
+### Updating the Workbench
+
+By default, the devcontainer environment will use the `latest` version of the `carpentries-workbench` Docker image, i.e. `carpentries-workbench:latest`. These images are prebuilt.
+
+When first opening a devcontainer-enabled lesson the devcontainer system will download the latest image for you.
+
+If a new version of the Workbench is released, your devcontainer will not automatically use these new versions. To update the devcontainer image, open the VSCode command menu with <kbd>F1</kbd> and select the `Dev Containers: Rebuild Container` option.
+This will download the new image version for you.
+
+### Using a specific Workbench Docker version
+
+Similarly, if you want to use a specific Workbench release, edit the `.devcontainer/Dockerfile` file, replacing `latest` on the first line with the version you require.
+
+For example, to use Workbench version `dev-0.2.2`:
+
+```bash
+FROM carpentries/workbench-docker:latest
+```
+
+becomes
+
+```bash
+FROM carpentries/workbench-docker:dev-0.2.2
+```
+
+Save the file, and rebuild the container by opening the command menu with <kbd>F1</kbd> and selecting the `Dev Containers: Rebuild Container` option.
+
+::::::::::::::::::::::: callout
+
+### What Docker image versions are available?
+
+The full list of Docker images and their version _tags_ are [on Dockerhub](https://hub.docker.com/r/carpentries/workbench-docker/tags).
+
+:::::::::::::::::::::::::::::::
+
+
+## What's next?
+
+### Not used the Workbench before?
+
+Please follow the [Building your first Workbench lesson](episodes/01-first-lesson.md) to familiarise yourself with the lesson build process.
+
+### What content can go in a lesson?
+
+Please check the [Lesson Content and Styling](episodes/02-content-styling.md) and [Additional Lesson Content](03-additional-content.md) documentation.
+
+### Using additional R packages?
+
+Please familiarise yourself with our [Packages and renv](episodes/04-r-and-renv.md) information.
+
+### Lesson in a non-English language?
+
+Please read our [Internationalisation](episodes/05-il8n.md) guide.

learners/docker.md

@@ -0,0 +1,6 @@
+---
+title: 'Docker Extras'
+---
+
+## Docker
+

learners/faq.md

@@ -4,7 +4,14 @@ title: 'Workbench FAQs'
 
 ## Installation FAQ
 
-### Why does it take 5 lines of code to install the infrastructure?
+### Is the Workbench open source?
+
+Yes! All the Workbench dependencies are open source.
+
+If you are choosing to use Docker or devcontainers, we acknowledge that some of these tools including the VSCode IDE, are not completely open source.
+You do not need to use these technologies to use the Workbench if you choose not to - the manual local installation of the Workbench will work in the exact same way.
+
+### Why does it take 5 lines of code to install the infrastructure locally?
 
 As the Workbench packages are in The Carpentries R-Universe and not CRAN, we need to tell R to get the packages from R-Universe.
 
@@ -34,7 +41,16 @@ In this case, select "yes".
 
 ## Opening your R environment
 
-If you are using RStudio, you can open it by double-clicking on the RStudio icon in your application launcher; you do not have to open R separately to use RStudio.
+### RStudio
+
+If you are using RStudio, you can open it by:
+
+- going to the RStudio Server URL provided when you run the Docker or devcontainer environment
+- or, double-clicking on the RStudio icon in your application launcher
+
+You do not have to open R separately to use RStudio.
+
+### R
 
 If you are using R, you can open it in your terminal application by typing `R`.
 Your prompt will be replaced by a `>`, which indicates that you are in R's interactive [REPL](https://glosario.carpentries.org/en/#repl).