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