feat: make docker host ports configurable via API_PORT/UI_PORT

Allow operators to remap the host-side ports (defaults 8081 api, 8080 ui)
without rebuilding images when those collide on the host. Container-internal
ports remain fixed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -5,6 +5,17 @@
 # Generate 32-byte hex secrets with: openssl rand -hex 32
 # =============================================================================
 
+# -----------------------------------------------------------------------------
+# Docker host ports (consumed by docker-compose.yml only)
+# -----------------------------------------------------------------------------
+# Host-side ports for the published service mappings. Container-internal
+# ports are fixed at 8081 (api) and 8080 (ui) — only the host side here is
+# remappable, so port collisions on the host can be resolved without
+# rebuilding the images. If you change UI_PORT, also update PUBLIC_URL
+# below so the browser-facing URL matches.
+API_PORT=8081
+UI_PORT=8080
+
 # -----------------------------------------------------------------------------
 # Shared (consumed by both api and ui containers)
 # -----------------------------------------------------------------------------

README.md

@@ -29,7 +29,9 @@ docker compose -f docker-compose.yml -f compose.scheduler.yml up -d
 
 That's it. The UI is at `http://localhost:8080`, the api at
 `http://localhost:8081`, and the API reference viewer at
-`http://localhost:8081/api/docs`.
+`http://localhost:8081/api/docs`. The host ports are configurable via
+`API_PORT` / `UI_PORT` in `.env` if those collide on your host;
+container-internal ports stay fixed.
 
 Log in with the local admin credentials you set in `.env`
 (`LOCAL_ADMIN_USERNAME` / `LOCAL_ADMIN_PASSWORD_HASH`). OIDC works too —

doc/development/SPEC.md

@@ -514,6 +514,15 @@ The UI also conditionally renders elements based on the cached role in the sessi
 
 Single `.env` file at the repo root, consumed by docker-compose. Each container reads only the variables it needs.
 
+### Docker host ports (compose only)
+```dotenv
+# Host-side ports for the published service mappings. Container-internal
+# ports stay fixed at 8081 (api) / 8080 (ui); only the host side is
+# remappable. If UI_PORT changes, also update PUBLIC_URL.
+API_PORT=8081
+UI_PORT=8080
+```
+
 ### Shared (both containers)
 ```dotenv
 # A 32-byte hex string. Used by api to authenticate the ui's calls.
@@ -644,7 +653,7 @@ services:
     command: api
     env_file: .env
     ports:
-      - "8081:8081"
+      - "${API_PORT:-8081}:8081"
     volumes:
       - irdb-data:/data
     depends_on:
@@ -662,7 +671,7 @@ services:
     build: { context: ./ui }
     env_file: .env
     ports:
-      - "8080:8080"
+      - "${UI_PORT:-8080}:8080"
     depends_on:
       api:
         condition: service_healthy

docker-compose.yml

@@ -29,7 +29,7 @@ services:
       - /home/app/.config:uid=1000,gid=1000,mode=0700
       - /home/app/.local/share:uid=1000,gid=1000,mode=0700
     ports:
-      - "8081:8081"
+      - "${API_PORT:-8081}:8081"
     volumes:
       - irdb-data:/data
     depends_on:
@@ -55,7 +55,7 @@ services:
       - /home/app/.config:uid=1000,gid=1000,mode=0700
       - /home/app/.local/share:uid=1000,gid=1000,mode=0700
     ports:
-      - "8080:8080"
+      - "${UI_PORT:-8080}:8080"
     depends_on:
       api:
         condition: service_healthy