From 4e70d52a84c2c6dd61af131d3db3358c953066b6 Mon Sep 17 00:00:00 2001 From: froggleston Date: Wed, 30 Jul 2025 22:09:39 +0100 Subject: [PATCH 01/18] Improve 101 intro, add devcontainer and docker basic instructions --- learners/setup.md | 103 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 80 insertions(+), 23 deletions(-) diff --git a/learners/setup.md b/learners/setup.md index 8507619..cd7217c 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,11 +2,7 @@ title: '101 Quick Start: Setting up your Workbench environment' --- -### Local vs Online - -You can use the Workbench completely within GitHub using our templates, but we recommend working through the local setup instructions as they will be useful for lesson development and debugging. - -## Local Installation of the Workbench {#101-local} +## Installation of the Workbench {#101-install} The Workbench lesson infrastructure is built on Git, the R language, and pandoc. It consists of four components: @@ -19,7 +15,82 @@ It consists of four components: Details of how these tools work together are explained in the [TODO](../episodes/todo.md). In short, you can interact with the lesson source content and the Workbench tools to author and preview your lesson. -### Required Software {#required} +### What installation method should I choose? + +We provide four mechanisms to interact with the Workbench: + +- Devcontainers (online or local) **[recommended]** + - We recommend using devcontainers as everything will be installed for you whether you are using an online or local environment, with minimal setup. + - **If no devcontainer is available for the lesson you wish to work on, please use the manual installation route, or Docker if you are comfortable with it.** +- Docker (local) + - The Docker option can be useful for those that already have experience with Docker and containers, and are happy to do some manual configuration or wish to have more flexibility. + - **Initial setup with docker is very straightfoward but can get complicated depending on your operating system!** +- Manual local installation (local) + - Installing all the requirements manually on your local operating system is a longer process, but can be useful if you want to learn how to get an environment set up and will teach you more about the Workbench framework. + - **If docker and devcontainers are not suitable for you, installing things manually is completely acceptable!** +- GitHub (online) + - Moving your development completely online by using GitHub's Codespaces or Dev environment is an excellent choice if you have fast internet and are comfortable with this process. + - **Be advised that this option may incur a cost depending on your GitHub account status!** + +::::::::::::::::::::: callout + +### Why would I want to install locally if all these other options exist? + +You can use the Workbench completely within devcontainers or Docker locally, or through GitHub using our templates. + +However, we still would recommend working through the [local setup instructions](#101-manual) at least once as they will be useful for lesson development and debugging in future. + +::::::::::::::::::::::::::::: + +## Devcontainers {#101-devcontainer} + +Devcontainers are a way of remotely or locally setting up a coding environment based on a preconfigured "blueprint". +This blueprint is used by Integrated Development Environments (IDEs) like VSCode, VSCodium, PyCharm, and EnvBuilder, to initiate and configure an environment for you. +This can make it much quicker to get up and running with lesson development. + +The only thing you need to use devcontainers is Docker, so please read the [Docker installation instructions](#101-docker) to install Docker Desktop or the Docker Engine for your operating system. + +Please note, if you are not comfortable with Docker or the Workbench, we recommend going through the installation steps below. + +Once you have Docker set up, please follow our full devcontainer instructions are in [TODO](../episodes/todo.md). + +::::::::::::::::::::: callout + +### Are devcontainers available for all lessons? + +Devcontainer blueprints are already provided by our [workbench-template-rmd][rmd-template] and [workbench-template-md][md-template] lesson templates, so when creating a new lesson you will get access to devcontainers automatically. + +However, not all Workbench-compatible lessons will have devcontainers enabled (a `.devcontainer` folder within the repository). +To add devcontainer support to a pre-existing lesson, please follow the [devcontainer import instructions TODO](../episodes/todo.md) + +We will also be rolling these out into existing lessons across our official lesson programs too! + +::::::::::::::::::::::::::::: + +## Docker {#101-docker} + +The documentation below for each operating system goes through how to manually install the Workbench dependencies, requirements, and packages. +To make this lengthy process shorter, the Workbench development team also provides Docker images of each release of the Workbench that are used for our GitHub workflows that build our core curriculum lessons. +You can use these Docker images to run the Workbench on your local system too! + +Docker Desktop is available for all operating systems (Windows, Mac and Linux), so we recommend installing this. + +### Docker Desktop + +Install Docker Desktop for [your operating system](https://docs.docker.com/desktop/). + +Once installed, choose one of the following ways to interact with the Docker system: + +1. Via the Docker Desktop GUI app +2. Via the command line terminal (bash on Linux/Windows WSL/git bash, terminal on the Mac) + +After Docker Desktop/Docker Engine is set up, you can use the [Workbench docker image directly](https://github.com/froggleston/workbench-dev/blob/frog-docker-update-1/docker.qmd), or use the [devcontainer](#101-devcontainer) route above. + +Please note, if you are not comfortable with Docker or the Workbench, we recommend going through the [manual installation steps](#101-manual) below. + +## Manual Local Installation {#101-manual} + +### Required Software {#101-required} This setup document will take you through the process of installing or upgrading the required software on your local computer or server. @@ -38,7 +109,7 @@ This setup document will take you through the process of installing or upgrading repos = c("https://carpentries.r-universe.dev/", getOption("repos"))) ``` -### Recommended Software {#recommend} +### Recommended Software {#101-recommend} If you are using R or pandoc for the first time, we recommend using [the RStudio IDE][rstudio] for the following reasons: @@ -61,22 +132,6 @@ Newer versions will often contain important bug fixes that are important to the Jump to the installation instructions for your system: [Windows](#windows), [MacOS](#mac), or [Linux](#linux). -::::::::::::::::::::: callout - -#### Optional: Setting up the Workbench environment using Docker - -The following documentation goes through how to manually install the Workbench dependencies, requirements, and packages. - -The Workbench development team also provides Docker images of each release of the Workbench that are used for our GitHub workflows that build our core curriculum lessons. -However, you can use these Docker images to run the Workbench on your local system too! - -If you are interested in using these images to build your lessons, please read the [Workbench Docker setup instructions](https://github.com/froggleston/workbench-dev/blob/frog-docker-update-1/docker.qmd). - -Please note, if you are not comfortable with Docker or the Workbench, we recommend going through the installation steps below. - -::::::::::::::::::::::::::::: - - ## Installing on Windows {#windows} ### Git @@ -591,6 +646,8 @@ The following resources are extremely helpful for setting up authentication cred [R]: https://cran.rstudio.org/ [pandoc]: https://pandoc.org/ [{tinkr}]: https://docs.ropensci.org/tinkr/ +[rmd-template]: https://github.com/carpentries/workbench-template-rmd +[md-template]: https://github.com/carpentries/workbench-template-md [^workspace]: By default, R will ask if you want to save your workspace to a hidden file called `.RData`. This is loaded when you start R, restoring your environment with all of the packages and objects you had previously loaded. From 5b792f7aa07f5f49662e8f70991328c509d23dea Mon Sep 17 00:00:00 2001 From: froggleston Date: Wed, 30 Jul 2025 23:17:32 +0100 Subject: [PATCH 02/18] Add 101 docker command and Rstudio instructions --- learners/setup.md | 47 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/learners/setup.md b/learners/setup.md index cd7217c..245422c 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -45,17 +45,34 @@ However, we still would recommend working through the [local setup instructions] ## Devcontainers {#101-devcontainer} Devcontainers are a way of remotely or locally setting up a coding environment based on a preconfigured "blueprint". -This blueprint is used by Integrated Development Environments (IDEs) like VSCode, VSCodium, PyCharm, and EnvBuilder, to initiate and configure an environment for you. +This blueprint is used by Integrated Development Environments (IDEs) like VSCode, vscodium, IDEA, Cursor or Zed, to initiate and configure an environment for you. This can make it much quicker to get up and running with lesson development. -The only thing you need to use devcontainers is Docker, so please read the [Docker installation instructions](#101-docker) to install Docker Desktop or the Docker Engine for your operating system. +To use devcontainers you need: -Please note, if you are not comfortable with Docker or the Workbench, we recommend going through the installation steps below. +- Docker: please read the [Docker installation instructions](#101-docker) to install Docker Desktop or the Docker Engine for your operating system. +- An IDE that supports devcontainers: We recommend [VSCode](https://code.visualstudio.com/) (free but not completely open source). + +Please note, if you are not comfortable with using Docker or the Workbench, we recommend going through the installation steps below. Once you have Docker set up, please follow our full devcontainer instructions are in [TODO](../episodes/todo.md). ::::::::::::::::::::: callout +### What if I don't want to use VSCode? + +Sadly the devcontainer specification is only fully supported in a small number of IDEs. +VSCode is recommended in our lessons and it natively supports devcontainers. +Getting devcontainers to work in other fully open source IDEs like `vscodium` and `zed` are not as simple as to be easy for novices. + +Therefore we would recommend using VSCode as whilst it is partially open source, it is a reliable and very well supported piece of software. + +If this is not an option, then we would recommend either using the [Docker image directly](#101-docker) as it comes bundled with RStudio which you can use to work on your lesson. + +::::::::::::::::::::::::::::: + +::::::::::::::::::::: callout + ### Are devcontainers available for all lessons? Devcontainer blueprints are already provided by our [workbench-template-rmd][rmd-template] and [workbench-template-md][md-template] lesson templates, so when creating a new lesson you will get access to devcontainers automatically. @@ -84,7 +101,26 @@ Once installed, choose one of the following ways to interact with the Docker sys 1. Via the Docker Desktop GUI app 2. Via the command line terminal (bash on Linux/Windows WSL/git bash, terminal on the Mac) -After Docker Desktop/Docker Engine is set up, you can use the [Workbench docker image directly](https://github.com/froggleston/workbench-dev/blob/frog-docker-update-1/docker.qmd), or use the [devcontainer](#101-devcontainer) route above. +### Running the Workbench Docker container + +After Docker Desktop/Docker Engine is set up, you can use the following command from the terminal (`git bash`, WSL, or MacOS Terminal app): + +```bash +docker run --name carpentries-workbench \ + -p 8787:8787 \ + -v ~/.ssh:/home/rstudio/.ssh:ro \ + -v ~/.gitconfig:/home/rstudio/.gitconfig \ + -e DISABLE_AUTH=true \ + -d carpentries/workbench-docker:latest +``` + +In the Docker Desktop app, you should see an entry appear in the "Containers" tab with the name `carpentries-workbench`. + +You can now open a web browser and navigate to `http://localhost:8787` which will connect to the RStudio server running in the Docker container. +You're good to go! +Please continue with the [Test Your Installation](#install-test) instructions. + +More information and docker runtime options are described in the [Workbench docker documentation](https://github.com/froggleston/workbench-dev/blob/frog-docker-update-1/docker.qmd). Please note, if you are not comfortable with Docker or the Workbench, we recommend going through the [manual installation steps](#101-manual) below. @@ -564,8 +600,7 @@ For example, for the error above, use `sudo apt install libxslt1-dev`. ## Test your installation {#install-test} -Now that you have installed the lesson components, it is a good idea to run a small test to verify that these components work together. -To test your installation **open RStudio** (or launch R if you have not installed RStudio) and enter the following commands to confirm everything works: +To test your installation **open RStudio** either as the locally installed app or in the browser if using Docker (or launch R if you have not installed RStudio and are not using Docker/devcontainers) and enter the following commands to confirm everything works: ```r rmarkdown::pandoc_version() From 9cda0007b15e2243933d8336dc02f38600f36914 Mon Sep 17 00:00:00 2001 From: froggleston Date: Mon, 15 Sep 2025 09:56:29 +0100 Subject: [PATCH 03/18] Initial commit of 101 setup and devcontainer instructions --- devcontainer.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++ learners/faq.md | 20 ++++++++++++-- learners/setup.md | 25 +++++++++++++++--- 3 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 devcontainer.md diff --git a/devcontainer.md b/devcontainer.md new file mode 100644 index 0000000..40e4e36 --- /dev/null +++ b/devcontainer.md @@ -0,0 +1,66 @@ +--- +title: 'Devcontainers' +--- + +It's 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 long-winded 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 +- A `Dockerfile` and `devcontainer.json` inside that folder + +in the root of its repository can be run inside a devcontainer. + +An example can be seen in the [x](TODO.md) repository. + +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. + +### Using VSCode to start the devcontainer + +Make sure Docker Desktop is running. + +Open VSCode: + +- either, by double clicking the icon in your OS, going to `File`, `Open Folder...`, and navigating to a lesson folder +- or, open a terminal, navigate to a lesson folder and type: + +```bash + cd ~/lessons/shell-novice + code . +``` + +NB: Note the space between `code` and `.`! + +Once VSCode has opened the folder, after a short time, a popup should appear in the bottom right of the IDE saying `Folder contains a Devcontainer configuration file. Reopen folder to develop in a container`, with an option button to `Reopen in container`. +Click this button and wait for VSCode to read the configuration file and setup the devcontainer environment. + +Various popups will appear in the bottom right, showing progress. +You can click on the `Show log` link in any of the popups that show it to see any logs of the setup process. + +The setup process can take a while the first time you run it for a lesson. +After the first time, it will be much quicker to start subsequent uses of the environment. diff --git a/learners/faq.md b/learners/faq.md index 8c94b90..50b6d17 100644 --- a/learners/faq.md +++ b/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 +- 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). diff --git a/learners/setup.md b/learners/setup.md index 245422c..25817b2 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -21,6 +21,7 @@ We provide four mechanisms to interact with the Workbench: - Devcontainers (online or local) **[recommended]** - We recommend using devcontainers as everything will be installed for you whether you are using an online or local environment, with minimal setup. + - Lessons with devcontainer support will have a `.devcontainer` folder in the root of the repository. - **If no devcontainer is available for the lesson you wish to work on, please use the manual installation route, or Docker if you are comfortable with it.** - Docker (local) - The Docker option can be useful for those that already have experience with Docker and containers, and are happy to do some manual configuration or wish to have more flexibility. @@ -45,17 +46,17 @@ However, we still would recommend working through the [local setup instructions] ## Devcontainers {#101-devcontainer} Devcontainers are a way of remotely or locally setting up a coding environment based on a preconfigured "blueprint". -This blueprint is used by Integrated Development Environments (IDEs) like VSCode, vscodium, IDEA, Cursor or Zed, to initiate and configure an environment for you. +This blueprint is used by Integrated Development Environments (IDEs) like VSCode, vscodium, IDEA, or Zed, to initiate and configure an environment for you. This can make it much quicker to get up and running with lesson development. To use devcontainers you need: - Docker: please read the [Docker installation instructions](#101-docker) to install Docker Desktop or the Docker Engine for your operating system. -- An IDE that supports devcontainers: We recommend [VSCode](https://code.visualstudio.com/) (free but not completely open source). +- An IDE that supports devcontainers: We recommend [VSCode](https://code.visualstudio.com/) as it has the most complete and easy to set up devcontainer support. We acknowledge that VSCode is free but not completely open source. Please note, if you are not comfortable with using Docker or the Workbench, we recommend going through the installation steps below. -Once you have Docker set up, please follow our full devcontainer instructions are in [TODO](../episodes/todo.md). +Once you have Docker set up, please follow our full instructions in the [devcontainer documentation](../devcontainer.md). ::::::::::::::::::::: callout @@ -105,6 +106,24 @@ Once installed, choose one of the following ways to interact with the Docker sys After Docker Desktop/Docker Engine is set up, you can use the following command from the terminal (`git bash`, WSL, or MacOS Terminal app): +```bash +# go home +cd ~ + +# make a `lessons` folder in your home directory and clone in a lesson +mkdir ~/lessons +cd ~/lessons +git clone git@github.com:swcarpentry/shell-novice.git + +# create a workbench-lessons named volume, and copy in the shell-novice content +curl -s https://raw.githubusercontent.com/carpentries/workbench-docker/main/scripts/setup_named_volume.sh | bash -s -- ~/lessons/shell-novice + +# start the workbench container +curl -s https://raw.githubusercontent.com/carpentries/workbench-docker/main/scripts/run_workbench.sh | bash +``` + +Or more longhand if you want to control various docker options: + ```bash docker run --name carpentries-workbench \ -p 8787:8787 \ From 6492e9323c3676a6e059d28feded24fe679890be Mon Sep 17 00:00:00 2001 From: froggleston Date: Tue, 16 Sep 2025 11:55:05 +0100 Subject: [PATCH 04/18] Separate docker and devcontainer details into extras --- .devcontainer/Dockerfile | 5 ++ .devcontainer/devcontainer.json | 18 +++++++ config.yaml | 6 ++- devcontainer.md | 86 +++++++++++++++++++++++++++++++-- episodes/01-first-lesson.md | 25 ++++++++++ learners/docker.md | 6 +++ learners/setup.md | 17 +++---- 7 files changed, 147 insertions(+), 16 deletions(-) create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/devcontainer.json create mode 100644 episodes/01-first-lesson.md create mode 100644 learners/docker.md diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..d3e2862 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,5 @@ +FROM carpentries/workbench-docker:dev-0.2.2 + +## this could be used to run userland scripts e.g. +## users could add specific dependencies or configurations +## RUN scripts/userland.sh diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..8d03dd6 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,18 @@ +{ + "remoteUser":"rstudio", + "workspaceMount": "source=${localWorkspaceFolder},target=/home/rstudio/lesson,type=bind", + "workspaceFolder": "/home/rstudio/lesson", + "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" + ], + "build": { + "dockerfile": "Dockerfile", + "context": ".." + }, + "postCreateCommand": { + "pre_echo": "echo 'Installing lesson prerequisites - please wait...'", + "lesson_deps": "Rscript /home/rstudio/.workbench/setup_lesson_deps.R", + "fortify": "Rscript /home/rstudio/.workbench/fortify_renv_cache.R" + } +} diff --git a/config.yaml b/config.yaml index 23f2938..db921ac 100644 --- a/config.yaml +++ b/config.yaml @@ -56,13 +56,17 @@ contact: 'team@carpentries.org' # Order of episodes in your lesson episodes: -- introduction.md +- 01-first-lesson.md # Information for Learners learners: +- setup.md +- faq.md +- docker.md # Information for Instructors instructors: +- instructor-notes.md # Learner Profiles profiles: diff --git a/devcontainer.md b/devcontainer.md index 40e4e36..fcf8ef5 100644 --- a/devcontainer.md +++ b/devcontainer.md @@ -1,5 +1,5 @@ --- -title: 'Devcontainers' +title: 'Devcontainer Extras' --- It's good practice to use separate environments when developing software. @@ -31,7 +31,7 @@ Any lesson that has: in the root of its repository can be run inside a devcontainer. -An example can be seen in the [x](TODO.md) repository. +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! @@ -42,7 +42,7 @@ This makes it quick and easy to start developing and building a lesson without n ### Using VSCode to start the devcontainer -Make sure Docker Desktop is running. +Make sure Docker Desktop is running and that you are connected to the Internet. Open VSCode: @@ -59,8 +59,84 @@ NB: Note the space between `code` and `.`! Once VSCode has opened the folder, after a short time, a popup should appear in the bottom right of the IDE saying `Folder contains a Devcontainer configuration file. Reopen folder to develop in a container`, with an option button to `Reopen in container`. Click this button and wait for VSCode to read the configuration file and setup the devcontainer environment. +:::::::::::::::::::: callout + +### Troubleshooting + +If this popup does not appear, open the command menu in VSCode with the `F1` function key. +Your cursor will appear in the command menu bar at the top of the window, prefixed with a `>` symbol. +Start typing `open folder` and select the `Dev Containers: Open Folder in Container...` option. + +Similarly if you have any issues with the container at any point, you can open the command menu with `F1`, start typing `rebuild`, and select the `Dev Containers: Rebuild and Reopen in Container...`. This should be used judiciously as it will often reinstall dependencies so can take a few minutes. + +:::::::::::::::::::::::::::: + Various popups will appear in the bottom right, showing progress. You can click on the `Show log` link in any of the popups that show it to see any logs of the setup process. -The setup process can take a while the first time you run it for a lesson. -After the first time, it will be much quicker to start subsequent uses of the environment. +The setup process can take a few minutes the first time you run it for a lesson. +After the first time, it will be much quicker to start subsequent uses of the environment as the Docker image would be downloaded and stored for reuse. + +## Running the Workbench + +As all Workbench components are preinstalled in the devcontainer for you, you can start building your lesson! + +Open a terminal in VSCode by going to the `Terminal` menu in the top menu bar and click `New Terminal`. +An Ubuntu `bash` terminal window should appear in VSCode. +This bash shell will be running **inside** the devcontainer, so should look something like: + +```bash +rstudio@55a86b63e4ab:~/lesson$ +``` + +Here, you can perform any shell or R actions as you would usually for lesson development. + +### 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 `F1` 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 `F1` and selecting the `Dev Containers: Rebuild Container` option. + + +## 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. + +### Using different Workbench versions + +The devcontainer will always use the `latest` version of diff --git a/episodes/01-first-lesson.md b/episodes/01-first-lesson.md new file mode 100644 index 0000000..375759d --- /dev/null +++ b/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 huild 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 diff --git a/learners/docker.md b/learners/docker.md new file mode 100644 index 0000000..19840e1 --- /dev/null +++ b/learners/docker.md @@ -0,0 +1,6 @@ +--- +title: 'Docker Extras' +--- + +## Docker + diff --git a/learners/setup.md b/learners/setup.md index 25817b2..d466430 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -139,7 +139,7 @@ You can now open a web browser and navigate to `http://localhost:8787` which wil You're good to go! Please continue with the [Test Your Installation](#install-test) instructions. -More information and docker runtime options are described in the [Workbench docker documentation](https://github.com/froggleston/workbench-dev/blob/frog-docker-update-1/docker.qmd). +More information and docker runtime options are described in the [Docker guide](docker.md) and [Workbench developer docker documentation](https://github.com/froggleston/workbench-dev/blob/frog-docker-update-1/docker.qmd). Please note, if you are not comfortable with Docker or the Workbench, we recommend going through the [manual installation steps](#101-manual) below. @@ -178,10 +178,6 @@ If you do not want to use RStudio, that's perfectly okay and expected! We want to you to be able work with the new template with the tools with which you're most familiar. If you feel comfortable using a different tool (e.g. the command line or VSCode), then you should install R and pandoc separately and make sure that they are in your PATH. -### Installation - -This will guide you through installing the foundational software and infrastructure packages on your computer. - If you already have software installed and are curious if you should update it to a newer version, the answer is almost always, yes. Newer versions will often contain important bug fixes that are important to the security of your computer. @@ -465,7 +461,7 @@ If your Ubuntu version is not listed, check the [RStudio Previous Versions](http ::::::::::: callout -##### Optional: verify the install +### Optional: verify the install You can optionally verify the download before installing by following the instructions at . @@ -545,7 +541,7 @@ install.packages(c("sandpaper", "varnish", "pegboard")) ::::::::::::: discussion -#### Saving these settings for later +### Saving these settings for later To not have to run this block of code every time you want to update, add the following code into your `~/.Rprofile` to run it every time you open your terminal: @@ -553,7 +549,7 @@ To not have to run this block of code every time you want to update, add the fol :::::: solution -#### Add this to `~/.Rprofile` +### Add this to `~/.Rprofile` Open the `nano` text editor: @@ -583,7 +579,7 @@ local({ ::::::::::::: callout -#### What if I get errors installing packages? +### What if I get errors installing packages? If you run into errors (non-zero exit status), it probably means that you were missing a C library dependency that needs to be installed via your package manager (i.e. apt). To resolve these issues, scroll back in the log and you might find messages that looks similar to this: @@ -617,7 +613,8 @@ For example, for the error above, use `sudo apt install libxslt1-dev`. ::::::::::::::::::::: -## Test your installation {#install-test} + +## Test your Workbench installation {#install-test} To test your installation **open RStudio** either as the locally installed app or in the browser if using Docker (or launch R if you have not installed RStudio and are not using Docker/devcontainers) and enter the following commands to confirm everything works: From 267104034ec4a602a127ebf610a04ba461acd07d Mon Sep 17 00:00:00 2001 From: froggleston Date: Tue, 16 Sep 2025 11:55:30 +0100 Subject: [PATCH 05/18] Move devcontainer extras to learners --- devcontainer.md => learners/devcontainer.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename devcontainer.md => learners/devcontainer.md (100%) diff --git a/devcontainer.md b/learners/devcontainer.md similarity index 100% rename from devcontainer.md rename to learners/devcontainer.md From f75405e1b92a122998e9e63948819add9f8bbbaf Mon Sep 17 00:00:00 2001 From: froggleston Date: Wed, 17 Sep 2025 12:35:35 +0100 Subject: [PATCH 06/18] Finish initial container docs --- .devcontainer/devcontainer.json | 14 +++++- config.yaml | 3 +- learners/devcontainer.md | 65 ++++---------------------- learners/setup.md | 82 ++++++++++++++++++++++++++++++++- 4 files changed, 104 insertions(+), 60 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 8d03dd6..234ea3b 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,7 +1,14 @@ { + "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" @@ -14,5 +21,8 @@ "pre_echo": "echo 'Installing lesson prerequisites - please wait...'", "lesson_deps": "Rscript /home/rstudio/.workbench/setup_lesson_deps.R", "fortify": "Rscript /home/rstudio/.workbench/fortify_renv_cache.R" + }, + "containerEnv": { + "DISABLE_AUTH": "true" } } diff --git a/config.yaml b/config.yaml index db921ac..53e2e49 100644 --- a/config.yaml +++ b/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 @@ -62,6 +62,7 @@ episodes: learners: - setup.md - faq.md +- devcontainer.md - docker.md # Information for Instructors diff --git a/learners/devcontainer.md b/learners/devcontainer.md index fcf8ef5..efaa247 100644 --- a/learners/devcontainer.md +++ b/learners/devcontainer.md @@ -40,64 +40,15 @@ The base workbench templates ([md](https://github.com/carpentries/workbench-temp 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. -### Using VSCode to start the devcontainer - -Make sure Docker Desktop is running and that you are connected to the Internet. - -Open VSCode: - -- either, by double clicking the icon in your OS, going to `File`, `Open Folder...`, and navigating to a lesson folder -- or, open a terminal, navigate to a lesson folder and type: - -```bash - cd ~/lessons/shell-novice - code . -``` - -NB: Note the space between `code` and `.`! - -Once VSCode has opened the folder, after a short time, a popup should appear in the bottom right of the IDE saying `Folder contains a Devcontainer configuration file. Reopen folder to develop in a container`, with an option button to `Reopen in container`. -Click this button and wait for VSCode to read the configuration file and setup the devcontainer environment. - -:::::::::::::::::::: callout - -### Troubleshooting - -If this popup does not appear, open the command menu in VSCode with the `F1` function key. -Your cursor will appear in the command menu bar at the top of the window, prefixed with a `>` symbol. -Start typing `open folder` and select the `Dev Containers: Open Folder in Container...` option. - -Similarly if you have any issues with the container at any point, you can open the command menu with `F1`, start typing `rebuild`, and select the `Dev Containers: Rebuild and Reopen in Container...`. This should be used judiciously as it will often reinstall dependencies so can take a few minutes. - -:::::::::::::::::::::::::::: - -Various popups will appear in the bottom right, showing progress. -You can click on the `Show log` link in any of the popups that show it to see any logs of the setup process. - -The setup process can take a few minutes the first time you run it for a lesson. -After the first time, it will be much quicker to start subsequent uses of the environment as the Docker image would be downloaded and stored for reuse. - ## Running the Workbench -As all Workbench components are preinstalled in the devcontainer for you, you can start building your lesson! - -Open a terminal in VSCode by going to the `Terminal` menu in the top menu bar and click `New Terminal`. -An Ubuntu `bash` terminal window should appear in VSCode. -This bash shell will be running **inside** the devcontainer, so should look something like: - -```bash -rstudio@55a86b63e4ab:~/lesson$ -``` - -Here, you can perform any shell or R actions as you would usually for lesson development. - ### 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 `F1` and select the `Dev Containers: Rebuild Container` option. +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 F1 and select the `Dev Containers: Rebuild Container` option. This will download the new image version for you. ### Using a specific Workbench Docker version @@ -116,7 +67,15 @@ becomes FROM carpentries/workbench-docker:dev-0.2.2 ``` -Save the file, and rebuild the container by opening the command menu with `F1` and selecting the `Dev Containers: Rebuild Container` option. +Save the file, and rebuild the container by opening the command menu with F1 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? @@ -136,7 +95,3 @@ Please familiarise yourself with our [Packages and renv](episodes/04-r-and-renv. ### Lesson in a non-English language? Please read our [Internationalisation](episodes/05-il8n.md) guide. - -### Using different Workbench versions - -The devcontainer will always use the `latest` version of diff --git a/learners/setup.md b/learners/setup.md index d466430..e7b5418 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -54,9 +54,67 @@ To use devcontainers you need: - Docker: please read the [Docker installation instructions](#101-docker) to install Docker Desktop or the Docker Engine for your operating system. - An IDE that supports devcontainers: We recommend [VSCode](https://code.visualstudio.com/) as it has the most complete and easy to set up devcontainer support. We acknowledge that VSCode is free but not completely open source. -Please note, if you are not comfortable with using Docker or the Workbench, we recommend going through the installation steps below. +Please note, if you are not comfortable with using Docker or the Workbench, we recommend going through the [manual installation](#101-manual) steps below. -Once you have Docker set up, please follow our full instructions in the [devcontainer documentation](../devcontainer.md). +### Starting up the devcontainer + +Make sure Docker Desktop is running and that you are connected to the Internet. + +Open VSCode: + +- either, by double clicking the icon in your OS, going to `File`, `Open Folder...`, and navigating to a lesson folder +- or, open a terminal, navigate to a lesson folder and start VSCode by typing: + +```bash + cd ~/lessons/shell-novice + code . +``` + +NB: Note the space between `code` and `.`! + +Once VSCode has opened the folder, after a short time, a popup should appear in the bottom right of the IDE saying `Folder contains a Devcontainer configuration file. Reopen folder to develop in a container`, with an option button to `Reopen in container`. +Click this button and wait for VSCode to read the configuration file and setup the devcontainer environment. + +:::::::::::::::::::: callout + +### Troubleshooting + +If this popup does not appear, open the command menu in VSCode with the F1 function key. +Your cursor will appear in the command menu bar at the top of the window, prefixed with a `>` symbol. +Start typing `open folder` and select the `Dev Containers: Open Folder in Container...` option. + +Similarly if you have any issues with the container at any point, you can open the command menu with F1, start typing `rebuild`, and select the `Dev Containers: Rebuild and Reopen in Container...`. This should be used judiciously as it will often reinstall dependencies so can take a few minutes. + +:::::::::::::::::::::::::::: + +Various popups will appear in the bottom right, showing progress. +You can click on the `Show log` link in any of the popups that show it to see any logs of the setup process. + +The setup process can take a few minutes the first time you run it for a lesson. +After the first time, it will be much quicker to start subsequent uses of the environment as the Docker image would be downloaded and stored for reuse. + +:::::::::::::::::::: callout + +### Lessons with a lot of dependencies + +For those RMarkdown lessons that require a large number of R packages, this first start of the devcontainer can take quite a long time. + +:::::::::::::::::::::::::::: + + +### Running the Workbench + +Open a terminal in VSCode by going to the `Terminal` menu in the top menu bar and click `New Terminal`. +An Ubuntu `bash` terminal window should appear in VSCode. +This bash shell will be running **inside** the devcontainer, so should look something like: + +```bash +rstudio@55a86b63e4ab:~/lesson$ +``` + +Here, you can perform any shell or R actions as you would usually for lesson development. + +For more information and information, please check the full [devcontainer documentation](devcontainer.md). ::::::::::::::::::::: callout @@ -70,6 +128,14 @@ Therefore we would recommend using VSCode as whilst it is partially open source, If this is not an option, then we would recommend either using the [Docker image directly](#101-docker) as it comes bundled with RStudio which you can use to work on your lesson. +**Sneaky extra:** If you want to run RStudio Server from VSCode, in a terminal shell running in the VSCode devcontainer, type: + +```bash +~/start.sh +``` + +This will start the RStudio Server within the devcontainer, and you can then access RStudio by opening a web browser and going to `http://localhost:8787`. Fancy! + ::::::::::::::::::::::::::::: ::::::::::::::::::::: callout @@ -85,6 +151,7 @@ We will also be rolling these out into existing lessons across our official less ::::::::::::::::::::::::::::: + ## Docker {#101-docker} The documentation below for each operating system goes through how to manually install the Workbench dependencies, requirements, and packages. @@ -668,6 +735,17 @@ You will need to make sure your git session is connected to GitHub. To do so, you will need to use an SSH or HTTPS protocol. If you already know how to push and pull from GitHub using the command line, you do not need to worry about setting this up. +:::::::::::::::: callout + +### Docker/devcontainers and git + +If you already have your git installation configured outside the Docker/devcontainer environment, the various scripts and commands used in this documentation include mapping your local SSH (and GPG signing) configuration into the container. +This means your git commands should "just work" inside the container as they would outside. + +If you have any issues, please open an issue on the [workbench-docker](https://github.com/carpentries/workbench-docker/issues) GitHub repo. + +:::::::::::::::::::::::: + If you do not have this set up, you should [choose a protocol](https://docs.github.com/en/github/getting-started-with-github/about-remote-repositories) and then set them up according to the instructions from GitHub. It’s recommended to use the SSH protocol, unless you explicitly cannot, e.g. behind an institutional firewall or proxy. From 1550a595470884dccd85698cc2f581226387657e Mon Sep 17 00:00:00 2001 From: froggleston Date: Wed, 17 Sep 2025 12:05:11 +0000 Subject: [PATCH 07/18] tty config --- .devcontainer/devcontainer.json | 4 +++- config.yaml | 14 +------------- 2 files changed, 4 insertions(+), 14 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 234ea3b..30f2e3f 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -19,10 +19,12 @@ }, "postCreateCommand": { "pre_echo": "echo 'Installing lesson prerequisites - please wait...'", + "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" + "DISABLE_AUTH": "true", + "GPG_TTY": "/dev/pts/0" } } diff --git a/config.yaml b/config.yaml index 53e2e49..8eb38b9 100644 --- a/config.yaml +++ b/config.yaml @@ -38,18 +38,6 @@ 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 @@ -61,9 +49,9 @@ episodes: # Information for Learners learners: - setup.md -- faq.md - devcontainer.md - docker.md +- faq.md # Information for Instructors instructors: From e8d2e80fa3daa8e0b6701e58375ceeeea175db78 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:12:22 +0100 Subject: [PATCH 08/18] Update episodes/01-first-lesson.md Co-authored-by: Toby Hodges --- episodes/01-first-lesson.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/01-first-lesson.md b/episodes/01-first-lesson.md index 375759d..56c43b8 100644 --- a/episodes/01-first-lesson.md +++ b/episodes/01-first-lesson.md @@ -5,7 +5,7 @@ title: "Building Lessons" :::::::::::::::::::::::::::::::::::::: questions - How do we build lessons using a local Workbench installation? -- How do we huild lessons using the online GitHub architecture? +- How do we build lessons using the online GitHub architecture? :::::::::::::::::::::::::::::::::::::::::::::::: From 765eac68a026da88ad6a0a6efa1c2c1b564311be Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:12:34 +0100 Subject: [PATCH 09/18] Update learners/devcontainer.md Co-authored-by: Toby Hodges --- learners/devcontainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/devcontainer.md b/learners/devcontainer.md index efaa247..ac3ca23 100644 --- a/learners/devcontainer.md +++ b/learners/devcontainer.md @@ -2,7 +2,7 @@ title: 'Devcontainer Extras' --- -It's good practice to use separate environments when developing software. +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 long-winded to install. From 69db7e135cdc4675b2122a5170252162ca123920 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:12:44 +0100 Subject: [PATCH 10/18] Update learners/devcontainer.md Co-authored-by: Toby Hodges --- learners/devcontainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/devcontainer.md b/learners/devcontainer.md index ac3ca23..2d5d2dd 100644 --- a/learners/devcontainer.md +++ b/learners/devcontainer.md @@ -5,7 +5,7 @@ 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 long-winded to install. +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 From 926780006026eab44b141c9391e02152cf883119 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:13:02 +0100 Subject: [PATCH 11/18] Update learners/devcontainer.md Co-authored-by: Toby Hodges --- learners/devcontainer.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/learners/devcontainer.md b/learners/devcontainer.md index 2d5d2dd..00cd69c 100644 --- a/learners/devcontainer.md +++ b/learners/devcontainer.md @@ -26,10 +26,10 @@ The first thing to check is that a lesson supports devcontainers. Any lesson that has: -- A `.devcontainer` folder -- A `Dockerfile` and `devcontainer.json` inside that folder +- A `.devcontainer` folder in the root of its repository +- and a `Dockerfile` and `devcontainer.json` inside that folder -in the root of its repository can be run inside a devcontainer. +can be run inside a devcontainer. An example can be seen in [this repository](https://github.com/carpentries/workbench-docs/tree/main/.devcontainer). From db6ae2161e702fe799cc2c535bc4a8fd856c9572 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:13:21 +0100 Subject: [PATCH 12/18] Update learners/setup.md Co-authored-by: Toby Hodges --- learners/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index e7b5418..5c820a0 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -126,7 +126,7 @@ Getting devcontainers to work in other fully open source IDEs like `vscodium` an Therefore we would recommend using VSCode as whilst it is partially open source, it is a reliable and very well supported piece of software. -If this is not an option, then we would recommend either using the [Docker image directly](#101-docker) as it comes bundled with RStudio which you can use to work on your lesson. +If this is not an option, then we recommend using the [Docker image directly](#101-docker) as it comes bundled with RStudio which you can use to work on your lesson. **Sneaky extra:** If you want to run RStudio Server from VSCode, in a terminal shell running in the VSCode devcontainer, type: From 715f71a25fe684a036b6051e76dea0a390e10150 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:13:35 +0100 Subject: [PATCH 13/18] Update learners/setup.md Co-authored-by: Toby Hodges --- learners/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index 5c820a0..a28aead 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -189,7 +189,7 @@ curl -s https://raw.githubusercontent.com/carpentries/workbench-docker/main/scri curl -s https://raw.githubusercontent.com/carpentries/workbench-docker/main/scripts/run_workbench.sh | bash ``` -Or more longhand if you want to control various docker options: +Or with `docker run` directly, if you want to control various docker options: ```bash docker run --name carpentries-workbench \ From 8d35b8604433928bd1d05c9000849f99a64bb0c8 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:13:46 +0100 Subject: [PATCH 14/18] Update learners/setup.md Co-authored-by: Toby Hodges --- learners/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index a28aead..3cddda7 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -742,7 +742,7 @@ If you already know how to push and pull from GitHub using the command line, you If you already have your git installation configured outside the Docker/devcontainer environment, the various scripts and commands used in this documentation include mapping your local SSH (and GPG signing) configuration into the container. This means your git commands should "just work" inside the container as they would outside. -If you have any issues, please open an issue on the [workbench-docker](https://github.com/carpentries/workbench-docker/issues) GitHub repo. +If you have any issues, please open an issue on the [workbench-docker](https://github.com/carpentries/workbench-docker/issues) GitHub repo and/or ask for help on the `workbench` channel in [The Carpentries Slack workspace](https://carpentries.org/community/get-involved/). :::::::::::::::::::::::: From fc57ca31c159bfdcc7504eb4220c7be53c851a51 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:13:52 +0100 Subject: [PATCH 15/18] Update learners/faq.md Co-authored-by: Toby Hodges --- learners/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/faq.md b/learners/faq.md index 50b6d17..ab03ded 100644 --- a/learners/faq.md +++ b/learners/faq.md @@ -46,7 +46,7 @@ In this case, select "yes". 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 -- double-clicking on the RStudio icon in your application launcher +- or, double-clicking on the RStudio icon in your application launcher You do not have to open R separately to use RStudio. From 0d36a945fcf0b1a12d4027301c5a91b27e253208 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:15:15 +0100 Subject: [PATCH 16/18] Update learners/setup.md Co-authored-by: Toby Hodges --- learners/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index 3cddda7..96aa7f0 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -114,7 +114,7 @@ rstudio@55a86b63e4ab:~/lesson$ Here, you can perform any shell or R actions as you would usually for lesson development. -For more information and information, please check the full [devcontainer documentation](devcontainer.md). +For more information, please check the full [devcontainer documentation](devcontainer.md). ::::::::::::::::::::: callout From c53afa5871bbcccef9c0cfc71235b89073c80a1c Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:15:37 +0100 Subject: [PATCH 17/18] Update learners/devcontainer.md Co-authored-by: Toby Hodges --- learners/devcontainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learners/devcontainer.md b/learners/devcontainer.md index 00cd69c..bc049c9 100644 --- a/learners/devcontainer.md +++ b/learners/devcontainer.md @@ -73,7 +73,7 @@ Save the file, and rebuild the container by opening the command menu with F ### 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). +The full list of Docker images and their version _tags_ are [on Dockerhub](https://hub.docker.com/r/carpentries/workbench-docker/tags). ::::::::::::::::::::::::::::::: From 94b37044a649289f7f7d8715c0c3175d7691c595 Mon Sep 17 00:00:00 2001 From: Robert Davey Date: Mon, 29 Sep 2025 12:17:28 +0100 Subject: [PATCH 18/18] Apply suggestions from code review Co-authored-by: Toby Hodges --- learners/setup.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/learners/setup.md b/learners/setup.md index 96aa7f0..f317389 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -28,7 +28,7 @@ We provide four mechanisms to interact with the Workbench: - **Initial setup with docker is very straightfoward but can get complicated depending on your operating system!** - Manual local installation (local) - Installing all the requirements manually on your local operating system is a longer process, but can be useful if you want to learn how to get an environment set up and will teach you more about the Workbench framework. - - **If docker and devcontainers are not suitable for you, installing things manually is completely acceptable!** + - **If Docker and devcontainers are not suitable for you, installing things manually is a great option and still relatively quick to do!** - GitHub (online) - Moving your development completely online by using GitHub's Codespaces or Dev environment is an excellent choice if you have fast internet and are comfortable with this process. - **Be advised that this option may incur a cost depending on your GitHub account status!** @@ -39,7 +39,7 @@ We provide four mechanisms to interact with the Workbench: You can use the Workbench completely within devcontainers or Docker locally, or through GitHub using our templates. -However, we still would recommend working through the [local setup instructions](#101-manual) at least once as they will be useful for lesson development and debugging in future. +However, we still would recommend working through the [local setup instructions](#101-manual) at least once as they can save you a lot of time during lesson development and debugging in future. ::::::::::::::::::::::::::::: @@ -52,7 +52,8 @@ This can make it much quicker to get up and running with lesson development. To use devcontainers you need: - Docker: please read the [Docker installation instructions](#101-docker) to install Docker Desktop or the Docker Engine for your operating system. -- An IDE that supports devcontainers: We recommend [VSCode](https://code.visualstudio.com/) as it has the most complete and easy to set up devcontainer support. We acknowledge that VSCode is free but not completely open source. +- An IDE that supports devcontainers: We recommend [VSCode](https://code.visualstudio.com/) as it has the most complete and easy to set up devcontainer support. + We acknowledge that VSCode is free but not completely open source. Please note, if you are not comfortable with using Docker or the Workbench, we recommend going through the [manual installation](#101-manual) steps below. @@ -72,14 +73,14 @@ Open VSCode: NB: Note the space between `code` and `.`! -Once VSCode has opened the folder, after a short time, a popup should appear in the bottom right of the IDE saying `Folder contains a Devcontainer configuration file. Reopen folder to develop in a container`, with an option button to `Reopen in container`. +Once VSCode has opened the folder, after a short time, a pop-up should appear in the bottom right of the IDE saying `Folder contains a Devcontainer configuration file. Reopen folder to develop in a container`, with an option button to `Reopen in container`. Click this button and wait for VSCode to read the configuration file and setup the devcontainer environment. :::::::::::::::::::: callout ### Troubleshooting -If this popup does not appear, open the command menu in VSCode with the F1 function key. +If this pop-up does not appear, open the command menu in VSCode with the F1 function key. Your cursor will appear in the command menu bar at the top of the window, prefixed with a `>` symbol. Start typing `open folder` and select the `Dev Containers: Open Folder in Container...` option. @@ -87,7 +88,7 @@ Similarly if you have any issues with the container at any point, you can open t :::::::::::::::::::::::::::: -Various popups will appear in the bottom right, showing progress. +Various pop-ups will appear in the bottom right, showing progress. You can click on the `Show log` link in any of the popups that show it to see any logs of the setup process. The setup process can take a few minutes the first time you run it for a lesson. @@ -97,7 +98,7 @@ After the first time, it will be much quicker to start subsequent uses of the en ### Lessons with a lot of dependencies -For those RMarkdown lessons that require a large number of R packages, this first start of the devcontainer can take quite a long time. +For those R Markdown lessons that require a large number of R packages, this first start of the devcontainer can take quite a long time. :::::::::::::::::::::::::::: @@ -122,7 +123,7 @@ For more information, please check the full [devcontainer documentation](devcont Sadly the devcontainer specification is only fully supported in a small number of IDEs. VSCode is recommended in our lessons and it natively supports devcontainers. -Getting devcontainers to work in other fully open source IDEs like `vscodium` and `zed` are not as simple as to be easy for novices. +Getting devcontainers to work in other fully open source IDEs like `vscodium` and `zed` are not as simple. Therefore we would recommend using VSCode as whilst it is partially open source, it is a reliable and very well supported piece of software.