Customizable ports (#962)

## High-level PR Summary This PR changes the default development ports for several background services to avoid conflicts. PostgreSQL moves from port `5432` to `8128`, Inbucket SMTP from `2500` to `8129`, Inbucket POP3 from `1100` to `8130`, and the OpenTelemetry collector from `4318` to `8131`. All references across configuration files, Docker Compose setups, environment files, CI/CD workflows, test files, and documentation have been updated to reflect these new port assignments. A knowledge base document has been added to document the new port mappings. ⏱️ Estimated Review Time: 15-30 minutes <details> <summary>💡 Review Order Suggestion</summary> | Order | File Path | | --- | --- | | 1 | `claude/CLAUDE-KNOWLEDGE.md` | | 2 | `apps/dev-launchpad/public/index.html` | | 3 | `docker/dependencies/docker.compose.yaml` | | 4 | `docker/emulator/docker.compose.yaml` | | 5 | `apps/backend/.env` | | 6 | `apps/backend/.env.development` | | 7 | `docker/server/.env.example` | | 8 | `package.json` | | 9 | `.devcontainer/devcontainer.json` | | 10 | `apps/e2e/.env.development` | | 11 | `.github/workflows/check-prisma-migrations.yaml` | | 12 | `.github/workflows/docker-server-test.yaml` | | 13 | `.github/workflows/e2e-api-tests.yaml` | | 14 | `.github/workflows/e2e-source-of-truth-api-tests.yaml` | | 15 | `.github/workflows/restart-dev-and-test.yaml` | | 16 | `apps/e2e/tests/backend/endpoints/api/v1/internal/email-drafts.test.ts` | | 17 | `apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts` | | 18 | `apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts` | | 19 | `apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts` | | 20 | `apps/e2e/tests/backend/workflows.test.ts` | | 21 | `docs/templates/others/self-host.mdx` | </details> [![Need help? Join our Discord](https://img.shields.io/badge/Need%20help%3F%20Join%20our%20Discord-5865F2?style=plastic&logo=discord&logoColor=white)](https://discord.gg/n3SsVDAW6U) [![Analyze latest changes](https://img.shields.io/badge/Analyze%20latest%20changes-238636?style=plastic)](https://squash-322339097191.europe-west3.run.app/interactive/21c3d5c36237cfa8aa584be4a22457c7e4e393688dd800b78799b3ef730fd693/?repo_owner=stack-auth&repo_name=stack-auth&pr_number=962)   ---- > [!IMPORTANT] > This PR introduces customizable development ports using `NEXT_PUBLIC_STACK_PORT_PREFIX`, updating configurations, documentation, and tests accordingly. > > - **Behavior**: > - Default development ports for services are now customizable via `NEXT_PUBLIC_STACK_PORT_PREFIX`. > - PostgreSQL port changed from `5432` to `${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28`. > - Inbucket SMTP port changed from `2500` to `${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}29`. > - Inbucket POP3 port changed from `1100` to `${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}30`. > - OpenTelemetry collector port changed from `4318` to `${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}31`. > - **Configuration**: > - Updated `docker.compose.yaml` to use new port variables for services like PostgreSQL, Inbucket, and OpenTelemetry. > - Environment files in `apps/backend`, `apps/dashboard`, and `apps/e2e` updated to use `NEXT_PUBLIC_STACK_PORT_PREFIX`. > - `package.json` scripts updated to reflect new port configurations. > - **Documentation**: > - Added `CLAUDE-KNOWLEDGE.md` to document new port mappings. > - Updated `self-host.mdx` to reflect new port configurations. > - **Testing**: > - Updated test files in `apps/e2e/tests` to use new port configurations. > - Added `helpers/ports.ts` for port-related utilities in tests. > > <sup>This description was created by </sup>[<img alt="Ellipsis" src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup> for 76ef55f58f. You can [customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this summary. It will automatically update as commits are pushed.</sup> ----   ## Summary by CodeRabbit - **New Features** - Enable configurable development ports via a NEXT_PUBLIC_STACK_PORT_PREFIX, allowing parallel local environments with custom port prefixes. - **Bug Fixes** - Updated local service port mappings and CI/workflow settings so tooling and tests use the new prefixed ports consistently. - **Documentation** - Added docs and contributor guidance for running multiple parallel workspaces with custom port prefixes.  --------- Co-authored-by: N2D4 <[email protected]>
2026-07-20 21:29:36 +08:00 · 2025-10-20 15:24:47 -07:00
parent 861fe439d1
commit 3d4c608187
94 changed files with 676 additions and 300 deletions
@@ -10,7 +10,7 @@ services:
      POSTGRES_DB: stackframe
      POSTGRES_DELAY_MS: ${POSTGRES_DELAY_MS:-0}
    ports:
-      - 5432:5432
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    cap_add:
@@ -23,7 +23,7 @@ services:
    environment:
      DATABASE_URL: postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@db:5432/stackframe
    ports:
-      - 8116:8080
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}16:8080"

  # ================= PgAdmin =================

@@ -38,7 +38,7 @@ services:
      - source: pgadmin_servers
        target: /pgadmin4/servers.json
    ports:
-      - 8117:80
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}17:80"

  # ================= Supabase Studio =================

@@ -65,7 +65,7 @@ services:
      NEXT_PUBLIC_ENABLE_LOGS: true
      NEXT_ANALYTICS_BACKEND_PROVIDER: postgres
    ports:
-      - 8118:3000
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}18:3000"
  
  supabase-meta:
    image: supabase/postgres-meta:v0.84.2
@@ -73,7 +73,7 @@ services:
    environment:
      PG_META_PORT: 8080
      PG_META_DB_HOST: db
-      PG_META_DB_PORT: 5432
+      PG_META_DB_PORT: 8128
      PG_META_DB_NAME: stackframe
      PG_META_DB_USER: postgres
      PG_META_DB_PASSWORD: PASSWORD-PLACEHOLDER--uqfEC1hmmv
@@ -84,9 +84,9 @@ services:
  inbucket:
    image: inbucket/inbucket:3.1.0
    ports:
-      - 2500:2500
-      - 8105:9000
-      - 1100:1100
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}29:2500"
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}05:9000"
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}30:1100"
    volumes:
      - inbucket-data:/data

@@ -97,8 +97,8 @@ services:
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
-      - 8107:16686  # Jaeger UI
-      - 4318:4318    # OTLP Endpoint
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}07:16686"  # Jaeger UI
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}31:4318"    # OTLP Endpoint
    restart: always

  # ================= svix =================
@@ -129,7 +129,7 @@ services:
      SVIX_LOG_LEVEL: trace
      SVIX_QUEUE_TYPE: redis
    ports:
-      - 8113:8071
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}13:8071"
    depends_on:
    - svix-redis
    - svix-db
@@ -139,7 +139,7 @@ services:
  s3mock:
    image: adobe/s3mock:latest
    ports:
-      - 8121:9090
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}21:9090"
    environment:
      - initialBuckets=stack-storage
      - root=s3mockroot
@@ -157,8 +157,8 @@ services:
  localstack:
    image: localstack/localstack:4.7
    ports:
-      - "8124:4566"            # LocalStack Gateway
-      - "8150-8199:4510-4559"  # external services port range
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}24:4566"            # LocalStack Gateway
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}50-${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}99:4510-4559"  # external services port range
    environment:
      # LocalStack configuration: https://docs.localstack.cloud/references/configuration/
      - DEBUG=${DEBUG:-0}
@@ -173,9 +173,8 @@ services:
      context: ./freestyle-mock
      dockerfile: Dockerfile
    image: freestyle-mock
-    container_name: freestyle-mock
    ports:
-      - "8122:8080"       # POST http://localhost:8119/execute/v1/script
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}22:8080"       # POST http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}19/execute/v1/script
    extra_hosts:
      - "host.docker.internal:host-gateway"  # noop on Docker Desktop/Orbstack, enables host.docker.internal on Linux
    environment:
@@ -189,7 +188,7 @@ services:
  stripe-mock:
    image: stripe/stripe-mock:v0.195.0
    ports:
-      - 8123:12111
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}23:12111"
    environment:
      - STRIPE_API_KEY=sk_test_1234567890

@@ -198,7 +197,7 @@ services:
  qstash:
    image: public.ecr.aws/upstash/qstash:latest
    ports:
-      - 8125:8080
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}25:8080"
    command: qstash dev
    extra_hosts:
      - "host.docker.internal:host-gateway"  # noop on Docker Desktop/Orbstack, enables host.docker.internal on Linux
@@ -210,9 +209,9 @@ services:
  mcpjam-inspector:
    image: node:20-alpine
    ports:
-      - "8126:3001"
+      - "${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}26:3001"
    command: >
-      sh -c "echo '{\"mcpServers\":{\"local-stack-auth-docs\":{\"url\":\"http://host.docker.internal:8104/api/internal/mcp\"}}}' > /app/mcp.json && npx -y @mcpjam/inspector@latest --port 3001 --config /app/mcp.json"
+      sh -c "echo '{\"mcpServers\":{\"local-stack-auth-docs\":{\"url\":\"http://host.docker.internal:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}04/api/internal/mcp\"}}}' > /app/mcp.json && npx -y @mcpjam/inspector@latest --port 3001 --config /app/mcp.json"
    working_dir: /app
    volumes:
      - mcpjam-inspector-data:/root
@@ -81,6 +81,7 @@ services:

  db:
    image: postgres:15
+    command: ["postgres", "-c"]
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: PASSWORD-PLACEHOLDER--uqfEC1hmmv
@@ -88,7 +89,7 @@ services:
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
-      test: ["CMD-SHELL", "pg_isready", "-d", "stackframe"]
+      test: ["CMD-SHELL", "pg_isready -p 5432 -d stackframe"]
      interval: 5s
      timeout: 10s
      retries: 5
@@ -97,6 +98,9 @@ services:
  # ================= Inbucket =================
  inbucket:
    image: inbucket/inbucket:latest
+    environment:
+      INBUCKET_SMTP_ADDR: ":2500"
+      INBUCKET_POP3_ADDR: ":1100"
    ports:
      - 32203:9000
    volumes:
@@ -177,4 +181,3 @@ volumes:
  svix-postgres-data:
  s3mock-data:
  deno-cache:
-
@@ -3,8 +3,8 @@
 NEXT_PUBLIC_STACK_API_URL=http://localhost:8102
 NEXT_PUBLIC_STACK_DASHBOARD_URL=http://localhost:8101

-STACK_DATABASE_CONNECTION_STRING=postgres://postgres:[email protected]:5432/stackframe
-STACK_DIRECT_DATABASE_CONNECTION_STRING=postgres://postgres:[email protected]:5432/stackframe
+STACK_DATABASE_CONNECTION_STRING=postgres://postgres:[email protected]:8128/stackframe
+STACK_DIRECT_DATABASE_CONNECTION_STRING=postgres://postgres:[email protected]:8128/stackframe

 STACK_SERVER_SECRET=23-wuNpik0gIW4mruTz25rbIvhuuvZFrLOLtL7J4tyo

@@ -21,9 +21,13 @@ export STACK_SECRET_SERVER_KEY=${STACK_SEED_INTERNAL_PROJECT_SECRET_SERVER_KEY}
 export STACK_SUPER_SECRET_ADMIN_KEY=${STACK_SEED_INTERNAL_PROJECT_SUPER_SECRET_ADMIN_KEY}

 export NEXT_PUBLIC_BROWSER_STACK_DASHBOARD_URL=${NEXT_PUBLIC_STACK_DASHBOARD_URL}
-export NEXT_PUBLIC_SERVER_STACK_DASHBOARD_URL="http://localhost:8101"
+export NEXT_PUBLIC_STACK_PORT_PREFIX=${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}
+PORT_PREFIX=${NEXT_PUBLIC_STACK_PORT_PREFIX}
+export NEXT_PUBLIC_SERVER_STACK_DASHBOARD_URL="http://localhost:${PORT_PREFIX}01"
 export NEXT_PUBLIC_BROWSER_STACK_API_URL=${NEXT_PUBLIC_STACK_API_URL}
-export NEXT_PUBLIC_SERVER_STACK_API_URL="http://localhost:8102"
+export NEXT_PUBLIC_SERVER_STACK_API_URL="http://localhost:${PORT_PREFIX}02"
+export BACKEND_PORT=${BACKEND_PORT:-${PORT_PREFIX}02}
+export DASHBOARD_PORT=${DASHBOARD_PORT:-${PORT_PREFIX}01}

 export USE_INLINE_ENV_VARS=true