2  Manual Setup

2.1 Summary

This documentation covers the “manual” install of Workbench packages and dependencies. For those interested in using Docker to manage their Workbench environments, please see the docker documentation.

2.2 Software Requirements

Development of Workbench components requires the same toolchain for working on lessons:

  • R
  • pandoc
  • Git

It is recommended to have the latest versions of R and pandoc available. You need at least git 2.28 for security purposes.

R version
---
R version 4.5.2 (2025-10-31) -- "[Not] Part in a Rumble"
Copyright (C) 2025 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under the terms of the
GNU General Public License versions 2 or 3.
For more information about these matters see
https://www.gnu.org/licenses/.

pandoc version
---
pandoc 3.1.11
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/runner/.local/share/pandoc
Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

git version
---
git version 2.53.0

2.3 R Packages

Once you have these installed, make sure to install ALL of the dependencies for the Workbench:

install.packages(c("sandpaper", "pegboard", "varnish", "tinkr"),
  dependencies = TRUE,
  repos = c(getOption("repos"), "https://carpentries.r-universe.dev"))
TipWorking on Linux?

If you are on Linux, you will run into a couple of fun aspects that you may already be familiar with, especially if you have ever tried to install bioinformatics software:

  1. having to also install some extra C libraries (which are akin to R packages, but for C), such as the xslt library.
  2. having to build all packages from source

You can find detailed instructions in The Sandpaper Setup Guide, but the relevant commands are below.

System Dependencies

We support Debian and Debian-based distributions (Ubuntu, Mint, etc). Use The Carpentries R-Universe API to get all of the system dependencies. To do this via CURL:

curl https://carpentries.r-universe.dev/stats/sysdeps 2> /dev/null | jq -r '.headers[0] | select(. != null)'

This list can be sent to apt-get install to install everything:

sudo apt-get install -y \
  $(curl https://carpentries.r-universe.dev/stats/sysdeps 2> /dev/null | jq -r '.headers[0] | select(. != null)') 2> /dev/null \
  || echo "Not on Ubuntu"

Binary Packages

To get binary packages for your system, you need to do two things:

  1. set your HTTPUserAgent header to state your R version and platform
  2. add the packagemanager CRAN-like repository to R’s options:

Here’s a script that you can copy and paste into ~/.Rprofile which will be run every time you start R

local({
  # Set the default HTTP user agent to get pre-built binary packages
  RV <- getRversion()
  OS <- paste(RV, R.version["platform"], R.version["arch"], R.version["os"])
  codename <- sub("Codename.\t", "", system2("lsb_release", "-c", stdout = TRUE))
  options(HTTPUserAgent = sprintf("R/%s R (%s)", RV, OS))

  # register the repositories for The Carpentries and CRAN
  options(repos = c(
    carpentries = "https://carpentries.r-universe.dev/",
    CRAN = paste0("https://packagemanager.posit.co/all/__linux__/", codename, "/latest")
  ))
})

When you have this set up, you can then install the Workbench packages:

# Install The Workbench and dependencies
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"), dep = TRUE)

The {sandpaper} package comes with the {usethis} package embedded (though this may change in the future).

If you wish to develop features for the Workbench, you will need the {devtools} package. It is also recommend that you install the {pandoc} package for managing pandoc versions (NOTE: this requires you to have a personal access token set up).

install.packages("devtools")
install.packages("pandoc")

Once you have devtools, be sure to run devtools::dev_sitrep() and usethis::git_sitrep() to make sure you have the tools to build The Workbench:

devtools::dev_sitrep()
#> ── R ───────────────────────────────────────────────────────────────────────────
#> • version: 4.3.0
#> • path: '/usr/lib/R/'
#> ── devtools ────────────────────────────────────────────────────────────────────
#> • version: 2.4.5
#> ── dev package ─────────────────────────────────────────────────────────────────
#> • package: <unset>
#> • path: <unset>
#> ✔ All checks passed

usethis::git_sitrep()
#> Git config (global)
#> • Name: 'Zhian N. Kamvar'
#> • Email: 'zkamvar@gmail.com'
#> • Global (user-level) gitignore file: <unset>
#> • Vaccinated: FALSE
#> ℹ See `?git_vaccinate` to learn more
#> ℹ Defaulting to 'https' Git protocol
#> • Default Git protocol: 'https'
#> • Default initial branch name: 'main'
#> GitHub
#> • Default GitHub host: 'https://github.com'
#> • Personal access token for 'https://github.com': '<discovered>'
#> • GitHub user: 'zkamvar'
#> • Token scopes: 'gist, repo, user, workflow'
#> • Email(s): 'zkamvar@gmail.com (primary)', ...
#> Git repo for current project
#> ℹ No active usethis project

Created on 2023-05-30 with reprex v2.0.2