diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index c4dc426..cfc4f08 100644 --- a/.devcontainer/devcontainer.json +++ b/.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 diff --git a/config.yaml b/config.yaml index 23f2938..8eb38b9 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 @@ -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: diff --git a/episodes/01-first-lesson.md b/episodes/01-first-lesson.md new file mode 100644 index 0000000..56c43b8 --- /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 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 diff --git a/learners/devcontainer.md b/learners/devcontainer.md new file mode 100644 index 0000000..bc049c9 --- /dev/null +++ b/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 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. + +::::::::::::::::::::::: 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. 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/faq.md b/learners/faq.md index 8c94b90..ab03ded 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 +- 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). diff --git a/learners/setup.md b/learners/setup.md index 8507619..f317389 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,205 @@ 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. + - 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. + - **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 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!** + +::::::::::::::::::::: 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 can save you a lot of time during 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, 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/) 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. + +### 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 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 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. + +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 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. +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 R Markdown 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, please check the full [devcontainer documentation](devcontainer.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. + +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 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: + +```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 + +### 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) + +### 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 +# 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 with `docker run` directly, if you want to control various docker options: + +```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 [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. + +## 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 +232,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: @@ -52,31 +246,11 @@ 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. 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 @@ -355,7 +529,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 . @@ -435,7 +609,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: @@ -443,7 +617,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: @@ -473,7 +647,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: @@ -507,10 +681,10 @@ 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: +## 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: ```r rmarkdown::pandoc_version() @@ -562,6 +736,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 and/or ask for help on the `workbench` channel in [The Carpentries Slack workspace](https://carpentries.org/community/get-involved/). + +:::::::::::::::::::::::: + 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. @@ -591,6 +776,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.