Port Management
Centralized port allocation via sbx ports manager — no hardcoded ports, all from registry
Tags
Overview
Purpose
Centralized port allocation via sbx ports manager — no hardcoded ports, all from registry
Rules
PRT-001: All port allocations via sbx ports manager. Source of truth: ports/registry.yml
Centralized registry prevents port conflicts. The registry is scannable by tooling and auditable by humans.
Verification: CLI check: sbx ports list shows all allocated ports. No port in code that isn't in registry.
PRT-002: Frontend/API code must NOT have hardcoded port fallbacks. Require env var, fail if missing.
Fallback ports mask misconfiguration. Failing fast on missing env var surfaces the issue immediately instead of silently using a wrong port.
Verification: Grep for localhost:NNNN in source code. No hardcoded port numbers.
PRT-003: Use {SERVICE}_PORT env var pattern. E.g., SBX_WEB_PORT, SBX_API_PORT.
Consistent naming enables automated port injection and documentation. SERVICE_PORT is discoverable by convention.
Verification: Env var review: port env vars follow SERVICE_PORT pattern.
PRT-004: Before new service code, allocate port: sbx ports allocate <consumer> --range <range>.
Port-first development prevents 'it works on my machine' conflicts. Allocation before code ensures no collisions.
Verification: Process gate: port allocation exists before service implementation begins.
PRT-005: Dockerfiles must use $PORT or ${PORT} in EXPOSE and healthchecks, not hardcoded values.
Hardcoded Docker ports create drift between registry and container configuration. Env vars keep them in sync.
Verification: Dockerfile review: EXPOSE and healthcheck commands use variable substitution.
PRT-006: CORS allowed origins must come from environment (HUB_CORS_ORIGINS), never hardcoded port lists.
Hardcoded CORS origins break when ports change. Environment-driven CORS adapts to any port assignment.
Verification: Code review: CORS configuration reads from env var, not hardcoded list.
PRT-007: PR review must check: no localhost:NNNN literals, all ports from env vars or sbx ports queries.
Port review is a mandatory PR checklist item. Missed hardcoded ports cause production failures.
Verification: PR checklist: port audit performed on every PR touching network code.
PRT-008: External clients: external range. Internal apps: internal range. APIs: services range.
Range discipline prevents accidental overlap between different service tiers and simplifies firewall rules.
Verification: Registry audit: each port is in the correct range for its service tier.