portta 0.8.0

package/dist/runtime/docker/compose/compose.yaml

@@ -0,0 +1,214 @@
+# ============================================================================
+# Portta: base stack
+# ============================================================================
+# This file contains ONLY gateway-owned infrastructure. It never references,
+# mounts or manages anything belonging to a consumer project.
+#
+# Do not run this file directly; use the CLI so the right profile overlays and
+# the resolved environment are applied:
+#
+#   ./bin/portta up local
+#
+# docker/compose/compose.yaml alone is intentionally incomplete: it declares no Traefik
+# networks or ports, because exactly one attach-* overlay decides those.
+#
+# Traefik's static configuration lives in `environment:` (TRAEFIK_* variables)
+# rather than a config file. Traefik treats file / CLI / env as mutually
+# exclusive sources, and only the env form composes across Compose overlays.
+# Dynamic configuration stays in config/traefik/dynamic/. See docs/development/adr/0003.
+# ============================================================================
+
+name: ${PORTTA_PROJECT_NAME:-portta}
+
+networks:
+  # Shared, external, created by `bootstrap`. Consumer projects attach their
+  # published HTTP services here. Its lifecycle is independent of this stack.
+  gateway:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}
+
+  # Gateway-private control plane. `internal: true` means no route to the
+  # outside world: the Docker socket proxy is unreachable from anywhere else.
+  control:
+    name: ${PORTTA_CONTROL_NETWORK:-portta-control}
+    internal: true
+    labels:
+      portta.managed: "true"
+      portta.component: control-network
+
+services:
+  # --------------------------------------------------------------------------
+  # Docker socket proxy: read-only, filtered view of the Docker API
+  # --------------------------------------------------------------------------
+  # Traefik needs container discovery, not control. This proxy exposes only the
+  # endpoints the Docker provider actually calls and rejects every write.
+  # It is reachable exclusively from the internal control network.
+  socket-proxy:
+    image: tecnativa/docker-socket-proxy:v0.5.0
+    restart: unless-stopped
+    read_only: true
+    environment:
+      # Endpoints Traefik's Docker provider requires
+      CONTAINERS: "1"
+      NETWORKS: "1"
+      EVENTS: "1"
+      PING: "1"
+      VERSION: "1"
+      # Everything else stays denied
+      POST: "0"
+      ALLOW_RESTARTS: "0"
+      ALLOW_STOP: "0"
+      ALLOW_START: "0"
+      AUTH: "0"
+      BUILD: "0"
+      COMMIT: "0"
+      CONFIGS: "0"
+      DISTRIBUTION: "0"
+      EXEC: "0"
+      IMAGES: "0"
+      INFO: "0"
+      NODES: "0"
+      PLUGINS: "0"
+      SECRETS: "0"
+      SERVICES: "0"
+      SESSION: "0"
+      SWARM: "0"
+      SYSTEM: "0"
+      TASKS: "0"
+      VOLUMES: "0"
+      LOG_LEVEL: warning
+    volumes:
+      # Read-only bind. The proxy is the only component that sees the socket.
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - control
+    # Deliberately no `ports:`: the proxy must never be reachable from the host.
+    # read_only above hardens the container; the entrypoint still needs to
+    # render the generated haproxy.cfg somewhere, hence these tmpfs mounts.
+    tmpfs:
+      - /tmp
+      - /run
+    healthcheck:
+      test: ["CMD", "nc", "-z", "127.0.0.1", "2375"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+    labels:
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: socket-proxy
+
+  # --------------------------------------------------------------------------
+  # Traefik: HTTP/HTTPS edge router
+  # --------------------------------------------------------------------------
+  traefik:
+    image: traefik:v3.7.12
+    restart: unless-stopped
+    depends_on:
+      socket-proxy:
+        condition: service_healthy
+    # No `networks:` and no `ports:` here on purpose. How Traefik is attached to
+    # the world is a per-profile decision made by exactly one overlay:
+    #   docker/compose/attach/host.yaml      : its own namespace, ports on the host
+    #   docker/compose/attach/tailscale.yaml : inside the Tailscale container's
+    #                                  network namespace, reachable over the
+    #                                  tailnet with nothing published
+    # `networks:` and `network_mode:` are mutually exclusive and Compose merges
+    # rather than replaces both, so neither can be declared here and undone later.
+    environment:
+      # -- global ----------------------------------------------------------
+      TRAEFIK_GLOBAL_CHECKNEWVERSION: "false"
+      TRAEFIK_GLOBAL_SENDANONYMOUSUSAGE: "false"
+
+      # -- observability ---------------------------------------------------
+      TRAEFIK_LOG_LEVEL: ${PORTTA_LOG_LEVEL:-INFO}
+      TRAEFIK_ACCESSLOG: ${PORTTA_ACCESS_LOG:-false}
+      TRAEFIK_PING: "true"
+
+      # -- api / dashboard -------------------------------------------------
+      # Off by default. docker/compose/features/dashboard.yaml turns it on, bound
+      # to loopback.
+      TRAEFIK_API: "false"
+
+      # -- entrypoints -----------------------------------------------------
+      TRAEFIK_ENTRYPOINTS_WEB_ADDRESS: ":80"
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_ADDRESS: ":443"
+      # Headers whose names contain characters outside [A-Za-z0-9-] can alias a
+      # canonical header once a backend normalises them (X_Auth_User becoming
+      # X-Auth-User in CGI/WSGI/PHP/nginx), which lets a client spoof headers
+      # Traefik manages. `keep` is Traefik's default and is fine behind
+      # loopback; the public profile raises this to `delete`. Setting it
+      # explicitly also silences Traefik's startup advisory.
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_ALIASHEADERSSTRATEGY: ${PORTTA_ALIAS_HEADERS_STRATEGY:-keep}
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_ALIASHEADERSSTRATEGY: ${PORTTA_ALIAS_HEADERS_STRATEGY:-keep}
+
+      # -- docker provider -------------------------------------------------
+      TRAEFIK_PROVIDERS_DOCKER: "true"
+      TRAEFIK_PROVIDERS_DOCKER_ENDPOINT: tcp://socket-proxy:2375
+      # A service is routed only when it opts in with traefik.enable=true.
+      TRAEFIK_PROVIDERS_DOCKER_EXPOSEDBYDEFAULT: "false"
+      # Consumer containers sit on several networks; always dial them over the
+      # shared gateway network so we never reach into a project's private one.
+      TRAEFIK_PROVIDERS_DOCKER_NETWORK: ${PORTTA_NETWORK:-portta}
+      # Hostnames are derived from the labels Compose already injects, so a
+      # project opts in without repeating its own name. An explicit
+      # `traefik.http.routers.<name>.rule` label always wins.
+      TRAEFIK_PROVIDERS_DOCKER_DEFAULTRULE: >-
+        Host(`{{ if index .Labels "com.docker.compose.project" }}{{ normalize (index .Labels "com.docker.compose.project") }}-{{ normalize (index .Labels "com.docker.compose.service") }}{{ else }}{{ normalize .Name }}{{ end }}.${PORTTA_DOMAIN:-localhost}`)
+
+      # -- file provider (dynamic configuration) ---------------------------
+      TRAEFIK_PROVIDERS_FILE_DIRECTORY: /etc/traefik/dynamic
+      TRAEFIK_PROVIDERS_FILE_WATCH: "true"
+    volumes:
+      - ./config/traefik/dynamic:/etc/traefik/dynamic:ro
+      # Local CA material, when `portta tls init` has been run. Empty
+      # otherwise; git-ignored either way.
+      - ./config/tls:/etc/traefik/tls:ro
+      - ./state/traefik/acme:/etc/traefik/acme
+    healthcheck:
+      test: ["CMD", "traefik", "healthcheck", "--ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+    labels:
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: traefik
+
+  # --------------------------------------------------------------------------
+  # ForwardAuth: browser login and host-scoped sessions
+  # --------------------------------------------------------------------------
+  portta-auth:
+    image: ${PORTTA_AUTH_IMAGE:-ghcr.io/fabioassuncao/portta:${PORTTA_VERSION}}
+    restart: unless-stopped
+    read_only: true
+    # The store it reads is owner-only and belongs to whoever installed Portta,
+    # which on a VPS is root. Hard-coding `node` (uid 1000) meant the service
+    # could not open its own protection store on any Linux host installed as
+    # anybody else -- the same reason the panel takes PORTTA_WEB_USER.
+    user: ${PORTTA_AUTH_USER:-node}
+    command: ["node", "/app/apps/auth/dist/index.js"]
+    environment:
+      PORTTA_AUTH_PORT: "4180"
+      PORTTA_AUTH_STORE: /app/state/auth/protections.json
+      PORTTA_AUTH_SECRET: ${PORTTA_AUTH_SECRET:-}
+      PORTTA_AUTH_UI_DIR: /app/apps/auth/dist/ui
+      PORTTA_AUTH_SESSION_SECONDS: "43200"
+    volumes:
+      - ./state/auth:/app/state/auth:ro
+    networks:
+      - gateway
+    tmpfs:
+      - /tmp
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:4180/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+    labels:
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: auth

package/dist/runtime/docker/compose/features/auth-build.yaml

@@ -0,0 +1,19 @@
+# ============================================================================
+# Portta: build the auth image locally (checkout only)
+# ============================================================================
+# Applied only when PORTTA_WEB_BUILD=true. Development uses auth-dev.yaml;
+# normal local-release and installed runs consume an already-built image.
+#
+# The runtime target is what the long-running service executes.
+# See docs/development/adr/0020-installer-and-portta-home.md.
+# ============================================================================
+
+services:
+  portta-auth:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+      target: runtime
+      args:
+        PORTTA_VERSION: ${PORTTA_VERSION:-}
+    image: ${PORTTA_AUTH_IMAGE:-fabioassuncao/portta:${PORTTA_VERSION}}

package/dist/runtime/docker/compose/features/auth-dev.yaml

@@ -0,0 +1,20 @@
+# =============================================================================
+# Portta ForwardAuth in development mode
+# =============================================================================
+# The dev image supplies Node and dependencies. Source and UI files come from
+# the checkout, so ordinary edits never require another image build.
+# =============================================================================
+
+services:
+  portta-auth:
+    image: fabioassuncao/portta:dev
+    working_dir: /app/apps/auth
+    command: ["npm", "run", "dev"]
+    volumes:
+      - ./apps/auth/src:/app/apps/auth/src:ro
+      - ./apps/auth/ui:/app/apps/auth/ui:ro
+      - ./apps/auth/vite.config.ts:/app/apps/auth/vite.config.ts:ro
+      - ./packages/core/src:/app/packages/core/src:ro
+    tmpfs:
+      - /app/apps/auth/dist
+      - /app/apps/auth/node_modules

package/dist/runtime/docker/compose/features/cloudflare-tunnel.yaml

@@ -0,0 +1,69 @@
+# ============================================================================
+# Portta: Cloudflare Tunnel connector (opt-in)
+# ============================================================================
+# Enabled by CLOUDFLARE_TUNNEL_ENABLED=true, after `portta tunnel setup`.
+#
+# What this buys, and what it does not
+# ------------------------------------
+# It makes the gateway reachable over HTTPS from the internet **without opening
+# a port**. The connector dials Cloudflare outbound, so the host needs no public
+# address, no forwarded 80/443, and nothing on its firewall — which is the only
+# way a home lab or a machine behind CGNAT can publish anything at all.
+#
+# It does not decide what is published. The connector carries one wildcard rule
+# to Traefik, and Traefik still routes only the services that opted in with
+# `traefik.enable=true`. Starting the connector publishes nothing on its own.
+#
+# Why a container, not a systemd unit
+# -----------------------------------
+# Everything else the gateway runs is a container, updated by pulling an image
+# and pinned to a version ([ADR 0004](../../../docs/development/adr/0004-pinned-versions.md)).
+# A connector installed on the host would be the one component with a different
+# lifecycle, a different update path and a different uninstall. An operator who
+# already runs cloudflared under systemd keeps it: Portta detects that connector
+# and leaves this overlay off. See docs/development/adr/0025-cloudflare-tunnel.md.
+# ============================================================================
+
+services:
+  cloudflared:
+    image: ${PORTTA_CLOUDFLARED_IMAGE:-cloudflare/cloudflared:2026.8.3}
+    restart: unless-stopped
+    # `tunnel run` with a config file, rather than a token on the command line:
+    # a token is a credential, and a credential on a command line is visible in
+    # `ps` and in every process listing on the host.
+    command: ["tunnel", "--no-autoupdate", "--config", "/etc/cloudflared/config.yml", "run"]
+    networks:
+      # The shared gateway network, and only that: the connector reaches Traefik
+      # by name and has no route into any project's private network.
+      #
+      # Under the Tailscale attachment Traefik has no name of its own here — it
+      # runs inside the tailscale container's namespace — so the generated
+      # config points at that container instead. `portta tunnel setup` picks the
+      # right origin; see docs/product/guides/cloudflare-tunnel.md.
+      - gateway
+    volumes:
+      # Generated by `portta tunnel setup`; the credentials file beside it is
+      # written 0600 and is the tunnel's private key.
+      - ./state/cloudflared:/etc/cloudflared:ro
+    depends_on:
+      traefik:
+        condition: service_healthy
+    healthcheck:
+      # The connector serves its own metrics; `ready` reports 200 only while it
+      # holds registered connections to the edge, so an unhealthy container here
+      # means the tunnel is genuinely down rather than merely starting.
+      test: ["CMD", "cloudflared", "--metrics", "127.0.0.1:2000", "tunnel", "ready"]
+      interval: 15s
+      timeout: 5s
+      retries: 4
+      start_period: 20s
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    labels:
+      # Never routed by Traefik: the connector is what traffic arrives through,
+      # not something traffic is sent to.
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: cloudflared

package/dist/runtime/docker/compose/features/dashboard-tailscale.yaml

@@ -0,0 +1,21 @@
+# ============================================================================
+# Traefik dashboard overlay for the Tailscale attachment
+# ============================================================================
+# Same as docker/compose/features/dashboard.yaml, but the port is published by the
+# Tailscale container, because Traefik has no network namespace of its own here.
+#
+# Note that the dashboard also becomes reachable over the tailnet at
+# http://<tailscale-hostname>:8080 without being published at all. Restrict it
+# with a Tailscale ACL, or leave PORTTA_DASHBOARD=false.
+# ============================================================================
+
+services:
+  tailscale:
+    ports:
+      - "${PORTTA_DASHBOARD_BIND_ADDRESS:-127.0.0.1}:${PORTTA_DASHBOARD_PORT:-8080}:8080"
+
+  traefik:
+    environment:
+      TRAEFIK_API: "true"
+      TRAEFIK_API_DASHBOARD: "true"
+      TRAEFIK_API_INSECURE: "true"

package/dist/runtime/docker/compose/features/dashboard.yaml

@@ -0,0 +1,21 @@
+# ============================================================================
+# Portta: Traefik dashboard overlay (opt-in, loopback only)
+# ============================================================================
+# Enabled by PORTTA_DASHBOARD=true. The dashboard listens on Traefik's
+# internal entrypoint and is published on a dedicated host port bound to
+# PORTTA_DASHBOARD_BIND_ADDRESS (127.0.0.1 by default).
+#
+# It is never attached to the web/websecure entrypoints, so it can never be
+# reached through the public wildcard domain. See docs/product/concepts/security.md.
+# ============================================================================
+
+services:
+  traefik:
+    ports:
+      - "${PORTTA_DASHBOARD_BIND_ADDRESS:-127.0.0.1}:${PORTTA_DASHBOARD_PORT:-8080}:8080"
+    environment:
+      TRAEFIK_API: "true"
+      TRAEFIK_API_DASHBOARD: "true"
+      # Serves the dashboard on the built-in `traefik` entrypoint (:8080).
+      # Safe only because the published port is loopback-bound above.
+      TRAEFIK_API_INSECURE: "true"

package/dist/runtime/docker/compose/features/db.yaml

@@ -0,0 +1,63 @@
+# ============================================================================
+# Portta: panel persistence (always, with the panel)
+# ============================================================================
+# PostgreSQL is a private implementation detail of the panel, and a required
+# one: the panel refuses to start without it, so this overlay is selected
+# wherever web.yaml is (packages/core/src/config.ts). It has no host port, never
+# joins the shared HTTP network, and keeps its data in a named volume that
+# `portta down` does not remove — only `portta reset` does.
+# ============================================================================
+
+networks:
+  webdata:
+    name: ${PORTTA_DB_NETWORK:-portta-data}
+    internal: true
+    labels:
+      portta.managed: "true"
+      portta.component: data-network
+
+volumes:
+  portta-db:
+    name: ${PORTTA_DB_VOLUME:-portta-db}
+    labels:
+      portta.managed: "true"
+      portta.component: db-volume
+
+services:
+  db:
+    image: postgres:18.6-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${PORTTA_RUNTIME_DB_NAME:-portta}
+      POSTGRES_USER: ${PORTTA_RUNTIME_DB_USER:-portta}
+      # An empty value makes PostgreSQL refuse to initialise; it never makes it
+      # trust unauthenticated clients. bootstrap/web up normally fill this.
+      POSTGRES_PASSWORD: ${PORTTA_RUNTIME_DB_PASSWORD:-}
+    volumes:
+      # PostgreSQL 18+ stores data in a major-version subdirectory. Mount the
+      # parent so upgrades fail explicitly instead of creating nested data.
+      - portta-db:/var/lib/postgresql
+    networks:
+      - webdata
+    healthcheck:
+      test: ["CMD-SHELL", 'pg_isready -h 127.0.0.1 -p 5432 -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"']
+      interval: 5s
+      timeout: 3s
+      retries: 12
+      start_period: 5s
+    labels:
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: db
+    # No `ports:`. Only the panel can reach this service.
+
+  web:
+    environment:
+      PORTTA_DB_NETWORK: ${PORTTA_DB_NETWORK:-portta-data}
+    networks:
+      - webdata
+    # The panel exits if Postgres is not accepting connections yet. Compose
+    # merges this with the socket-proxy wait in web.yaml.
+    depends_on:
+      db:
+        condition: service_healthy

package/dist/runtime/docker/compose/features/panel-domain.yaml

@@ -0,0 +1,42 @@
+# ============================================================================
+# Portta: the panel on the domain, over HTTPS, behind Portta ForwardAuth
+# ============================================================================
+# Applied when PORTTA_WEB_EXPOSE=domain. The panel answers on one hostname of
+# the gateway's own domain, on the entrypoint every application uses, with the
+# certificate that entrypoint already terminates.
+#
+# Why this is allowed on a public profile when `vpn` is not
+# ---------------------------------------------------------
+# `web-vpn.yaml` is refused on remote-public because it would publish a VPN
+# hostname on every interface. The `public` mode publishes the panel on
+# 0.0.0.0, and what stands in front of it is the panel itself -- accounts,
+# roles, sessions, a second factor and a rate limiter, all of them its own
+# (docs/development/adr/0035-authentication-lives-in-the-panel.md).
+#
+# So the remaining difference between `public` and this is not exposure. It is
+# which entrypoint carries the panel, and what that costs:
+#
+#   `public`  keeps the panel on its own entrypoint, so it needs no hostname
+#             and works on a bare IP -- but that entrypoint terminates no TLS,
+#             so the password crosses the network in clear text.
+#   `domain`  puts the panel on websecure, where it gets a real certificate and
+#             the same HTTPS every application gets. It needs a hostname, and
+#             it gives up the property that the panel's entrypoint carries
+#             nothing else. It carries no application the router does not name.
+#
+# The router names exactly one host, so publishing the panel still publishes no
+# application: an application is reachable only through a router of its own.
+#
+# There is no middleware: the panel signs people in itself, and `portta web up
+# --expose domain` refuses unless PORTTA_AUTH_MODE=required and TLS is on.
+# See docs/development/adr/0035-authentication-lives-in-the-panel.md.
+# ============================================================================
+
+services:
+  web:
+    labels:
+      # Overrides the `false` in web.yaml: a later overlay wins for map labels.
+      traefik.enable: "true"
+      traefik.http.routers.portta-panel.rule: >-
+        Host(`${PORTTA_PANEL_ADVERTISED_HOST:-portta-web}`)
+      traefik.http.services.portta-panel.loadbalancer.server.port: "8081"

package/dist/runtime/docker/compose/features/panel-public.yaml

@@ -0,0 +1,47 @@
+# ============================================================================
+# Portta: the panel on a public address, behind Portta ForwardAuth
+# ============================================================================
+# Applied when PORTTA_WEB_EXPOSE=public. This is the mode the installer offers
+# first, because it is the shortest path to a usable development VPS.
+#
+# Two properties make it safe enough to be the default, and both are load
+# bearing:
+#
+#   1. The panel gets its OWN Traefik entrypoint (`panel`, :8090 inside the
+#      container). It is never attached to web/websecure, so publishing the
+#      panel does not publish a single application, and an application that
+#      opts into Traefik is not reachable on this port. Panel access and
+#      application exposure stay separate decisions.
+#
+#   2. The panel signs people in itself. There is no middleware on this
+#      router: `PORTTA_AUTH_MODE=required` is what stands in front of it, the
+#      panel's own process refuses to start in `disabled` mode on anything but
+#      loopback, and `portta web up --expose public` refuses before that.
+#      See docs/development/adr/0035-authentication-lives-in-the-panel.md.
+#
+# The panel container itself publishes no host port here (web-bind.yaml is not
+# applied), so the only way in is through this entrypoint.
+#
+# HTTP, not HTTPS, when the address is a bare IP: there is no certificate a
+# public CA will issue for one. The password is checked by the panel but the
+# connection is not encrypted, and the installer says so in as many words.
+# `--expose domain` is the mode that gets a real certificate.
+# ============================================================================
+
+services:
+  traefik:
+    ports:
+      # 0.0.0.0 by default: `public` means public, and the installer states it.
+      - "${PORTTA_WEB_BIND_ADDRESS:-0.0.0.0}:${PORTTA_WEB_PORT:-8081}:8090"
+    environment:
+      TRAEFIK_ENTRYPOINTS_PANEL_ADDRESS: ":8090"
+
+  web:
+    labels:
+      # Overrides the `false` in web.yaml: a later overlay wins for map labels.
+      traefik.enable: "true"
+      # A bare IP has no hostname to match on, so the rule is the path. The
+      # entrypoint is what scopes it: nothing else answers on :8090.
+      traefik.http.routers.portta-panel.rule: PathPrefix(`/`)
+      traefik.http.routers.portta-panel.entrypoints: panel
+      traefik.http.services.portta-panel.loadbalancer.server.port: "8081"

package/dist/runtime/docker/compose/features/panel-webhook.yaml

@@ -0,0 +1,46 @@
+# ============================================================================
+# Portta: the one panel path that authenticates itself
+# ============================================================================
+# Applied when GITHUB_APP_ENABLED=true and the panel is routed on a domain.
+#
+# The problem
+# -----------
+# A GitHub App delivers webhooks to a URL of yours. Every panel path sits
+# behind ForwardAuth, which expects a session cookie or a Basic credential --
+# GitHub sends neither, so a delivery is refused before the panel ever sees it.
+# The panel cannot be told about a push, an issue, or a new installation.
+#
+# Why an exemption is safe here, and only here
+# --------------------------------------------
+# This is not a hole in the panel's authentication. It is one path that carries
+# a *different* and, for a machine-to-machine callback, stronger one: GitHub
+# signs the raw body with HMAC-SHA256 under a secret only it and this host
+# know, and `verifySignature` compares in constant time, refusing a missing
+# secret, a missing header and a wrong digest alike. Nothing is parsed before
+# that check passes.
+#
+# So the request is authenticated, just not by a cookie. A session cookie would
+# be the wrong instrument: GitHub has no session, and any scheme that let it in
+# by origin or by address would trust something forgeable.
+#
+# What this deliberately is not
+# -----------------------------
+# It is not a general "these URLs are public" list. Every other panel path
+# authenticates by session and by nothing else, so exempting one would be an
+# unauthenticated door into an API that can start, stop and remove containers.
+# This router names one exact path with `Path(...)`, not a prefix -- there is
+# no `/api/integrations/github/webhook/../projects` to walk out of.
+#
+# The priority is above the panel's own router so the exact path wins over
+# `Host(...)`; both name the same service, so the panel process is unchanged.
+# ============================================================================
+
+services:
+  web:
+    labels:
+      traefik.enable: "true"
+      traefik.http.routers.portta-panel-webhook.rule: >-
+        Host(`${PORTTA_PANEL_ADVERTISED_HOST:-portta-web}`) && Path(`/api/integrations/github/webhook`)
+      traefik.http.routers.portta-panel-webhook.priority: "20000"
+      traefik.http.routers.portta-panel-webhook.service: portta-panel
+      traefik.http.services.portta-panel.loadbalancer.server.port: "8081"

package/dist/runtime/docker/compose/features/tcp-tailscale.yaml

@@ -0,0 +1,30 @@
+# ============================================================================
+# TCP entrypoints for the Tailscale attachment
+# ============================================================================
+# Same as docker/compose/features/tcp.yaml, but the ports and the access network belong
+# to the Tailscale container: Traefik shares its network namespace and has
+# neither of its own (see docs/development/adr/0007-tailscale-sidecar.md).
+#
+# The published ports exist so the VPS itself can reach a database for
+# debugging. What matters is that the entrypoints listen on the tailnet
+# address, so `storefront-postgres.vpn.example.com:5432` works from any machine
+# on your tailnet and from nowhere else.
+# ============================================================================
+
+networks:
+  access:
+    external: true
+    name: ${PORTTA_ACCESS_NETWORK:-portta-access}
+
+services:
+  tailscale:
+    networks:
+      - access
+    ports:
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_TCP_POSTGRES_PORT:-5432}:5432"
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_TCP_REDIS_PORT:-6379}:6379"
+
+  traefik:
+    environment:
+      TRAEFIK_ENTRYPOINTS_POSTGRES_ADDRESS: ":5432"
+      TRAEFIK_ENTRYPOINTS_REDIS_ADDRESS: ":6379"

package/dist/runtime/docker/compose/features/tcp.yaml

@@ -0,0 +1,40 @@
+# ============================================================================
+# Portta: TCP entrypoints, so databases are told apart by hostname
+# ============================================================================
+# Enabled by PORTTA_TCP=true. Off by default.
+#
+# One host port per protocol, however many instances are running behind it.
+# Traefik picks the backend from the TLS Server Name Indication, so two
+# projects can both run PostgreSQL on 5432 inside their own containers and
+# neither has to publish a port or renumber anything:
+#
+#   storefront-postgres.localhost:5432  ->  storefront's postgres:5432
+#   checkout-postgres.localhost:5432    ->  checkout's postgres:5432
+#
+# Only services that opt in are routed: `exposedByDefault` stays false, and a
+# datastore additionally has to join the access network. Nothing here publishes
+# a database by itself. See docs/product/guides/tcp-routing.md.
+#
+# This overlay is for the `host` attachment. docker/compose/features/tcp-tailscale.yaml
+# is the same thing for the Tailscale attachment, where the ports belong to the
+# Tailscale container because Traefik has no namespace of its own.
+# ============================================================================
+
+networks:
+  # Created by the CLI before Compose runs, the same way the shared network is.
+  # Datastores that opt into hostname routing join THIS network, never the
+  # shared HTTP one: Compose validation and routing tests keep that true.
+  access:
+    external: true
+    name: ${PORTTA_ACCESS_NETWORK:-portta-access}
+
+services:
+  traefik:
+    networks:
+      - access
+    ports:
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_TCP_POSTGRES_PORT:-5432}:5432"
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_TCP_REDIS_PORT:-6379}:6379"
+    environment:
+      TRAEFIK_ENTRYPOINTS_POSTGRES_ADDRESS: ":5432"
+      TRAEFIK_ENTRYPOINTS_REDIS_ADDRESS: ":6379"

package/dist/runtime/docker/compose/features/web-bind.yaml

@@ -0,0 +1,19 @@
+# ============================================================================
+# Portta: publish the panel on a host interface
+# ============================================================================
+# Applied for every panel access mode except `public`:
+#
+#   local      127.0.0.1        this machine, or an SSH tunnel
+#   tailscale  100.x.y.z        the tailnet only, nothing on the public NIC
+#   vpn        127.0.0.1        loopback, plus the router in web-vpn.yaml
+#
+# PORTTA_WEB_BIND_ADDRESS is the whole decision, and the installer and
+# `portta config set panel.access` are the two places that set it. The `public`
+# mode never applies this overlay: there the port belongs to Traefik, so a
+# request cannot reach the panel without passing Portta ForwardAuth first.
+# ============================================================================
+
+services:
+  web:
+    ports:
+      - "${PORTTA_WEB_BIND_ADDRESS:-127.0.0.1}:${PORTTA_WEB_PORT:-8081}:8081"