CHT Docker image not running on Apple Silicon

Hi Forum, I am facing some issues with setting up the CHT Core development environment.

I followed the instructions for CouchDB Setup in CHT 4.x

When I run the command to start CouchDB

COUCHDB_USER=medic COUCHDB_PASSWORD=password docker-compose -f docker-compose.yml -f couchdb-override.yml up -d

I get this output in my terminal

couchdb The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

In Docker this is the log

For context, I am using a Mac with the M2 Chip.

hello @Ben_Kiarie i think there is a platform mismatch between the requested platform for a Docker image and the host platform where you are attempting to run the Docker container.

You can consider building or pulling an image that is compatible with the host platform. We can build a multi-architecture image that supports both linux/amd64 and linux/arm64/v8 , or find an image that is already compatible with the host platform.


@tlepiz could you share which Docker image you are using to run Couch on Apple silicon? Those new steps for running CouchDB for CHT 4.x are going to pull the custom Medic image from, but I would guess we are not building an image for ARM. :thinking:

I am looking for a short-term fix to get Ben up and running, but in the long term, I think Cliff is correct that we should consider building for ARM (if only for development purposes…).

@cliff Thanks for the suggestion. I like the long term solution, perhaps adding a check to determine which image to pull depending on the host platform.

Unfortunately, from Medic’s ECR Public Gallery, I cannot tell which image supports ARM. I tried 4.3.0 but that also failed. The other possibility is to look for an image in Docker DSO where I can select my architecture.

However as @jkuester points out, I need the custom Medic image. I will wait for a suggestion from you Josh on how to resolve this issue. Thank you.

Not sure if @diana as any thoughts on this (from the Couch 3 perspective), but I would expect that you could use the CHT 3.x Couch instructions, but with the apache/couchdb:3 image (instead of apache/couchdb:2). Though, using Couch 2 would probably still work fine for you too. (I imagine @tlepiz, and others on Apple Silicon, might still be running Couch 2…)

1 Like

Hi @Ben_Kiarie

I think the easiest way to unblock you to build the images yourself. There is an npm command local-images that will build images locally:
This should also generate docker-compose files with the images in a folder called local-build in the root of your cht directory.

To get a specific version, you can checkout the tag for that version, build the application and generate the local images.

Let me know if that works for you.


Thanks Diana for pointing me in the right direction. I’ll post an update after trying it out.

1 Like

Hi @diana here is where I am so far.

  1. I cloned the repo from Master. Checking the current tag I got back 4.4.0-beta.1-4-g15990f76a
  2. I ran npm run local-images and it successfully built the local build.
  3. Checking the local-build folder I have three files and one dir cht-core.yml, cht-couchdb.yml,
    cht-couchdb-clustered.yml and srv
  4. I started the container with COUCHDB_USER=medic COUCHDB_PASSWORD=password docker-compose -f cht-couchdb.yml up -d.

Continuing with the setup

  1. Running npm run build-dev-watch worked successfully and it shows waiting.
  2. Unfortunately when I run npm run dev-api I get the following error
RequestError: Error: connect ECONNREFUSED
    at new RequestError (/Users/benkiarie/Repos/medic/cht-core/node_modules/request-promise-core/lib/errors.js:14:15)
    at (/Users/benkiarie/Repos/medic/cht-core/node_modules/request-promise-core/lib/plumbing.js:87:29)
    at Request.RP$callback [as _callback] (/Users/benkiarie/Repos/medic/cht-core/node_modules/request-promise-core/lib/plumbing.js:46:31)
    at self.callback (/Users/benkiarie/Repos/medic/cht-core/node_modules/request/request.js:185:22)
    at Request.emit (node:events:513:28)
    at Request.onRequestError (/Users/benkiarie/Repos/medic/cht-core/node_modules/request/request.js:877:8)
    at ClientRequest.emit (node:events:513:28)
    at Socket.socketErrorListener (node:_http_client:494:9)
    at Socket.emit (node:events:513:28)
    at emitErrorNT (node:internal/streams/destroy:157:8) {
  cause: Error: connect ECONNREFUSED
      at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1278:16) {
    errno: -61,
    code: 'ECONNREFUSED',
    syscall: 'connect',
    address: '',
    port: 5984
  error: Error: connect ECONNREFUSED
      at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1278:16) {
    errno: -61,
    code: 'ECONNREFUSED',
    syscall: 'connect',
    address: '',
    port: 5984


I took an educated guess and copied

      - "5984:5984"
      - "5986:5986"

Into the cht-couchdb.yml and that seems to have fixed the issue. With that update when I run docker ps I can see the>5984/tcp mapping.

Hi @Ben_Kiarie

You need to build the webapp before building the images.

  1. npm run build-dev
  2. npm run local-images
  3. docker-compose up

npm run dev-api tries to start standalone api, you should not use it unless you have couchdb already set up separately,

When I try docker-compose up from root folder and when inside local-build I get
no configuration file provided: not found

But after adding the ports to cht-couchdb.yml the application is running using

  1. npm run build-dev-watch
  2. npm run dev-api
  3. npm run dev-sentinel

Can I celebrate now :raised_hands: ? Or have I overlooked something :thinking: ?

this is expected. you didn’t pass the compose file names as parameters.

If you plan on developing on the CHT, running dev-api is the way to go. If you want to test, please test over the built images.

1 Like

Thanks for the tip for development and testing for prod.

With docker-compose -f cht-core.yml -f cht-couchdb.yml up -d I think everything looks good now :+1:

1 Like

Hi, I was facing the same issue on my Mac M1, with Docker v4.26.0, but @diana solution works out for me too.


Hi all!

Great to see folks getting CouchDB up and running on their newer Apple hardware.

Much thanks to @Ben_Kiarie , @Jennifer_Quesada and @Esther_Moturi - we now have a specific section of our documentation to address this issue. I wanted to call this out as a canonical place to look for a solution!

1 Like