diff --git a/Justfile b/Justfile index 791b57354..0cee790fc 100644 --- a/Justfile +++ b/Justfile @@ -4,10 +4,13 @@ # Justfile - Root-level Justfile for Passport export DOCKER_IMAGE := env_var_or_default('DOCKER_IMAGE', 'foundation-devices/passport2:latest') +export DOCKER_CMD := env_var_or_default('DOCKER_CMD', 'docker') + +DOCKER_RUN := if DOCKER_CMD == 'docker' { 'docker run -u $(id -u):$(id -g)' } else { 'podman run' } # Build the docker image build-docker: - docker build -t ${DOCKER_IMAGE} . + $DOCKER_CMD build -t ${DOCKER_IMAGE} . # Build the firmware inside docker. build-firmware screen="mono": mpy-cross (run-in-docker ("just ports/stm32/build " + screen)) @@ -76,8 +79,7 @@ mpy-cross: (run-in-docker "make -C mpy-cross PROG=mpy-cross-docker BUILD=build-d [private] run-in-docker command: - docker run --rm -v "$PWD":/workspace \ - -u $(id -u):$(id -g) \ + {{DOCKER_RUN}} --rm \ -v $(pwd):/workspace \ -w /workspace \ -e MPY_CROSS="/workspace/mpy-cross/mpy-cross-docker" \ diff --git a/REPRODUCIBILITY.md b/REPRODUCIBILITY.md index a8e7b9c41..70b97f834 100644 --- a/REPRODUCIBILITY.md +++ b/REPRODUCIBILITY.md @@ -26,7 +26,7 @@ In order to build and verify the reproducibility of Passport firmware, you will - Get the source code - Install the dependencies - - [Docker](https://docs.docker.com/desktop/) + - [Docker](https://docs.docker.com/desktop/) or [Podman](https://podman.io/). - [Just](https://github.com/casey/just#installation) - Build the reproducible binaries - Verify the binaries match the: @@ -54,6 +54,8 @@ Several tools are required for building and verifying Passport’s firmware. ### Install Docker +:warning: Docker requires to add your user to the `docker` group which is root-equivalent and may pose a security risk for you. Consider using Podman if you don't want to add your user to the `docker` group. Building with `sudo` and Docker is not supported. + The installation of Docker is most easily achieved by installing Docker Desktop on your given platform using the official docs linked below. Follow those directions, launch Docker Desktop, and accept the terms before proceeding: - [Windows](https://docs.docker.com/desktop/install/windows-install/) @@ -61,6 +63,20 @@ The installation of Docker is most easily achieved by installing Docker Desktop - [Linux](https://docs.docker.com/desktop/install/linux-install/) - If you don’t want to require using `sudo` when running the `just` commands below, follow the [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) to grant your user Docker permissions on Linux +### Install Podman (optional) + +This step is optional if you already have Docker installed and your user is on the `docker` group. + +Podman does not require root or adding your user to another group, so this option is recommended for non-developer users that want to verify the reproducibility of the firmware only. + +- [Windows](https://podman.io/docs/installation#windows) +- [MacOS](https://podman.io/docs/installation#macos) +- [Linux](https://podman.io/docs/installation#installing-on-linux) + +Also, the following configuration files might need to be created after installation: + +- [Configuration files](https://podman.io/docs/installation#policyjson) + ### Install Just Just is a powerful tool that allows us to provide scripts to perform all the necessary steps of building and verification. In order to use Just, you will need to install it using the following instructions for your given operating system: @@ -99,6 +115,14 @@ just build-docker This command will take some time to run as it creates the image, including downloading and installing every tool necessary for the build process. As we use a Docker image here, not only will this ensure the binaries are always the same for a given version, but it also allows you to easily clean up after verifying the firmware and leave your system uncluttered. +If you want to opt to use Docker instead of Podman, then you can prepend set the `DOCKER_CMD` environment variable to `podman`, for example: + +```bash +DOCKER_CMD=podman just build-docker +``` + +This applies to other commands shown here as well that would normally require Docker in order to run. + If you’d like to validate exactly how the `build-docker` Justfile command functions, you can find the relevant source code here: - [passport2/Justfile#L8-L10](https://github.com/Foundation-Devices/passport2/blob/6c6249e2c15f52c59db56b12b5f84213806a6533/Justfile#L8-L10)