Skip to main content

ADR-017: Ecosystem Hostname Convention

Status​

Accepted

Context​

The PowerSeller ecosystem has multiple projects running locally in Docker during development:

  • PSSaaS — Nginx proxy, Docusaurus, .NET API, React frontend, Redis, Keycloak, RabbitMQ, Mailpit
  • PowerSeller X — Nginx proxy, FastAPI, Next.js, PostgreSQL, Redis, Keycloak, MinIO, Superset, Grafana, Prometheus, Loki, Tempo, MkDocs, OTEL Collector

With both projects running simultaneously, developers face 20+ host port mappings. URLs like localhost:8080, localhost:8181, localhost:3003 carry no semantic meaning and require a reference table to navigate.

Each project already has its own Nginx reverse proxy with path-based routing internally (ADR-016 for PSSaaS). The remaining problem is distinguishing between projects.

Decision​

  1. Adopt the *.powerseller.local namespace for all PowerSeller projects in local development.

  2. Assign each project a unique loopback IP from the 127.0.0.0/8 range:

    ProjectHostnameLoopback IP
    PSSaaSpssaas.powerseller.local127.0.0.1
    PowerSeller Xpsx.powerseller.local127.0.0.2
    MBS Accessmbs.powerseller.local127.0.0.3 (reserved)
    Odooodoo.powerseller.local127.0.0.4 (reserved)

  3. Each project's Nginx proxy binds to port 80 on its assigned IP. This eliminates port numbers from all URLs.

  4. Hostname resolution via hosts file entries. Each developer workstation adds entries to C:\Windows\System32\drivers\etc\hosts:

    # PowerSeller ecosystem local development
    127.0.0.1 pssaas.powerseller.local
    127.0.0.2 psx.powerseller.local

  5. Nginx server_name set to the project's hostname for clear identification in logs and future virtual-host scenarios.

Consequences​

Positive​

  • Self-documenting URLs. http://pssaas.powerseller.local/docs/ is immediately understandable. http://localhost:8080/docs/ is not.
  • No port numbers in URLs. Port 80 is the HTTP default and can be omitted.
  • No port conflicts between projects. Each project owns its loopback IP. Both can bind port 80 simultaneously.
  • Scales to any number of projects. The 127.0.0.0/8 range provides ~16 million addresses.
  • Consistent ecosystem naming. The *.powerseller.local namespace creates a recognizable pattern across all projects.
  • Windows-native. The 127.0.0.0/8 loopback range works natively on Windows without additional configuration. Docker Desktop supports binding to specific loopback IPs.

Negative​

  • One-time manual setup. Each developer must add hosts file entries (requires elevated terminal). This is a one-time step documented in each project's README.
  • .local TLD and mDNS. The .local TLD is technically used by mDNS/Bonjour. On Windows with explicit hosts file entries, this is not a practical issue. If mDNS conflicts arise, .test (IANA-reserved) is the fallback TLD.
  • Non-HTTP protocols unaffected. Direct-access ports for PostgreSQL (5432), Redis (6379), and similar protocols remain as-is since they cannot be proxied by HTTP path.

Neutral​

  • This convention is for local development only. Production deployment uses Azure-managed hostnames and DNS.