Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify Docker installation #1038

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Clarify Docker installation #1038

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 43 additions & 18 deletions docs/install-docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,60 @@

## Why Docker?

Docker allows you to run identical software on all platforms.
Docker allows you to run identical software on all platforms.
It creates "containers" that are guaranteed to be identical on any system that can run Docker.

OpenSAFELY uses Docker to run your code in a reproducible, safe manner.
OpenSAFELY uses Docker to run your code in a reproducible, safe manner.
This is most helpful for checking that you will be able to successfully run your code on the OpenSAFELY server on real data.
If you only run your code locally using your own installation of R, say, then you won't know if the version of R (and the packages) installed on the server will run your code without errors or unexpected behaviours.
See the [Testing Your Code section](actions-pipelines.md) for more details on how to test your code in practice.

Unfortunately, Docker is happiest on Linux; on Windows and Mac OSX, installation can be a chore.
Unfortunately, Docker is happiest on Linux; on Windows and Mac OSX, installation can be a chore.
These notes should help.

## Installation

Windows and Macs have different installation processes.
Regardless of machine, you will have to install Docker and make an account on the [Docker Website](https://docs.docker.com/).

There are two flavours you can install, *Desktop* and *Toolbox*.
Docker Desktop is preferred over Docker Toolbox.
Windows and Macs have different installation processes.
Regardless of machine, you will have to install Docker Desktop and make an account on the [Docker Website](https://docs.docker.com/).

### Windows

Docker Desktop in Windows offers native support via Hyper-V containers, and so is preferred.
Follow the instructions from the Docker website.
Windows 10 or later is required.
It is best to install using the default settings.

To install Docker Desktop on Windows 10 64-bit Pro, Enterprise, or Education build 15063 or later (i.e., most university or institution managed machines), [follow these installation instructions](https://docs.docker.com/docker-for-windows/install/).
To install Docker Desktop on Windows Home [follow these installation instructions](https://docs.docker.com/docker-for-windows/install-windows-home/).
!!! note
We previously recommended Docker Desktop with the Hyper-V backend.

Windows users who log into an Active Directory domain (i.e., a network login) may find they lack permissions to start Docker correctly.
If so, [follow these instructions](https://github.com/docker/for-win/issues/785#issuecomment-344805180).
It is best to install using the default settings.
Docker Desktop's recommended configuration is now the WSL2 backend.
We have not thoroughly tested OpenSAFELY with WSL2,
but there is no reason why WSL2 should be incompatible with OpenSAFELY's tooling.

You may be asked to enable the Hyper-V and Containers features, which you should do.
You can do this by [following these instructions](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v).
You only need to choose either Hyper-V or WSL2.
It is fine to continue to use the Hyper-V backend.
Comment on lines +26 to +34
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a reader, this makes me nervous. The Docker people say "WSL2". The OpenSAFELY people say "WSL2, but we haven't tested it, and Hyper-V is fine".

Could we (as OpenSAFELY people) commit to WSL2, and keep a very close eye out for issues?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we (as OpenSAFELY people) commit to WSL2, and keep a very close eye out for issues?

This is probably the right thing to do seeing as that's where Docker looks to be headed.

I'd be happier if a friendly Windows user could test WSL2 so that we know it does work. (I don't expect that it won't. But confirmation would be great ✔️)

I don't have a native Windows install to test with, unfortunately.


#### Enabling Hyper-V

!!! warning
Hyper-V is only available for the Pro, Enterprise and Education editions of Windows.
If you have a Windows Home edition,
then Hyper-V is not available and you must use WSL2 instead.

If using Hyper-V, you may be asked to enable the Hyper-V and Containers features, which you should do.
You can do this by [following these instructions](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v).
At least one user has had the box ticked on the screen but had to untick and tick again to get this to enable correctly (Detailed in [this issue](https://github.com/ebmdatalab/custom-docker/issues/4)).

#### Enabling WSL

See [Microsoft's instructions](https://learn.microsoft.com/en-us/windows/wsl/install).

#### Enabling permissions for Active Directory logins

Windows users who log into an Active Directory domain (i.e., a network login) may find they lack permissions to start Docker correctly.
If so, [follow these instructions](https://github.com/docker/for-win/issues/785#issuecomment-344805180).

#### Running Docker

Starting Docker can take a while — up to 5 minutes.
While it's doing so, an animation runs in the notification area:

Expand All @@ -54,9 +74,9 @@ When logged in as a network user, there have been permission problems that have

Finally, note that when authentication changes (e.g., different logins), you sometimes have to reauthorise Docker's "Shared Drives" (click system tray Docker icon; select "Settings"; select "Shared drives"; click "Reset credentials"; retick the drive to share; click "Apply").

### Macs
### Mac

Follow the instructions from the Docker website.
Follow the [Mac installation instructions](https://docs.docker.com/desktop/install/mac-install/) from the Docker website.
You may have to restart your computer during installation.

Once you have Docker installed, you will need to log in.
Expand All @@ -66,6 +86,11 @@ This can be accessed via the Applications Folder and once you have logged in, yo

Once this is running, you should be able to use Docker.

### Linux

You can either install Docker with [Docker Desktop](https://docs.docker.com/desktop/install/linux-install/),
or via the server [Docker Engine](https://docs.docker.com/engine/install/).

## Gotchas

- The first time you use Docker or use a new Docker template, please be aware that it takes a long time to make the build.
Expand Down