Skip to main content
Get started

Installing the tools

A known development environment makes the rest of the tutorial easier to follow and debug. We'll install Git, GitHub CLI, Docker, Sprocket, Visual Studio Code, and the Sprocket extension. After installing each tool, you'll run a check that proves it is ready.

Use the platform tabs to choose macOS, Linux, or Windows. The site remembers your choice for other platform-specific examples.

Identify your system

Installers often provide different files for different operating systems and processor architectures. Check yours now so you can choose the correct download later.

First, open a terminal. A terminal is an application where you run text commands:

  1. Press ⌘ + Space to open Spotlight.
  2. Type Terminal.
  3. Press Return.

The terminal shows a prompt where you can type. For each command block in this tutorial, type or paste the command after the prompt, then press Enter. Wait for the command to finish before running the next one.

Lines that start with # are comments, so they do not execute any code in the terminal. In this tutorial, a comment either explains a command or shows what its output should look like. It does no harm if you type or paste comments into the terminal.

Now run the commands for your platform:

bash
uname -s
# Darwin
uname -m
# arm64 or x86_64

Architecture names commonly appear as arm64 or aarch64 for ARM and x86_64 or AMD64 for Intel or AMD processors. You will use this architecture to select the correct downloads for the tools below. A download built for another architecture may not run on your computer, so keep both your operating system and architecture handy.

Install Git and GitHub CLI

Git records changes to the pipeline, while GitHub CLI connects that local history to GitHub. We'll explain branches, commits, checkpoints, and pull requests in the Git crash course. For now, we're only installing and setting up the tools.

Follow the official Git installation and GitHub CLI installation instructions for your operating system. On Windows, install Git for Windows with Git Bash. Git Bash also provides the Bash executable used by WDL command sections.

Once done, check that both commands are available:

bash
git --version
# git version 2...
gh --version
# gh version 2...

While we're here, Git records a name and email associated with each change you make to source code. Configure the values you want this course to use:

bash
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
# No output is expected.

Connect GitHub CLI to your account. Choose GitHub.com, HTTPS, and browser authentication when prompted unless your organization requires another method:

bash
gh auth login
# ? What account do you want to log into? GitHub.com
# ? What is your preferred protocol for Git operations? HTTPS
# ? How would you like to authenticate GitHub CLI? Login with a web browser
# ... Follow the remaining instructions to complete authentication.

gh auth status
# github.com
# ✓ Logged in to github.com account YOUR-USERNAME (...)

This section is complete when Git reports a version and GitHub CLI reports an authenticated account.

Install Docker

Containers package tools with the system libraries they need, helping the same work run consistently on your computer, in the cloud, and on HPC. Docker builds and runs those containers. We'll explain them in more detail and build one in Containers. For now, we'll just install and configure the tools needed to work with containers.

Choose your platform:

Install Docker Desktop for Mac.

Docker Desktop has licensing conditions for some larger organizations. Check the current terms before using it for institutional work.

Installing the Docker command is only part of the setup. The command sends work to Docker Engine, a background service that builds and runs containers. Start Docker Desktop on macOS or Windows, or start Docker Engine on Linux, and wait until it is ready. Then check both the command and the running service:

bash
docker version
# Client: Docker Engine ...
# Server: Docker Engine ...
docker run --rm hello-world
# Hello from Docker!

docker version must report both a client and a server. If it reports only a client, the Docker service is not running or your account cannot reach it. The hello-world container must finish successfully. Once both checks pass, leave Docker running while you work through the tutorial. Later sections will use it to build and run containers.

Install Sprocket

Sprocket is a complete and modern development suite for WDL written in Rust. It helps you write, check, format, document, and run WDL. We'll use it throughout this tutorial.

This course requires Sprocket 0.30.1 or later. Choose whether you want Homebrew to manage updates or whether you want to install the latest binary yourself:

Choose an installation approach:

Use Homebrew if you want to keep Sprocket updated to the latest release. If Homebrew is not installed, follow the instructions at brew.sh. Then run:

bash
brew install sprocket
# ==> Installing sprocket
# ...

To update Sprocket later, run brew update && brew upgrade sprocket.

Check the installation:

bash
sprocket --version
# sprocket 0.30.1 ... or later

The command should identify Sprocket 0.30.1 or later. If it reports an older version, update Sprocket or install the latest Sprocket release.

Install Visual Studio Code and the extension

Visual Studio Code is the text editor we'll use to write WDL. The Sprocket extension connects the editor to Sprocket, which analyzes your WDL while you type. It adds syntax highlighting, formatting, snippets, and live error and lint messages directly beside the code they describe.

This immediate feedback helps you learn the language and fix problems while the relevant code is still in front of you. It also catches many mistakes before you send a workflow to a cloud or HPC system, where discovering the same mistake can take longer and consume compute resources.

Install Visual Studio Code and make its code command available in the terminal:

  1. Follow the official Visual Studio Code setup for macOS.
  2. Open Visual Studio Code.
  3. Press ⌘ + Shift + P to open the Command Palette.
  4. Type shell command.
  5. Select Shell Command: Install 'code' command in PATH.
  6. Close the terminal and open it again so it can find the new command.

Check that the terminal can start Visual Studio Code:

bash
code --version
# 1...
# ...

Install the Sprocket extension from the terminal:

bash
code --install-extension stjude-rust-labs.sprocket-vscode
# Installing extensions...
# Extension 'stjude-rust-labs.sprocket-vscode' was successfully installed.

Now use the terminal and Visual Studio Code to create a temporary WDL file:

  1. Return to the terminal and run:
bash
code environment-check.wdl
# Visual Studio Code opens a new, empty file named environment-check.wdl.
  1. Paste this WDL into the empty editor:
wdl
version 1.3

workflow environment_check {}

This is a complete, valid WDL file, so the editor should not report any errors after you save it.

  1. Select File > Save. The .wdl filename tells VS Code and the Sprocket extension which language the file contains.
  2. Open the Problems panel. The official Visual Studio Code errors and warnings guide shows what the panel looks like and how VS Code marks problems in a file:

Select View > Problems, or press ⌘ + Shift + M.

With the valid spelling, the Problems panel should be empty. Change workflow to workflo and save the file again. The panel should list a syntax error with its message, filename, and location, while the editor marks the affected line. Select the problem to jump to that line. Restore the valid spelling, save the file, and confirm that the problem disappears from both places. You can then delete the temporary file.

Seeing the error and then clearing it proves that the editor, extension, language server, and WDL file association work together.

Download the course repository

The code for this tutorial lives in the openwdl/production-guide-tutorial repository. We'll use GitHub CLI to copy, or in Git parlance, clone, that repository to your computer:

bash
gh repo clone openwdl/production-guide-tutorial
# Cloning into 'production-guide-tutorial'...
# ...
cd production-guide-tutorial

The course repository has a branch for the start of each section. A branch is a named line of changes to the source code. It lets many people work on the same project at once without mixing unfinished changes. In this course, each starting branch contains everything completed before that section.

Each section has a chapter/NN-topic branch containing its starting point. We will use one of these branches to begin the hands-on course. Later sections will create their own local branches from the corresponding branch on origin, the OpenWDL repository. You will commit your work locally rather than push routine coursework to your fork.

Since we're about to start section three, [Git crash course], we'll go ahead and switch to that branch to make the files in your local copy match the section's starting point:

bash
git fetch origin
# No output is expected.
git switch chapter/03-git-crash-course
# Switched to branch 'chapter/03-git-crash-course'
# Your branch is up to date with 'origin/chapter/03-git-crash-course'.
git status --short
# No output is expected.

The first time you switch to a chapter branch, Git may instead say that it created a new local branch that tracks the branch on origin. origin is Git's name for the GitHub repository you cloned. Both messages mean you are on the correct starting branch.

You should see a project directory with source code, tests, examples, documentation, and configuration appropriate for this point in the course. The exact files may change as the course evolves. The important checks are that Git names the expected branch and git status --short prints nothing, which means you have a clean starting copy.

The Git crash course will use a fork to teach GitHub collaboration. After that exercise, each section will start from its own branch on origin and keep your work on your computer unless the lesson specifically requires a GitHub service.

Confirm that you are ready

Run this final checklist before continuing:

bash
git --version
gh auth status
docker version
sprocket --version
# Visual Studio Code reports WDL diagnostics

If a check fails, fix that tool before continuing. The next section gives you the Git skills you'll use to track the project safely. Continue to Git crash course.