Update README for corporate macbook by ems-sato · Pull Request #1967 · ONSdigital/eq-questionnaire-runner

ems-sato · 2026-08-28T14:16:00Z

What is the context of this PR?

Homebrew is no longer available on Corporate MacBooks, so the README's local setup instructions no longer work. This reworks them to use Miniconda + conda-forge for packages and Podman as the container runtime, replacing brew, pyenv, nvm and Colima

Reflects the decisions from the drop-in session: closest-patch Node pinning, environment.yml committed, Makefile uses docker-compose

What has changed?

README: Pre-requisites, Setup, Run with Docker and Installing dependencies rewritten; new Conda Environment and Troubleshooting sections
environment.yml: added and committed, pinning Python, Node, Poetry, snappy, jq, setting poetry env to false
Makefile: conditional approach from census31 team implemented to detect container runtime automatically
pyproject.toml / poetry.lock: added python-dotenv as an explicit dependency
.gitignore: un-ignores environment.yml

Verified end to end on a Corporate MacBook: runner, launcher and datastore all running, survey launches and completes.

How to review

conda-forge skips Node patches (22.13.0 → 22.17.0), so .nvmrc's v22.15.0 isn't available. Pinned to 22.13.0 per the agreed rule
The Makefile changes using the same conditional that census31 team already use. This removes the need for both docker -> podman symlink and the standalone docker-compose binary
Tests section left unchanged pending the Playwright PR

Retrace the new steps on a corporate Macbook and confirm the setup works from a clean start.

petechd · 2026-09-04T08:40:39Z

+Create and activate the environment:
+
+``` shell
+conda env create -f environment.yml


This command has the -n attribute missing?

conda create -n eq-questionnaire-runner -f environment.yml

environment.yml sets name: eq-runner, no -n is not needed here

petechd · 2026-09-04T08:53:29Z

-eval "$(pyenv init -)"
+#### Poetry
+
+Poetry must install into the conda environment rather than creating its own virtualenv.


Maybe some mention how to install poetry? Since we explain how to install everything else?

Sure, poetry comes via environment.yml so there is no separate install step but you are right, I will adjust to make it explicit

petechd · 2026-09-04T08:54:29Z

 ``` shell
-curl -sSL https://install.python-poetry.org | python3 - --version 2.1.2
-poetry self add poetry-plugin-dotenv
 poetry install


Maybe something about poetry update?

Yes, I can add that as a note

petechd · 2026-09-04T08:55:29Z

+- Miniconda: Python, node and system package management (install from Self Service)
+- Podman: Container runtime for supporting services (machine created and running)
+- wkhtmltopdf: PDF generation (installed separately, see below)
+- gcloud: Pulling images from Google Artifact Registry


It's not in Self Service as a package so we should mention it should be installed from source?

Yes, I got it confused. Will add that

petechd · 2026-09-04T08:57:14Z

+podman machine start
+```
+
+`wkhtmltopdf` is nor reliably available on conda-forge for macOS ARM, so it is installed outside the conda environment.


A typo here.

Thanks for catching that! Fixed!

petechd · 2026-09-04T09:06:36Z

 ```

-On MacOS install container runtimes, eg. [Colima](https://github.com/abiosoft/colima):
+Podman is API-compatible with Docker, so provide a `docker` command that points at it. This is still needed for the plain `docker run` commands used later in this README (e.g. running launcher, SDS, CIR images):


Any need for alias docker=podman anymore in .zshrc? Or would it only confuse us?

I dont think we need it as we went for this option in the drop-in discussion: Change the Makefile to docker-compose. No per-machine setup, but this fixes only compose commands and docker build target would still need the symlink

My vote would be for adding this as an alias but happy to go with the flow on this. I forgot we discussed this originally as a team 🫣

Sure, lets agree on adding it as an alias and we can review this in a couple of months time

liamtoozer

Great work 👍 Able to spin up Runner and is working great 🙌 Just some really minor questions/comments

liamtoozer · 2026-09-07T09:47:41Z

-	docker compose -f docker-compose-dev.yml pull sds
-	docker compose -f docker-compose-dev.yml pull cir
-	docker compose -f docker-compose-dev.yml up -d
+	docker-compose -f docker-compose-dev.yml pull eq-questionnaire-launcher


I might be wrong but I've noticed it worked without the hyphens here. podman compose and docker compose both seem to work okay for me 🤔

I've noticed a few teams have set a condition at the top of their Makefile to handle docker/podman mappings, so this might be enough here? For example: https://github.com/ONSdigital/census31-rm-fieldwork-adapter/blob/be5f9531848f6e751323b62822defee25c02cd82/Makefile#L2

Yes, so both forms should work if you have the docker -> podman symlink. This was the option we picked at the drop-in session. The conditional approach in census31 team looks like a good alternative as well, happy to have a follow-up with the team to pick which solution we should go ahead with

After discussion, have implemented census31 team conditional approach

liamtoozer · 2026-09-07T11:48:48Z

+docker --version
+```
+
+The Makefile and the commands below use the standalone `docker-compose` binary (not the


I might be wrong with this again, but we might not need to do this, as per this comment: https://github.com/ONSdigital/eq-questionnaire-runner/pull/1967/changes#r3948509228

liamtoozer · 2026-09-07T15:05:29Z

@@ -11,27 +11,46 @@

 ## Run with Docker


Very minor - does this section name need to change if we're using Podman?

Renamed to "Run with Podman"

liamtoozer · 2026-09-07T16:06:16Z

+
 ```shell
-colima start
+docker --version


One small thing I wondered about here: This will return something likedocker version 5.8.4, but that’s actually reflecting the Podman version rather than a real Docker install. Not sure what is the best for this and open to suggestions, but I would probably vote for alias docker='podman' in shell profile?

Done, added alias to readme

liamtoozer · 2026-09-07T16:10:39Z


 ``` shell
-RUNNER_ENV_FILE=.development.env docker compose up -d
+RUNNER_ENV_FILE=.development.env docker-compose up -d


Hyphen might not be needed here and in the other places?

liamtoozer · 2026-09-08T13:36:19Z

+Set this on the environment so that no configuration file is left in the repository:
+
+``` shell
+conda env config vars set POETRY_VIRTUALENVS_CREATE=false


Just wondered if this could be instead set in the environment.yml file in the variables: block?

Yes! I dont know why I didnt think of that. Yes, that should be possible

ems-sato added 2 commits August 28, 2026 15:08

Update README for corporate macbook

281bd74

update README with environment.yml and docker-compose switch

b2218d7

ems-sato marked this pull request as ready for review September 1, 2026 15:59

ems-sato requested a review from a team as a code owner September 1, 2026 15:59

Add python-dotenv as an explicit dependency

2906650

ems-sato mentioned this pull request Sep 2, 2026

Update README for corporate macbook ONSdigital/eq-questionnaire-launcher#113

Open

petechd reviewed Sep 4, 2026

View reviewed changes

README download examples

97cbe1c

ems-sato force-pushed the EQS-1149-Update-READMEs-Makefile-commands-for-Corporate-Macs branch from 661921c to 97cbe1c Compare September 8, 2026 12:17

liamtoozer reviewed Sep 8, 2026

View reviewed changes

Makefile to detect container runtime and use Podman in README

0c0ed3a

Uh oh!

Conversation

ems-sato commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the context of this PR?

What has changed?

How to review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ems-sato Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liamtoozer left a comment

Choose a reason for hiding this comment

Uh oh!

liamtoozer Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

liamtoozer Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ems-sato commented Aug 28, 2026 •

edited

Loading

ems-sato Sep 9, 2026 •

edited

Loading

liamtoozer Sep 7, 2026 •

edited

Loading

liamtoozer Sep 7, 2026 •

edited

Loading