Docs: running Pithagoras with Docker on a Mac

Open Beginner friendly
  • Is something wrong?
#306 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
docker, docker-compose, macos, node.js, typescript
Domain
devops, documentation

Research direction

Read the README quick start and docs/guide/deploying.md, then check both Compose files to confirm the network_mode: host behavior described in the issue. Add the requested macOS guidance covering Linux container engines, Apple Silicon image support and emulation, Docker Desktop host networking, and the Node version and socket path limit. Done when both documentation locations explain these setup constraints accurately.

Written by the indexing model from the issue text.

Description

documentation

From #1: the README and docs/guide/deploying.md never say that Pithagoras needs a Docker engine that runs Linux containers, and they never mention macOS. The reporter used the macOS-native container engine (darwin-containers / rund). It can only run macOS images, so the build failed in a way that can't be fixed on that engine.

What we want

An "On a Mac" section in deploying.md, and a line in the README's quick start, saying:

  • Use a Docker that runs Linux in a VM: Docker Desktop, OrbStack or Colima, with docker context use pointing at it. The macOS-native container engine can't run Pithagoras.
  • docker compose up -d --build builds a native image on Apple Silicon. The prebuilt image is linux/amd64 only until #305; with it, set DOCKER_DEFAULT_PLATFORM=linux/amd64 and it runs under emulation.
  • Both compose files use network_mode: host. Docker Desktop honours that only when host networking is turned on in its settings; otherwise port 4100 isn't reachable from the Mac. Document that switch, or give a ports: variant for a Mac.
  • Running from source with Node 22.19 or newer works too. One known limit on a Mac is in #43: the server's socket path has to stay under macOS's shorter limit, so a long data-folder path can stop it from starting.
Dominant language
TypeScript
Stars
297
Forks
81
Avg merge
8h 47m
Merged PRs (30d)
167

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from thecodacus/pithagoras

All issues in thecodacus/pithagoras

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.