fix(#2249): correct macOS Node, Python and CouchDB steps in dev guide by ken-talltree-io · Pull Request #2250 · medic/cht-docs

ken-talltree-io · 2026-08-29T01:32:24Z

Description

Five steps in the CHT Core dev environment guide are wrong on macOS. I hit all five following the guide end to end today on macOS 26.3.1 (Apple Silicon); each fix is one I ran rather than reasoned about.

1. node@{{< param nodeVersion >}} is keg-only, so the install step doesn't take effect. Homebrew does not symlink keg-only formulae onto the PATH, so after the macOS tab's brew install, node is still whatever it was before. Adds the export PATH line, and gives the node -v && npm -v verification an explicit failure branch — as written it prints the wrong version and reports nothing wrong, so the reader goes on to build and run everything against the wrong Node.

2 & 3. pyenv global 2.7.18 pins an EOL Python the repo cannot use, in the macOS tab and again in the prerequisites list. The only Python tooling in cht-core is haproxy-healthcheck/, whose Makefile runs python3 -m venv .venv and whose .tool-versions declares python 3.10.13. The Linux and WSL2 tabs of this same guide install python3.

4. docker stop medic-couchdb names a container that is never created. The docker-compose.yml this guide downloads creates cht-docker-couchdb-1 and cht-docker-nouveau-1, so the documented command fails with No such container, and correcting only the name would still leave nouveau running. Replaces stop and start with the compose equivalents. They need the COUCHDB_* prefix because the compose file marks COUCHDB_PASSWORD mandatory with :? — without it docker compose aborts during interpolation.

5. Malformed markdown link on the bzip2 prerequisite — ])( should be ](.

How this was verified

Claim	How it was checked
`node@22` is keg-only	`brew info node@22` → `[keg-only]`, "was not symlinked into /opt/homebrew"
The verify step passes on the wrong Node	Ran the macOS tab verbatim; `node -v` reported 26.4.0, not 22.x.x
Nothing needs Python 2	`python2` absent from the machine; `npm ci` (3439 pkgs), `npm run build-dev` and `npm run dev-api` all completed clean
`.tool-versions` asks for 3.10.13	Read `haproxy-healthcheck/.tool-versions`
`docker stop medic-couchdb` fails	Ran it: `Error response from daemon: No such container: medic-couchdb`
Bare `docker compose stop` fails	Ran it: `required variable COUCHDB_PASSWORD is missing a value`
The replacement commands work	Full round trip — `stop` → both containers `Exited (143)` → `start` → both `Up` → CouchDB answering on 5984
`callout type="warning"` renders	Theme is Hextra; `callout type` already used in three other `content/en` pages

Not in this PR

#2249 also lists six improvements — a .env for the CouchDB credentials, a link to the automated-tests page, a note about the hardcoded ~/cht-core paths, where the CouchDB data lives, a question about | $SHELL in the Linux nvm install, and the missing .nvmrc in cht-core. I've deliberately kept them out of this PR so the fixes can land on their own. Happy to add any of them here or in a follow-up — your call.

What I did not verify

Only the macOS path. I have no Linux or WSL2 machine, so I have not confirmed those tabs are unaffected — I believe they are, since neither uses Homebrew or pyenv. I also did not run the e2e or integration suites, so the Python 2 claim is scoped to the setup this guide walks through rather than to the whole repo. I have not built the site locally to view the rendered page.

AI disclosure

Claude Code (Anthropic) was used to run the setup, reproduce each failure, test the replacement commands, and draft this PR. Every command in the table above was executed and its output read. I have reviewed the change and am accountable for it. — Ken Britton

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

…guide Five steps in the CHT Core dev environment guide fail when followed on macOS. node@22 is keg-only, so the macOS `brew install` never puts Node 22 on the PATH, and the `node -v && npm -v` check reports the pre-existing version without signalling that the step it verifies did not work. Adds the PATH export and gives the check an explicit failure branch. pyenv is pinned to 2.7.18 in two places, but nothing in cht-core uses Python 2: haproxy-healthcheck runs `python3 -m venv` and its .tool-versions declares python 3.10.13. Repins to that version. `docker stop medic-couchdb` names a container the guide's own compose file never creates (it creates cht-docker-couchdb-1 and cht-docker-nouveau-1), so it fails with "No such container". Replaces stop and start with the compose equivalents, which need the COUCHDB_* prefix because the compose file marks COUCHDB_PASSWORD mandatory. Also fixes a malformed markdown link on the bzip2 prerequisite. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

mrjones-plip

Thanks for the improvements! As I mentioned, new eyes make all bugs shallow ;)

requesting some small tweaks, but overall looks good.

mrjones-plip · 2026-09-02T20:15:47Z

Let's get a fix from another PR in your PR - thanks!

Suggested change

sudo apt -y install xsltproc curl uidmap jq python3 git make bzip2

mrjones-plip · 2026-09-02T20:17:37Z

Let's get a fix from another PR in your PR - thanks!

Suggested change

sudo apt -y install xsltproc curl uidmap jq python3 git make bzip2

mrjones-plip · 2026-09-02T20:18:31Z

 * [Docker](https://docs.docker.com/engine/install/)
 * [CouchDB](https://docs.couchdb.org/en/stable/install/index.html) - OS package instead of in Docker - you **MUST** use CouchDB 2.x for CHT < 4.4! We still strongly recommend using Docker.
-* [bzip2])(https://sourceware.org/bzip2/downloads.html) - if you're on Ubuntu call: `sudo apt install bzip2`
+* [bzip2](https://sourceware.org/bzip2/downloads.html) - if you're on Ubuntu call: `sudo apt install bzip2`


let's just explicitly add it per my other suggestion. then we can just remove this line and broken link:

Suggested change

* [bzip2](https://sourceware.org/bzip2/downloads.html) - if you're on Ubuntu call: `sudo apt install bzip2`

mrjones-plip · 2026-09-02T20:22:07Z

 ```

+{{< callout type="warning" >}}
+On macOS, `node@{{< param nodeVersion >}}` is [keg-only](https://docs.brew.sh/FAQ#what-does-keg-only-mean) — installing it does not put it on your PATH. If the command above reports any version other than {{< param nodeVersion >}}.x.x, the `export PATH` line from the macOS tab has not taken effect; open a new shell, or re-run it, before continuing. Everything below will otherwise silently build and run against the wrong version of Node.


Fair point about keeping this in-line as it doesn't silently fail (er, "fail"? I suspect it works against latest LTS node 🤷 ). Let's keep it here but snug up the wording:

Suggested change

On macOS, `node@{{< param nodeVersion >}}` is [keg-only](https://docs.brew.sh/FAQ#what-does-keg-only-mean) — installing it does not put it on your PATH. If the command above reports any version other than {{< param nodeVersion >}}.x.x, the `export PATH` line from the macOS tab has not taken effect; open a new shell, or re-run it, before continuing. Everything below will otherwise silently build and run against the wrong version of Node.

On macOS, `node@{{< param nodeVersion >}}` is [keg-only](https://docs.brew.sh/FAQ#what-does-keg-only-mean) so it doesn't end up in your `PATH`. If `node -v` shows a different version than {{< param nodeVersion >}}.x.x, the `export PATH` line from the macOS tab has not taken effect. To fix this, open a new shell, or re-run `export PATH`, before continuing.

…rerequisite line, tighten keg-only wording Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E3pPDjTvWBhxAKKCQdSwcn

mrjones-plip

Thanks @ken-talltree-io ! Is a much improved document for macOS users thanks to you .

Looking at it in the fully rendered site, the MacOS warning was a bit too out of place, looking like it was possibly in the Linux or WSL2 instructions, so I moved inside the MacOS tab group and a "in the command below"

ken-talltree-io mentioned this pull request Sep 2, 2026

Five defects in the CHT Core dev environment setup guide (macOS) #2249

Closed

mrjones-plip requested changes Sep 2, 2026

View reviewed changes

mrjones-plip mentioned this pull request Sep 2, 2026

some slim linux distros don't have bzip2 #2248

Closed

ken-talltree-io and others added 2 commits September 2, 2026 14:50

Apply review suggestions: add bzip2 to apt installs, drop redundant p…

d3b7058

…rerequisite line, tighten keg-only wording Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E3pPDjTvWBhxAKKCQdSwcn

move macos warning inside platform specfific tab, light reword

9fef39f

mrjones-plip approved these changes Sep 3, 2026

View reviewed changes

mrjones-plip merged commit ded59cb into medic:main Sep 3, 2026
1 check passed

Navigation Menu

Uh oh!

fix(#2249): correct macOS Node, Python and CouchDB steps in dev guide - #2250

fix(#2249): correct macOS Node, Python and CouchDB steps in dev guide#2250
mrjones-plip merged 3 commits into
medic:mainfrom
ken-talltree-io:2249-dev-environment-fixes

ken-talltree-io commented Aug 29, 2026

Uh oh!

mrjones-plip left a comment

Uh oh!

mrjones-plip Sep 2, 2026

Uh oh!

mrjones-plip Sep 2, 2026

Uh oh!

mrjones-plip Sep 2, 2026

Uh oh!

mrjones-plip Sep 2, 2026

Uh oh!

mrjones-plip left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


	sudo apt -y install xsltproc curl uidmap jq python3 git make bzip2

Uh oh!

Conversation

ken-talltree-io commented Aug 29, 2026

Description

How this was verified

Not in this PR

What I did not verify

AI disclosure

License

Uh oh!

mrjones-plip left a comment

Choose a reason for hiding this comment

Uh oh!

mrjones-plip Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mrjones-plip Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mrjones-plip Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mrjones-plip Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mrjones-plip left a comment • 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mrjones-plip left a comment •

edited

Loading