Run locally in an isolated environment (Docker)

This option lets you run a RECAP template on your own machine using a self-contained environment that includes all required tools, without installing them permanently on your system.

Compared to GitHub Codespaces, this option requires a one-time local setup.
Compared to running directly on your machine, it avoids installing and maintaining a large software stack.

For most medium and large projects, this provides a good balance between reproducibility and local control.

When this option is a good fit

Choose this option if:

  • you want strong reproducibility without relying on the cloud,
  • you prefer not to install many tools directly on your system,
  • you are working on a medium or large project,
  • you want an experience close to Codespaces, but running locally.

How it works

The template is opened inside an isolated local environment that contains:

  • the statistical language used by the project,
  • document generation tools,
  • and all other required dependencies.

You work and access the project files as usual, while execution happens inside this isolated environment.

Getting set up

You need Docker Desktop installed and running on your machine.
This is a one-time setup.

🎥 Prefer watching instead of reading?
Short walkthrough of these steps below (no audio).

  1. Go to https://www.docker.com/ and download Docker Desktop. Choose:
    • Apple Silicon if your Mac is from 2020 or later (M1, M2, M3)
    • Intel Chip if your Mac is older
  2. Install Docker Desktop
  3. Open Docker Desktop for the first time.
    • If Docker offers a setup choice, select the recommended configuration. You may be asked to confirm permissions (for example, using your Mac password or Touch ID).
    • You can skip prompts about creating a Docker Hub account. You do not need a Docker Hub account to use RECAP templates.
  4. Wait until Docker Desktop indicates that Docker is running.

🎥 Prefer watching instead of reading?
Short walkthrough of these steps below (no audio).

  1. Open Windows Terminal
  2. Run: wsl --install
  3. Restart your computer when prompted
  4. Open the Microsoft Store
  5. Install Docker Desktop
  6. Open Docker Desktop and wait until it reports that it is running

Installing Docker may take a few minutes and may require restarting your computer.

If this setup feels cumbersome, consider using GitHub Codespaces, which provides the same environment with no local installation.

Open the project in Visual Studio Code

RECAP documents and supports this option using Visual Studio Code.
Other editors may work, but are not covered here.

🎥 Prefer watching instead of reading?
Short walkthrough of these steps below (no audio).

  1. Install Visual Studio Code if you haven’t already.

  2. Make sure Docker Desktop is running.

  3. Install the Dev Containers extension from the VS Code Marketplace.

  4. On the template’s GitHub repository page, choose how you want to get the project files:

    • I don’t want to use Git
      Click Code → Local → Download ZIP, extract the archive on your computer, then open the extracted folder in Visual Studio Code.

    • I want to use Git

      1. Click the “Use this template” button on the repository page.
        This creates a new repository under your GitHub account, based on the RECAP template.
        You can choose a name for your project and decide whether it should be public or private.

      2. Open the new repository in Visual Studio Code.
        You can do this by cloning the repository directly from VS Code.

        (Cloning a repository using VS Code is covered in How to get started with Git.)

  5. Open the Command Palette in Visual Studio Code
    (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), then run:

    Dev Containers: Reopen in Container

    This operation may take a few minutes the first time.

Visual Studio Code will build the environment and reopen the project inside the isolated container.

Once this is done, you can run the analysis and build outputs as described in the template’s instructions.

Frequently asked questions

How do I go back to my container later?

To return to your Dev Container, open up Visual Studio Code and select File > Open recent. Your project’s name should appear, followed by the mention [Dev Container].

Things are broken - How do I start over?

You can delete your existing container and create a new one with Visual Studio Code at any time. Open Docker Desktop. Select your container and delete it. This will reset the environment to its original state, while preserving your files.

This site uses Just the Docs, a documentation theme for Jekyll.