From dd782fcec0d8f6918a039ee585fea55db4af19c8 Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 7 Feb 2026 11:43:30 +0000 Subject: [PATCH 1/2] Fix Docker Compose for macOS and document setup learnings - Remove obsolete version key from docker-compose.yml to suppress deprecation warnings - Add anonymous volume for node_modules to isolate Linux-native packages from macOS bind mount (prevents platform mismatch for esbuild, tsx, Prisma binaries) - Document macOS Apple Silicon setup gotchas in README including PostGIS platform emulation, node_modules isolation, first-time setup commands, and Prisma OpenSSL warning - Fix .gitignore: remove !dist/ and !build/ negations that accidentally un-ignored the dist/ directory, causing build artifacts like dist/proto/ to appear as untracked Co-authored-by: Cursor --- .gitignore | 2 -- README.md | 39 +++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 2 +- 3 files changed, 40 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 6e4e12a..d145e42 100644 --- a/.gitignore +++ b/.gitignore @@ -36,8 +36,6 @@ Thumbs.db # Ignore compiled JS in source tree (should only be in dist/ or build/) *.js *.js.map -!dist/ -!build/ # Ignore test output *.test.js diff --git a/README.md b/README.md index b730a16..ce38b4c 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,45 @@ docker compose up --build - The API will be available at `http://localhost:3000` (or as configured). - The PostgreSQL container is also started. +### Running on macOS (Apple Silicon / ARM) + +When running this project with Docker on macOS (especially Apple Silicon / M-series chips), there are a few things to be aware of: + +1. **Platform mismatch for PostGIS image:** + The `postgis/postgis:15-3.4` image is built for `linux/amd64`. Docker Desktop on Apple Silicon runs it under emulation automatically, but you may see a warning: + > `The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)` + + This is expected and the container works correctly under emulation. + +2. **Node modules volume isolation (bind mount + native binaries):** + The `docker-compose.yml` uses a bind mount (`.:/usr/src/app`) for live code reloading. An anonymous volume (`/usr/src/app/node_modules`) is used to prevent the host's macOS-native `node_modules` from overriding the container's Linux-native packages. This is critical because packages like `esbuild`, `tsx`, and Prisma's query engine include platform-specific binaries that differ between macOS ARM and Linux. + + If you see errors like `@esbuild/darwin-arm64 package is present but this platform needs @esbuild/linux-arm64`, the `node_modules` volume isolation is not working correctly. Ensure the anonymous volume line is present in `docker-compose.yml`: + ```yaml + volumes: + - .:/usr/src/app + - /usr/src/app/node_modules + ``` + +3. **First-time setup after cloning:** + After `docker compose up --build`, you may need to run these commands inside the container on first setup: + ```sh + # Generate Prisma client (for the container's Linux platform) + docker compose exec api npx prisma generate + + # Apply database migrations + docker compose exec api npx prisma migrate deploy + + # Generate Protobuf JS/TS files (if not already present) + docker compose exec api npm run proto:all + ``` + +4. **Prisma OpenSSL warning:** + You may see a Prisma warning about failing to detect the libssl/openssl version. This is cosmetic and does not affect functionality. If needed, install OpenSSL in the container by adding to the Dockerfile: + ```dockerfile + RUN apt-get update -y && apt-get install -y openssl + ``` + ### Running Tests Tests should be run **inside the container**: diff --git a/docker-compose.yml b/docker-compose.yml index 2343faa..0a41460 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,4 +1,3 @@ -version: '3.8' services: postgres: image: postgis/postgis:15-3.4 @@ -25,6 +24,7 @@ services: restart: always volumes: - .:/usr/src/app + - /usr/src/app/node_modules healthcheck: test: ['CMD', 'curl', '-f', 'http://localhost:3000/api-docs'] interval: 10s From 8ce6e6106d2015dadb344e6c6ec4ce0e31378515 Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 7 Feb 2026 11:59:05 +0000 Subject: [PATCH 2/2] chore(gitignore): reinstate previous changes --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index d145e42..6e4e12a 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,8 @@ Thumbs.db # Ignore compiled JS in source tree (should only be in dist/ or build/) *.js *.js.map +!dist/ +!build/ # Ignore test output *.test.js