Introduction and Overview
Before using the build environment, the host system must be able to run Docker containers and provide a writable project directory. This chapter explains the host-side requirements and the platform-specific limits that matter before any RISC OS tools are installed.
The environment supports Linux, macOS, Windows, and WSL2 at the container level, but the wrapper installation and shell workflow are more capable on Linux, macOS, and WSL2 than on native Windows command shells.
Important: the build-environment container images in this repository are built for linux/amd64. On ARM-based host systems, including Apple silicon Macs and ARM Windows devices, the environment therefore runs through emulation unless the host is already amd64-compatible. That is normally functional, but it may be noticeably slower than running on an amd64 system directly.
Technical Details
Required host capabilities
Every supported host must provide the following before the build environment can be used productively:
- Docker Engine or Docker Desktop installed and working for the current user;
- a terminal or shell in which Docker commands can be run successfully;
- a writable host directory that will be shared into the container as the source tree;
- network access if images need to be downloaded or remote build services used.
Linux
Linux provides the most direct wrapper-based workflow. Once Docker is working, the build environment can install its host wrapper commands into a directory on the user's PATH. Those wrappers then start the container on demand.
For Linux hosts, start with the official Docker Engine installation guide: Install Docker Engine. That guide branches to the supported distributions such as Ubuntu, Debian, Fedora, and RHEL. Docker's Linux documentation also notes that Ubuntu derivatives should normally follow the Ubuntu instructions that correspond to their base release.
Docker Desktop for Linux is also available, but the build environment only requires a working Docker daemon and CLI. After installation, verify that a simple docker run command succeeds before attempting to install the RISC OS wrappers.
The Ubuntu, Debian, Fedora, and RHEL command sequences below are transcribed directly from Docker's own installation guide as of June 2026. Docker maintains and updates that guide independently of this manual, so treat the commands here as a convenience snapshot rather than the canonical source: if a command fails or looks out of date, check the linked guide above for the current sequence before troubleshooting further.
Ubuntu quick installation
For Ubuntu, Docker's recommended path is to install Docker Engine from the official apt repository. The current Docker documentation gives this command sequence:
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
Debian quick installation
For Debian, Docker recommends the same apt-repository pattern with the Debian repository and codename:
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc podman-docker containerd runc | cut -f1)
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
Docker's Debian documentation notes that on Debian testing or derivative distributions such as Kali, the codename may need to be replaced manually with the matching Debian release codename.
Fedora quick installation
For Fedora, Docker's current recommendation is to use the rpm repository:
sudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-selinux docker-engine-selinux docker-engine
sudo dnf config-manager addrepo --from-repofile https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run hello-world
If the Docker service fails to start and the journal reports that it cannot find iptables, Docker's Fedora guide says to point the system at iptables-nft and restart Docker:
sudo alternatives --set iptables /usr/bin/iptables-nft
sudo systemctl restart docker
RHEL quick installation
For RHEL, Docker's current repository-based installation sequence is:
sudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine podman runc
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run hello-world
Common Linux post-installation
On Linux, Docker's post-installation guide recommends adding the user to the docker group if Docker should be usable without sudo. This grants root-level privileges, so it should be used deliberately.
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker run hello-world
On distributions where the docker group is created automatically during installation, the groupadd step is not required. Docker's post-installation guidance also says to log out and log back in so that group membership is re-evaluated; in virtual machines, a full restart may be required instead.
macOS
On macOS, Docker Desktop is the normal route. Use the official guidance:
Docker provides separate downloads for Apple silicon and Intel Macs. The current and two previous major macOS releases are supported, and Docker states that at least 4 GB of RAM is required. Docker also recommends Rosetta 2 for the best experience on Apple silicon because some optional Darwin/AMD64 command-line tools still depend on it.
The permission guide explains that Docker Desktop commonly requests privileged access during installation for tasks such as installing symlinks in /usr/local/bin and binding privileged ports. If a machine has stricter security requirements, the advanced settings can be used to reduce the need for privileged access by adjusting the CLI location, socket location, and privileged port mapping behaviour.
Quick installation from the Finder
Docker's standard macOS path is:
- Download the correct installer for Apple silicon or Intel Mac hardware.
- Open Docker.dmg.
- Drag Docker into the Applications folder.
- Start /Applications/Docker.app.
- Accept the Docker Desktop terms.
- Choose the recommended settings unless there is a reason to use the advanced settings.
Quick installation from the command line
Docker's macOS installer also supports a direct command-line installation once Docker.dmg has been downloaded:
sudo hdiutil attach Docker.dmg
sudo /Volumes/Docker/Docker.app/Contents/MacOS/install
sudo hdiutil detach /Volumes/Docker
The documentation notes that this may take several minutes because macOS performs security checks when the application is first used.
Quick post-install checks
After installation, start Docker Desktop and then verify that the Docker CLI works in a terminal:
docker version
docker run --rm hello-world
If the user chose the per-user CLI location $HOME/.docker/bin rather than /usr/local/bin, Docker's permission guide says that this directory must be added to the shell PATH manually.
On Apple silicon Macs, install Rosetta 2 as well if it is not already available:
softwareupdate --install-rosetta
Windows and WSL2
Windows users can run the environment through Docker Desktop, but there is an important limitation: the local wrapper installation workflow is not supported for native Windows shells. The practical recommendation is to use WSL2 and install the wrappers there, or run the environment directly with docker run commands.
The command help explicitly notes that local wrapper installation is not currently supported on Windows. In practice this means that Windows users should treat the container shell as the main interface unless they are working through WSL2.
For Windows hosts, use the official Docker Desktop installation and permission guides:
Docker documents both per-user and all-users installation modes. Per-user installation is recommended by Docker and uses the WSL 2 backend only. All-users installation can use WSL 2 or Hyper-V, but requires elevation at install time. Docker's documented requirements for the WSL 2 backend include WSL version 2.1.5 or later, supported 64-bit Windows 10 or Windows 11 editions, enabled hardware virtualisation, and 8 GB of RAM.
The Windows permission guide explains that after installation Docker Desktop can usually be run without administrator privileges. However, if higher-privilege features are required, additional users may need to be added manually to the docker-users group.
Quick interactive installation
Docker's standard Windows path is:
- Download Docker Desktop Installer.exe.
- Run the installer.
- Choose per-user installation for the common WSL 2 workflow, or all-users if Hyper-V or Windows containers are required.
- When prompted, keep the WSL 2 backend selected unless a specific Hyper-V workflow is required.
- Finish the installer and then start Docker Desktop.
Quick command-line installation
Docker's Windows installer can also be driven directly from the command line. The current documentation gives these commands:
"Docker Desktop Installer.exe" install --user
Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--user'
Those are the per-user forms. For an all-users installation, Docker documents:
"Docker Desktop Installer.exe" install
Start-Process 'Docker Desktop Installer.exe' -Wait install
If using all-users installation and the administrator account differs from the developer account, Docker also documents adding that user to the docker-users group:
net localgroup docker-users <user> /add
Quick post-install checks
After Docker Desktop starts, verify that it is working:
docker version
docker run --rm hello-world
WSL2 as the preferred Windows workflow
For this build environment, WSL2 is the recommended Windows workflow. Install Docker Desktop on Windows first, ensure the WSL 2 backend is enabled, and then run the RISC OS wrapper installation and shell workflow from inside a Linux distribution under WSL2 rather than from a native Windows command prompt.
This approach aligns best with the wrapper scripts, path handling, and shell examples used throughout the rest of this manual.
Quick WSL2 setup
Docker's Windows documentation says to verify the installed WSL version and, if necessary, install or update WSL before relying on the WSL 2 backend:
wsl --version
wsl --install
wsl --update
These commands should be run from an elevated PowerShell or Windows Command Prompt when WSL still needs to be installed or updated.
Quick WSL2 workflow for this environment
Once Docker Desktop is running with the WSL 2 backend:
- Open the Linux distribution under WSL2.
- Verify that docker version works inside WSL.
- Install the RISC OS build-environment wrappers from inside WSL rather than from native Windows shells.
A minimal first check from the Windows side is:
wsl
docker version
What to verify before proceeding
Before continuing to the installation chapter, verify the following on the host:
- Docker starts without administrative repair work.
- The current user can pull or run a container.
- A terminal session is available for normal command-line use.
- A writable project directory exists, preferably inside a Git repository.
The quickest generic check before any wrapper installation is:
docker run --rm hello-world
Related constraints
If the goal is to use optional runtime graphics support, later chapters will also discuss VNC access and Pyromaniac availability, but these are not required for ordinary cross-compilation. Continue with Installation once the host prerequisites are in place.