Skip to content

Installing Docker

Jump to bottom
David Anderson edited this page Jun 14, 2025 · 15 revisions

Docker is a system that makes it easy for BOINC projects to run applications on Windows, Mac and Linux computers. It's like VirtualBox but is more efficient and easier to use.

In the future, many BOINC projects will use Docker to package their apps. To run these apps, you'll need to have Docker installed on computers running BOINC.

Eventually we hope to include Docker in the BOINC installer. For now, you need to install it yourself. It's easy, and we strongly encourage you to do it.

Docker itself is a commercial product. Podman is a free open-source drop-in replacement for Docker. We use Podman because it's free and easier to install. But if you already have Docker installed, BOINC will detect and use it.

Windows

Note: Docker and VirtualBox are incompatible on Windows. If you're using VirtualBox for something other than BOINC, do not install Docker.

On Windows, Docker needs something called Windows Subsystem for Linux (WSL). Windows 11 has WSL already enabled. On Windows 10 you first need to enable WSL:

  • click in the Windows search bar (lower left corner)
  • click 'Control Panel'
  • click 'Programs and Features'
  • click 'Turn Windows features on or off'
  • check the box for 'Windows Subsystem for Linux'
  • click OK
  • Restart the computer

Install the latest version of WSL: https://github.com/microsoft/WSL/releases/download/2.4.13/wsl.2.4.13.0.x64.msi

BOINC provides a WSL 'image' that contains Podman. Download it from https://github.com/BOINC/boinc-buda-runner-wsl and open it.

Open a terminal window (type 'cmd' in the Windows search box). In this window, type

wsl -d boinc-buda-runner

Run the BOINC client. You should see something like

3/25/2025 3:15:16 PM |  | Usable WSL distros:
3/25/2025 3:15:16 PM |  | -   boinc-buda-runner (WSL 2) (default)
3/25/2025 3:15:16 PM |  | -      OS: Alpine Linux (Alpine Linux v3.21)
3/25/2025 3:15:16 PM |  | -      Docker version 5.3.2 (podman)

Linux

If you're running Linux in a virtual machine (e.g. a cloud node) Docker/Podman won't work. (We're working on a solution for this problem.)

To install Podman on Debian/Ubuntu:

sudo apt install podman
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 boinc

On Red Hat:

sudo yum install podman
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 boinc

IMPORTANT:

If BOINC is not installed from the official package listed here, you should give permission to run podman to the user that is actually running BOINC client:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 PUT_USERNAME_HERE

This section will be updated to cover any corner cases. In case of any issues found, feel free to create bug report.

Mac

To install Podman, go to https://github.com/containers/podman/releases. Scroll down until you see a version that says 'Latest' (not 'Pre-release'). Click on Assets.

For Apple Silicon Macs, download podman-installer-macos-arm64.pkg

For Intel Macs, download podman-installer-macos-amd64.pkg

Double-click on the file, and step through the installation. At the end it will tell you to run

podman machine init
podman machine start

You can do this (in a terminal window) if you want, but you don't have to; the BOINC client will do it when it starts up.

Home

Clone this wiki locally