Proxy: one project URL

Add a top-level proxy: block to put every service behind a single URL. Portler starts a local reverse proxy on a Portler-assigned port and prints one project URL — which also removes CORS pain, because the browser only ever talks to one origin.

proxy:
  port: auto
  routes:
    /api: backend
    /: frontend

$ portler up
SERVICE   PORT   URL
...
[portler] project url: http://localhost:52000

Requests to http://localhost:52000/api/... go to backend; everything else goes to frontend.

How routing works

• The longest matching prefix wins, and matching respects path segment boundaries: /api matches /api and /api/users, but not /apifoo.
• The prefix is not stripped before forwarding, like most dev proxies: a request for /api/users reaches the backend as /api/users. Mount your routes under the same path the proxy uses.
• Routes can target local and Docker services alike — the proxy forwards to their assigned localhost ports. A route must target a service that declares a port.

Port

• port: auto (or omitting port) lets Portler pick a free port.
• A fixed number like port: 8080 is preferred when free — like a service's declared port, it is not a hard requirement.

Headers and WebSockets

• The Host header is preserved, and X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host are set.
• WebSocket upgrades are proxied transparently, so dev-server HMR works through the project URL.
• When a routed service is down, the proxy answers 502 Bad Gateway with a message naming the service.

Lifecycle

The proxy follows the project lifecycle:

• portler up starts it (also with --detach),
• portler down stops it,
• portler down proxy stops just the proxy.

It shows up as proxy in portler ports and portler ps.

Referencing the proxy

The proxy's address is available to services as PORTLER_PROXY_URL / PORTLER_PROXY_PORT, or via references like proxy.url:

services:
  backend:
    command: npm run dev
    port: 4000
    port_env: PORT
    env:
      PUBLIC_ORIGIN: proxy.url

WARNING

With a proxy: block present, proxy is a reserved name and cannot be used as a service name.