(DRAFT) Add automatic local dev port resolution

.env.docker

@@ -57,10 +57,10 @@ DC_MINIO_ACCESS_KEY=medusaappkey
 DC_MINIO_SECRET_KEY=medusaappsecret_change_me
 
 # Postgres container + bootstrap role setup
+DC_POSTGRES_PUBLIC_PORT=5433
+DC_POSTGRES_SSLMODE=disable
 DC_POSTGRES_SUPERUSER=root
 DC_POSTGRES_SUPERUSER_PASSWORD=root
-DC_POSTGRES_PUBLIC_PORT=5432
-DC_POSTGRES_SSLMODE=disable
 DC_POSTGRES_VOLUME_DATA=./.docker_data/db18
 # Bootstrap-only role used by init script (not used by medusa-be runtime directly)
 DC_MEDUSA_DEV_DB_USER=medusa_dev

.mise.toml

@@ -8,6 +8,14 @@ node = "latest"
 description = "Incremental local startup after `dev:init`: resources -> meili provisioning -> backend phase -> frontend phase"
 run = "mise run dev:resources && mise run dev:internal:meili:sync-env && mise run dev:backend && mise run dev:frontend"
 
+[tasks."dev:ports"]
+description = "Resolve available local host ports into the generated Docker Compose env file"
+run = "bash ./scripts/dev/mise-dev-helpers.sh resolve-local-ports"
+
+[tasks."dev:info"]
+description = "Print the current worktree-local Docker Compose project, generated ports, and running services"
+run = "bash ./scripts/dev/stack-info.sh"
+
 [tasks."dev:init"]
 description = "First-time local initialization: env bootstrap -> dependency install -> backend bootstrap -> admin user -> seed"
 run = "bash ./scripts/dev/init-local-stack.sh"
@@ -22,7 +30,7 @@ run = "mise run dev:internal:down"
 
 [tasks."dev:down:volumes"]
 description = "Stop the local compose stack and remove named volumes"
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} down -v --remove-orphans --timeout ${COMPOSE_STOP_TIMEOUT:-60}"
+run = "bash ./scripts/dev/compose.sh down -v --remove-orphans --timeout ${COMPOSE_STOP_TIMEOUT:-60}"
 
 [tasks."dev:resources"]
 description = "Start and wait for manifest-defined shared resources"
@@ -74,35 +82,35 @@ run = "bash ./scripts/dev/run-prod-stack.sh --no-cache"
 
 [tasks."dev:medusa:user:create"]
 description = "Create a Medusa admin user in the running local stack (requires EMAIL and PASSWORD)"
-run = """bash -lc 'test -n \"${EMAIL:-}\" && test -n \"${PASSWORD:-}\" || { echo \"EMAIL and PASSWORD are required.\" >&2; exit 1; }; docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be exec medusa user -e \"$EMAIL\" -p \"$PASSWORD\"'"""
+run = """bash -lc 'test -n \"${EMAIL:-}\" && test -n \"${PASSWORD:-}\" || { echo \"EMAIL and PASSWORD are required.\" >&2; exit 1; }; bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be exec medusa user -e \"$EMAIL\" -p \"$PASSWORD\"'"""
 
 [tasks."dev:medusa:migrate"]
 description = "Run Medusa migrations against the running local stack"
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be run migrate"
+run = "bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be run migrate"
 
 [tasks."dev:medusa:migration:generate"]
 description = "Generate a Medusa migration in the running local stack (requires MODULE)"
-run = """bash -lc 'test -n \"${MODULE:-}\" || { echo \"MODULE is required.\" >&2; exit 1; }; docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be run migrate:generate-only \"$MODULE\"'"""
+run = """bash -lc 'test -n \"${MODULE:-}\" || { echo \"MODULE is required.\" >&2; exit 1; }; bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be run migrate:generate-only \"$MODULE\"'"""
 
 [tasks."dev:medusa:minio:init"]
 description = "Manually reapply the local MinIO bootstrap fallback against the running stack"
 run = "bash ./scripts/dev/minio-init.sh"
 
 [tasks."dev:medusa:meili:reseed"]
 description = "Rebuild Medusa search documents in the running local stack"
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be run addInitialSearchDocuments"
+run = "bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be run addInitialSearchDocuments"
 
 [tasks."dev:medusa:seed"]
 description = "Seed initial Medusa data in the running local stack"
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be run seedInitialData"
+run = "bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be run seedInitialData"
 
 [tasks."dev:medusa:seed:dev-data"]
 description = "Seed Medusa development data in the running local stack"
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be run seedDevData"
+run = "bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be run seedDevData"
 
 [tasks."dev:medusa:seed:n1"]
 description = "Seed N1-specific Medusa data in the running local stack"
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} exec medusa-be pnpm --filter medusa-be run seedN1"
+run = "bash ./scripts/dev/compose.sh exec medusa-be pnpm --filter medusa-be run seedN1"
 
 [tasks."dev:postgres:bootstrap"]
 description = "Rerun medusa-db role bootstrap against the running local stack"
@@ -163,12 +171,12 @@ run = "MEDUSA_E2E_KEEP_STACK=1 bash ./scripts/e2e/medusa-be-http.sh run"
 [tasks."dev:internal:resources:up"]
 description = "Start manifest-defined shared resource services"
 hide = true
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} up -d --build $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase resources)"
+run = "bash ./scripts/dev/compose.sh up -d --build $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase resources)"
 
 [tasks."dev:internal:down"]
 description = "Gracefully stop and remove compose services before stepped startup"
 hide = true
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} down --remove-orphans --timeout ${COMPOSE_STOP_TIMEOUT:-60}"
+run = "bash ./scripts/dev/compose.sh down --remove-orphans --timeout ${COMPOSE_STOP_TIMEOUT:-60}"
 
 [tasks."dev:internal:resources:wait"]
 description = "Wait for manifest-defined shared resource services to become healthy"
@@ -183,12 +191,12 @@ run = "bash ./scripts/dev/mise-dev-helpers.sh sync-meili-env"
 [tasks."dev:internal:backend:up"]
 description = "Start manifest-defined backend phase services"
 hide = true
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} up -d --build --no-deps $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase backend)"
+run = "bash ./scripts/dev/compose.sh up -d --build --no-deps $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase backend)"
 
 [tasks."dev:internal:backend:prepare"]
 description = "Run Medusa DB migrations before backend startup"
 hide = true
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} run --rm --build --no-deps medusa-be pnpm --filter medusa-be run migrate"
+run = "bash ./scripts/dev/compose.sh build medusa-be && bash ./scripts/dev/compose.sh run --rm --no-deps medusa-be pnpm --filter medusa-be run migrate"
 
 [tasks."dev:internal:backend:wait"]
 description = "Wait for manifest-defined backend phase services to become healthy"
@@ -198,7 +206,7 @@ run = "bash ./scripts/dev/mise-dev-helpers.sh wait-healthy $(bash ./scripts/dev/
 [tasks."dev:internal:frontend:up"]
 description = "Start manifest-defined frontend phase services"
 hide = true
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} up -d --build --no-deps $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase frontend)"
+run = "bash ./scripts/dev/compose.sh up -d --build --no-deps $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase frontend)"
 
 [tasks."dev:internal:frontend:wait"]
 description = "Wait for manifest-defined frontend phase services to become healthy"
@@ -208,7 +216,7 @@ run = "bash ./scripts/dev/mise-dev-helpers.sh wait-healthy $(bash ./scripts/dev/
 [tasks."dev:internal:operator:up"]
 description = "Start manifest-defined operator phase services"
 hide = true
-run = "docker compose -f docker-compose.yaml -p ${PROJECT_NAME:-new-engine} --profile operator up -d --build --no-deps $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase operator)"
+run = "bash ./scripts/dev/compose.sh --profile operator up -d --build --no-deps $(bash ./scripts/dev/mise-dev-helpers.sh services-for-phase operator)"
 
 [tasks."dev:internal:operator:wait"]
 description = "Wait for manifest-defined operator phase services to become healthy"

README.md

@@ -42,6 +42,8 @@
     5. `n1`
 
     Common follow-up tasks stay on the public `mise` surface:
+    * show this worktree's Compose project, resolved ports, and running services: `mise run dev:info`
+    * resolve local host ports without starting the stack: `mise run dev:ports`
     * rerun first-time bootstrap from the top: `mise run dev:init`
     * non-destructive restart from a stopped stack: `mise run dev:fresh`
     * stop the stack: `mise run dev:down`
@@ -52,10 +54,16 @@
     * verify hardened Postgres grants: `mise run dev:postgres:grants:verify`
 
     During `dev` startup, `.env` handling is opinionated:
+    * every worktree gets its own deterministic Docker Compose project name derived from its absolute path; override with `PROJECT_NAME` when needed
+    * Compose container names are generated from that project name and service name, so multiple Git worktrees can run side by side without fixed container-name collisions
+    * host-published Docker ports are resolved before Compose `up`/`run` commands and written to `.docker_data/dev-runtime.env`
+    * if a preferred port from `.env` or the local resolver defaults is busy, the next available port is selected automatically
+    * container-to-container runtime envs stay stable; for example `DC_MEDUSA_APP_DB_HOST=medusa-db` and `DC_MEDUSA_APP_DB_PORT=5432` still define the Medusa/ZaneOps DB endpoint inside the Docker network
+    * host-facing local URLs such as `DC_N1_NEXT_PUBLIC_MEDUSA_BACKEND_URL`, `DC_N1_NEXT_PUBLIC_MEILISEARCH_URL`, CORS values, and `MISE_DEV_MEILI_URL` are generated from the resolved public ports unless you already customized them in `.env`
     * if `DC_MEILISEARCH_BACKEND_API_KEY` / `DC_N1_NEXT_PUBLIC_MEILISEARCH_API_KEY` are empty, values are written
     * if existing values differ, you are prompted to `override` or `keep`
     * Meilisearch key policy/provisioning is owned by `apps/new-engine-ctl meili-api-credentials`; only `mise run dev` performs `.env` sync logic
-    * `mise run dev` calls provisioning against host URL `http://127.0.0.1:7700` by default (override via `MISE_DEV_MEILI_URL`) so `DC_MEILISEARCH_HOST` can remain container-internal (`http://medusa-meilisearch:7700`)
+    * `mise run dev` calls provisioning against the resolved host Meilisearch URL (override via `MISE_DEV_MEILI_URL`) so `DC_MEILISEARCH_HOST` can remain container-internal (`http://medusa-meilisearch:7700`)
 
     * Postgres role bootstrap (`medusa_app`, `medusa_dev`, `zane_operator`) runs automatically from `medusa-db` startup via `/usr/local/bin/run-postgres-with-bootstrap.sh`
     * MinIO bootstrap now runs inside `medusa-minio` startup (idempotent): it ensures `DC_MINIO_BUCKET` exists, enforces public object reads, and provisions a non-root Medusa runtime key with bucket-scoped permissions limited to the Medusa bucket
@@ -197,6 +205,7 @@ When DB env wiring changes, apply these actions manually on the live `.env` file
     * provider policy lives in `apps/new-engine-ctl/config/stack-inputs.yaml`, not in shell scripts
 
 9. <b>Explore local envs</b>
+    * The exact project name and host ports for your machine are printed by `mise run dev:info`; raw port values are in `.docker_data/dev-runtime.env` after `mise run dev:ports`, `mise run dev:init`, or `mise run dev`.
     * N1 FE should be available at:
         * <a href="http://localhost:8000">localhost:8000</a>
         * <a href="https://n1.medusa.localhost">https://n1.medusa.localhost</a>
@@ -222,7 +231,7 @@ When DB env wiring changes, apply these actions manually on the live `.env` file
             * bearer token: `DC_ZANE_OPERATOR_API_AUTH_TOKEN`
     * Redis compatible ValKey storage can be connected at `localhost:6379`
         * password: `DC_VALKEY_PASSWORD` (default in `.env`: `valkey_dev_change_me`)
-    * Postgres DB can be connected at `localhost:5432`
+    * Postgres DB can be connected at `localhost:5433` by default, or the resolved `DC_POSTGRES_PUBLIC_PORT`
         * default credentials: `root`/`root`
         * adminer can be accessed on <a href="http://localhost:8081">localhost:8081</a>
 

apps/medusa-be/.env.template

@@ -1,6 +1,6 @@
 # Core runtime
 NODE_ENV=development
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/medusa
+DATABASE_URL=postgres://postgres:postgres@localhost:5433/medusa
 MEDUSA_DATABASE_SCHEMA=public
 # Fallback schema env used by Medusa module DB loader.
 DATABASE_SCHEMA=public

docker-compose.yaml

@@ -96,11 +96,10 @@ x-zane-operator-env: &zane-operator-env
 
 x-medusa-base: &medusa-base
   restart: unless-stopped
-  container_name: wr_medusa_be
   ports:
-    - "127.0.0.1:9000:9000"
-    - "127.0.0.1:9009:9009"
-    - "127.0.0.1:24678:24678"
+    - "127.0.0.1:${DC_MEDUSA_BE_PUBLIC_PORT:-9000}:9000"
+    - "127.0.0.1:${DC_MEDUSA_BE_ADMIN_PUBLIC_PORT:-9009}:9009"
+    - "127.0.0.1:${DC_MEDUSA_BE_HMR_PUBLIC_PORT:-24678}:24678"
   depends_on:
     medusa-db:
       condition: service_healthy
@@ -154,7 +153,6 @@ services:
       interval: 10s
   n1:
     restart: unless-stopped
-    container_name: wr_n1
     build:
       context: .
       dockerfile: docker/development/n1/Dockerfile
@@ -166,7 +164,7 @@ services:
       medusa-be:
         condition: service_healthy
     ports:
-      - "127.0.0.1:8000:3000"
+      - "127.0.0.1:${DC_N1_PUBLIC_PORT:-8000}:3000"
     networks:
       - internal
     environment:
@@ -184,15 +182,14 @@ services:
       context: ./docker/development/medusa-valkey
       dockerfile: Dockerfile
     command: ["sh", "-lc", "exec valkey-server --requirepass \"$$VALKEY_PASSWORD\" --appendonly yes"]
-    container_name: wr_medusa_valkey
     healthcheck:
       test: ["CMD-SHELL", "valkey-cli -a \"$${VALKEY_PASSWORD}\" --no-auth-warning ping | grep -q PONG"]
       start_period: 5s
       timeout: 3s
       interval: 1s
       retries: 5
     ports:
-      - "127.0.0.1:6379:6379"
+      - "127.0.0.1:${DC_VALKEY_PUBLIC_PORT:-6379}:6379"
     volumes:
       - medusa-valkey-data:/data
     networks:
@@ -203,10 +200,9 @@ services:
     build:
       context: ./docker/development/medusa-minio
       dockerfile: Dockerfile
-    container_name: wr_medusa_minio
     ports:
-      - "127.0.0.1:9003:9003"
-      - "127.0.0.1:9004:9004"
+      - "127.0.0.1:${DC_MINIO_CONSOLE_PUBLIC_PORT:-9003}:9003"
+      - "127.0.0.1:${DC_MINIO_API_PUBLIC_PORT:-9004}:9004"
     volumes:
       - medusa-minio-data:/data
     networks:
@@ -220,9 +216,8 @@ services:
     build:
       context: ./docker/development/medusa-meilisearch
       dockerfile: Dockerfile
-    container_name: wr_medusa_meilisearch
     ports:
-      - "127.0.0.1:7700:7700"
+      - "127.0.0.1:${DC_MEILISEARCH_PUBLIC_PORT:-7700}:7700"
     volumes:
       - medusa-meilisearch-data:/meili_data
     networks:
@@ -241,7 +236,7 @@ services:
     restart: unless-stopped
     command: ["/usr/local/bin/run-postgres-with-bootstrap.sh"]
     ports:
-      - "127.0.0.1:${DC_POSTGRES_PUBLIC_PORT:-5432}:5432"
+      - "127.0.0.1:${DC_POSTGRES_PUBLIC_PORT:-5433}:5432"
     volumes:
       - ${DC_POSTGRES_VOLUME_DATA:-./.docker_data/db18}:/var/lib/postgresql
     networks:
@@ -292,7 +287,7 @@ services:
       MYSQL_PASSWORD: 1234
     command: --sql_mode="NO_ENGINE_SUBSTITUTION"
     ports:
-      - "127.0.0.1:3306:3306"
+      - "127.0.0.1:${DC_ENGINE_DB_PUBLIC_PORT:-3306}:3306"
     volumes:
       - ./.docker_data/dbmysql:/var/lib/mysql
       - ./docker/development/mariadb/wr.cnf:/etc/mysql/conf.d/wr.cnf
@@ -302,7 +297,7 @@ services:
     image: adminer
     restart: unless-stopped
     ports:
-      - "127.0.0.1:8081:8080"
+      - "127.0.0.1:${DC_ADMINER_PUBLIC_PORT:-8081}:8080"
     depends_on:
       - medusa-db
     networks:
@@ -318,9 +313,11 @@ services:
     cap_add:
       - NET_ADMIN
     ports:
-      - "127.0.0.1:80:80"
-      - "127.0.0.1:443:443"
-      - "127.0.0.1:443:443/udp"
+      - "127.0.0.1:${DC_CADDY_HTTP_PUBLIC_PORT:-80}:80"
+      - "127.0.0.1:${DC_CADDY_HTTPS_PUBLIC_PORT:-443}:443"
+      - "127.0.0.1:${DC_CADDY_HTTPS_PUBLIC_PORT:-443}:443/udp"
+    environment:
+      DC_CADDY_HTTPS_PUBLIC_PORT: ${DC_CADDY_HTTPS_PUBLIC_PORT:-443}
     networks:
       - internal
     volumes:

docker/development/caddy/Caddyfile

@@ -17,7 +17,7 @@ admin.medusa.localhost:9009 {
 }
 
 admin.medusa.localhost {
-    redir https://{host}{uri}
+    redir https://admin.medusa.localhost:{$DC_CADDY_HTTPS_PUBLIC_PORT:443}{uri}
 }
 
 n1.medusa.localhost:443 {
@@ -26,7 +26,7 @@ n1.medusa.localhost:443 {
 }
 
 n1.medusa.localhost {
-    redir https://{host}{uri}
+    redir https://n1.medusa.localhost:{$DC_CADDY_HTTPS_PUBLIC_PORT:443}{uri}
 }
 
 admin.meilisearch.localhost:443 {
@@ -35,7 +35,7 @@ admin.meilisearch.localhost:443 {
 }
 
 admin.meilisearch.localhost {
-    redir https://{host}{uri}
+    redir https://admin.meilisearch.localhost:{$DC_CADDY_HTTPS_PUBLIC_PORT:443}{uri}
 }
 
 admin.minio.localhost:443 {
@@ -49,7 +49,7 @@ api.minio.localhost:80 {
 }
 
 admin.minio.localhost {
-    redir https://{host}{uri}
+    redir https://admin.minio.localhost:{$DC_CADDY_HTTPS_PUBLIC_PORT:443}{uri}
 }
 
 admin.db.localhost:443 {
@@ -58,7 +58,7 @@ admin.db.localhost:443 {
 }
 
 admin.db.localhost {
-    redir https://{host}{uri}
+    redir https://admin.db.localhost:{$DC_CADDY_HTTPS_PUBLIC_PORT:443}{uri}
 }
 
 admin.zane-operator.localhost:443 {
@@ -67,5 +67,5 @@ admin.zane-operator.localhost:443 {
 }
 
 admin.zane-operator.localhost {
-    redir https://{host}{uri}
+    redir https://admin.zane-operator.localhost:{$DC_CADDY_HTTPS_PUBLIC_PORT:443}{uri}
 }

libs/analytics/package.json

@@ -35,7 +35,8 @@
   "scripts": {
     "build": "rslib build",
     "dev": "rslib build --watch",
-    "lint": "pnpm -w exec biome lint libs/analytics/src --diagnostic-level=error"
+    "lint": "pnpm -w exec biome lint libs/analytics/src --diagnostic-level=error",
+    "prepack": "pnpm build"
   },
   "devDependencies": {
     "@rsbuild/plugin-react": "^1.4.1",

scripts/apply-postgres-role-bootstrap.sh

@@ -4,6 +4,12 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ENV_FILE="${ROOT_DIR}/.env"
 
+# shellcheck source=scripts/dev/project-env.sh
+. "$ROOT_DIR/scripts/dev/project-env.sh"
+
+PROJECT_NAME="$(new_engine_project_name)"
+export COMPOSE_PROJECT_NAME="$PROJECT_NAME"
+
 get_env_value() {
   local var_name="$1"
   local line
@@ -47,7 +53,7 @@ if ! command -v docker >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ -z "$(docker compose ps -q medusa-db)" ]; then
+if [ -z "$(cd "$ROOT_DIR" && bash ./scripts/dev/compose.sh ps -q medusa-db)" ]; then
   echo "medusa-db container is not running. Start the stack first (for example: mise run dev)." >&2
   exit 1
 fi
@@ -59,7 +65,7 @@ operator_template_db="$(resolved_env_value "DC_ZANE_OPERATOR_DB_TEMPLATE_NAME" "
 echo "Applying postgres role bootstrap (medusa_app/medusa_dev/zane_operator) to running medusa-db container..."
 (
   cd "$ROOT_DIR"
-  docker compose exec -T \
+  bash ./scripts/dev/compose.sh exec -T \
     -e MEDUSA_DB_ZANE_OPERATOR_USER="$operator_user" \
     -e MEDUSA_DB_ZANE_OPERATOR_PASSWORD="$operator_password" \
     -e MEDUSA_DB_ZANE_OPERATOR_DB_TEMPLATE_NAME="$operator_template_db" \
@@ -70,7 +76,7 @@ if [ "${1:-}" = "--verify-idempotent" ]; then
   echo "Running bootstrap second time to verify idempotency..."
   (
     cd "$ROOT_DIR"
-    docker compose exec -T \
+    bash ./scripts/dev/compose.sh exec -T \
       -e MEDUSA_DB_ZANE_OPERATOR_USER="$operator_user" \
       -e MEDUSA_DB_ZANE_OPERATOR_PASSWORD="$operator_password" \
       -e MEDUSA_DB_ZANE_OPERATOR_DB_TEMPLATE_NAME="$operator_template_db" \