From 870cfb98f75d5ec55a1bf2ab8bef9002f219afb3 Mon Sep 17 00:00:00 2001
From: Nicolas Pastorello <nicolaspastorello1@gmail.com>
Date: Mon, 27 Jul 2026 16:13:56 -0300
Subject: [PATCH] fix(docker): use HOST_PORT for the published port
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Setting PORT in .env.local moved the port the server listens on
*inside* the container (env_file injects it), while the mapping and
the healthcheck stayed on 3000 — so the container came up
unreachable.

The published port is now HOST_PORT, and PORT is pinned to 3000 via
`environment` (which takes precedence over env_file) so a leftover
PORT in .env.local can no longer desync the app from the mapping.
Documented both, including for the plain-docker path.
---
 docker-compose.yml | 15 +++++++++++----
 docs/docker.md     | 10 ++++++++--
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 1d1fec3..3df1e2e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -16,15 +16,22 @@ services:
     # never baked into the image.
     env_file:
       - .env.local
+    # The server always listens on 3000 inside the container. Pinned
+    # here because `environment` wins over `env_file`, so a stray PORT
+    # in .env.local can't desync the app from the mapping and the
+    # healthcheck below.
+    environment:
+      PORT: 3000
+    # Host side only — HOST_PORT=8080 publishes the app on :8080.
     ports:
-      - "${PORT:-3000}:3000"
+      - '${HOST_PORT:-3000}:3000'
     restart: unless-stopped
     healthcheck:
       test:
         [
-          "CMD",
-          "node",
-          "-e",
+          'CMD',
+          'node',
+          '-e',
           "fetch('http://localhost:3000').then((r)=>process.exit(r.ok||r.status<500?0:1)).catch(()=>process.exit(1))",
         ]
       interval: 30s
diff --git a/docs/docker.md b/docs/docker.md
index a074869..9834c90 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -23,7 +23,13 @@ is included.
    ```
 
 3. The app is served on [http://localhost:3000](http://localhost:3000)
-   (override the host port with `PORT=8080` in `.env.local`).
+   (publish it elsewhere with `HOST_PORT=8080` in `.env.local`).
+
+> Use `HOST_PORT`, not `PORT`, to move the published port. `PORT` is
+> what the server listens on _inside_ the container, and `env_file`
+> would inject it there — leaving the app on a port the mapping and
+> the healthcheck don't target. Compose pins it to 3000 for that
+> reason.
 
 ## Build-time vs runtime variables
 
@@ -44,7 +50,7 @@ docker build \
   --build-arg NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key \
   -t wacrm .
 
-docker run -d --env-file .env.local -p 3000:3000 wacrm
+docker run -d --env-file .env.local -e PORT=3000 -p 3000:3000 wacrm
 ```
 
 ## Notes