Chapter 1 Prerequisites and installing easy-opal
Part I builds the three-site federation from nothing. The five chapters mirror the five numbered folders in the repository, and each one shows the real commands and links the exact script that runs them. You can either run the scripts as-is, or follow along to understand what each does.
There are two roles in play, which may be the same computer:
- The server host runs the three simulated sites (Opal + Rock + PostgreSQL). Steps 1–4 happen here and need Docker and Python.
- The DataSHIELD client is the R session that connects to the sites and runs the analysis (step 5 and all of Part II). It needs R.
1.1 What you need
| Tool | Minimum version | Used for |
|---|---|---|
| Python | 3.11 | Installing and running the easy-opal CLI (step 1). |
| Docker | Engine ≥ 20.10 with Compose v2 (docker compose) |
Running the Opal, Rock, MongoDB and PostgreSQL containers (steps 2–4). The daemon must be running. |
| R | 4.1 (ideally 4.4.x, to match the Rock server’s R) | The DataSHIELD client packages (step 5 / Part II). |
The dsOMOP Rock image is published for
linux/amd64. It runs natively on Linux/amd64 hosts and emulated on Apple Silicon (slower, but it works).
1.2 Installing easy-opal (step 1)
We deploy and manage the Opal + Rock sites with
easy-opal, a CLI that wraps
Docker Compose. It is an ordinary PyPI package, so installing it is a single
pip command:
Version.
easy-opalis actively developed, so we deliberately do not pin a version. As of June 2026 the current release is 2.1.0 — that or newer is fine.
That puts an easy-opal command on your PATH. Confirm it works — easy-opal doctor checks that Docker is reachable and correctly configured:
If your system Python is externally managed (PEP 668) and a bare
pip installis refused, install it in isolation instead — both still puteasy-opalon yourPATH:
With easy-opal on your PATH, the next chapter stands up the three sites.