-
Notifications
You must be signed in to change notification settings - Fork 58
fix(#2249): correct macOS Node, Python and CouchDB steps in dev guide #2250
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
mrjones-plip
merged 3 commits into
medic:main
from
ken-talltree-io:2249-dev-environment-fixes
Sep 3, 2026
Merged
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
11b0e58
fix(#2249): correct macOS Node, Python and CouchDB steps in dev guide
ken-talltree-io d3b7058
Apply review suggestions: add bzip2 to apt installs, drop redundant p…
ken-talltree-io 9fef39f
move macos warning inside platform specfific tab, light reword
mrjones-plip File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||
|---|---|---|---|---|
|
|
@@ -48,9 +48,11 @@ _(Node {{< param nodeVersion >}} is the environment used to run the CHT server i | |||
| # Uses Homebrew: https://brew.sh/ | ||||
| brew update | ||||
| brew install curl jq pyenv git make node@{{< param nodeVersion >}} | ||||
| # Python no longer included by default in macOS >12.3 | ||||
| pyenv install 2.7.18 | ||||
| pyenv global 2.7.18 | ||||
| # node@{{< param nodeVersion >}} is keg-only, so Homebrew does not symlink it onto your PATH. | ||||
| echo "export PATH=\"\$(brew --prefix node@{{< param nodeVersion >}})/bin:\$PATH\"" >> ~/.$(basename $SHELL)rc | ||||
| # Python is no longer included by default in macOS >12.3 | ||||
| pyenv install 3.10.13 | ||||
| pyenv global 3.10.13 | ||||
| echo "eval \"\$(pyenv init --path)\"" >> ~/.$(basename $SHELL)rc | ||||
| . ~/.$(basename $SHELL)rc | ||||
| ``` | ||||
|
|
@@ -75,6 +77,10 @@ Now let's ensure NodeJS {{< param nodeVersion >}} and npm {{< param npmVersion > | |||
| node -v && npm -v | ||||
| ``` | ||||
|
|
||||
| {{< 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. | ||||
| {{< /callout >}} | ||||
|
|
||||
| Install Docker: | ||||
|
|
||||
| {{< read-content file="_partial_docker_setup.md" >}} | ||||
|
|
@@ -166,7 +172,14 @@ cd ~/cht-core && npm run dev-sentinel | |||
|
|
||||
| That's it! Now when you edit code in your IDE, it will automatically reload. You can see the CHT running locally here: [http://localhost:5988/](http://localhost:5988/) | ||||
|
|
||||
| When you're done with development you can `ctrl + c` in the three terminals and stop the CouchDB container with `docker stop medic-couchdb`. When you want to resume development later, run `docker start medic-couchdb` and re-run the three terminal commands. | ||||
| When you're done with development you can `ctrl + c` in the three terminals and stop the CouchDB containers with: | ||||
|
|
||||
| ```shell | ||||
| cd ~/cht-docker | ||||
| COUCHDB_USER=medic COUCHDB_PASSWORD=password docker compose -f docker-compose.yml -f couchdb-override.yml stop | ||||
| ``` | ||||
|
|
||||
| When you want to resume development later, run the same command with `start` in place of `stop`, then re-run the three terminal commands. The `COUCHDB_*` variables are required because `docker-compose.yml` declares `COUCHDB_PASSWORD` as mandatory; without them `docker compose` aborts before it reaches the container. | ||||
|
|
||||
| ### Adding and accessing data | ||||
|
|
||||
|
|
@@ -190,10 +203,10 @@ If you had issues with following the above steps, check out these links for how | |||
|
|
||||
| * [Node.js {{< param nodeVersion >}}.x](https://nodejs.org/) & [npm {{< param npmVersion >}}.x.x](https://npmjs.com/) - Both of which we recommend installing [via `nvm`](https://github.com/nvm-sh/nvm#installing-and-updating) | ||||
| * [xsltproc](https://github.com/ilyar/xsltproc) | ||||
| * [python 2.7](https://www.python.org/downloads/) | ||||
| * [python 3](https://www.python.org/downloads/) | ||||
| * [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` | ||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. let's just explicitly add it per my other suggestion. then we can just remove this line and broken link:
Suggested change
|
||||
|
|
||||
| ### Windows WSL2 | ||||
|
|
||||
|
|
||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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: