portta 0.8.0

package/dist/runtime/scripts/lib/runner-exec.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# The command the project runner container is created with. Fixed at creation;
+# the panel supplies no argument. The request is { verb, project, flags } in
+# state/runner/request.json, plus { workingDir, configFiles } for an `up` of a
+# project that has no container left. See docs/development/adr/0030-the-panel-and-a-project-lifecycle.md.
+set -euo pipefail
+
+PORTTA_ROOT="${PORTTA_ROOT:?PORTTA_ROOT is required}"
+REQUEST="$PORTTA_ROOT/state/runner/request.json"
+HOST_ROOT=/host
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+
+[ -f "$REQUEST" ] || die "no runner request at $REQUEST"
+
+# Closed fields, closed values. A full JSON parser is not needed and would be a
+# dependency this image does not have. The panel refuses a path carrying a
+# comma, a quote or a backslash before it writes the request, which is what
+# lets the list be read as text between the brackets.
+verb=$(sed -n 's/.*"verb"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$REQUEST" | head -n1)
+project=$(sed -n 's/.*"project"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$REQUEST" | head -n1)
+nocache=$(grep -q '"no-cache"' "$REQUEST" && printf '1' || printf '0')
+directory=$(grep -q '"directory"' "$REQUEST" && printf '1' || printf '0')
+request_working_dir=$(sed -n 's/.*"workingDir"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$REQUEST" | head -n1)
+request_config_files=$(sed -n 's/.*"configFiles"[[:space:]]*:[[:space:]]*\[\([^]]*\)\].*/\1/p' "$REQUEST" | head -n1 | tr -d '"')
+
+case "$verb" in
+  up|stop|restart|build|down|down-volumes) ;;
+  *) die "unknown runner verb '$verb'" ;;
+esac
+
+[[ "$project" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*$ ]] || die "refusing project name '$project'"
+
+# The bound a path from the request must satisfy, the same one
+# packages/core/src/runner.ts checks before writing it: absolute, no walk-up,
+# not `/`, not a top-level directory.
+assert_request_path() {
+  local path="$1" what="$2"
+  [[ "$path" == /* ]] || die "$what is not absolute"
+  [[ "$path" != *..* ]] || die "refusing $what that walks up"
+  [[ "$path" != "/" ]] || die "refusing / as $what"
+  case "${path#/}" in
+    */*) ;;
+    *) die "refusing a top-level directory as $what" ;;
+  esac
+}
+
+# With no container left there is no managed label to protect Portta itself.
+# Refuse both its root and descendants: a remembered request must never run a
+# consumer Compose file from the gateway checkout.
+assert_not_portta_path() {
+  local path="$1" what="$2"
+  case "$path" in
+    "$PORTTA_ROOT"|"$PORTTA_ROOT"/*) die "refusing Portta's own directory as $what" ;;
+  esac
+}
+
+id=$(docker ps -aq --filter "label=com.docker.compose.project=${project}" | head -n1)
+if [ -n "$id" ]; then
+  # A container exists: its labels are the truth, whatever the request says.
+  managed=$(docker inspect "$id" --format '{{ index .Config.Labels "portta.managed" }}' 2>/dev/null || true)
+  [ "$managed" != "true" ] || die "refusing to operate Portta's own project"
+  working_dir=$(docker inspect "$id" --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}')
+  config_files=$(docker inspect "$id" --format '{{ index .Config.Labels "com.docker.compose.project.config_files" }}')
+else
+  # Nothing left to read labels from: only `up` makes sense, and only with the
+  # paths the panel remembered. Portta's own project is refused by name and by
+  # directory, since no label can say so here.
+  [ "$verb" = "up" ] || die "no container on this host belongs to project '$project'"
+  [ -n "$request_working_dir" ] || die "no container on this host belongs to project '$project', and the request names no working directory"
+  own_name=$(sed -n 's/^PORTTA_PROJECT_NAME=//p' "$PORTTA_ROOT/.env" 2>/dev/null | head -n1)
+  own_name="${own_name%\"}"; own_name="${own_name#\"}"; own_name="${own_name%\'}"; own_name="${own_name#\'}"
+  own_name="${own_name:-portta}"
+  [ "$project" != "$own_name" ] || die "refusing to operate Portta's own project"
+  assert_request_path "$request_working_dir" "working directory"
+  assert_not_portta_path "$request_working_dir" "a working directory"
+  working_dir="$request_working_dir"
+  config_files="$request_config_files"
+fi
+
+[ -n "$working_dir" ] || die "project '$project' has no Compose working directory label"
+[ -d "${HOST_ROOT}${working_dir}" ] || die "working directory ${working_dir} does not exist on this host"
+
+# Compose sees the host filesystem at the host's own paths, so `include:` and
+# every relative path in a Compose file resolve exactly as they do on the host.
+# The first ancestor of a path that does not exist in this container becomes a
+# symlink into /host; the repository root is already mounted at its own path.
+link_host_path() {
+  local target="$1" partial="" rest segment
+  case "$target" in
+    "$PORTTA_ROOT"|"$PORTTA_ROOT"/*) return 0 ;;
+  esac
+  rest="${target#/}"
+  while [ -n "$rest" ]; do
+    segment="${rest%%/*}"
+    if [ "$segment" = "$rest" ]; then rest=""; else rest="${rest#*/}"; fi
+    partial="$partial/$segment"
+    if [ -L "$partial" ]; then
+      [ "$(realpath "$partial")" = "$(realpath "${HOST_ROOT}${partial}")" ] || die "${partial} in the runner does not point at the host's ${partial}; recreate the runner with portta up"
+      return 0
+    fi
+    if [ ! -e "$partial" ]; then
+      ln -s "${HOST_ROOT}${partial}" "$partial"
+      return 0
+    fi
+  done
+  [ "$(realpath "$target")" = "$(realpath "${HOST_ROOT}${target}")" ] || die "${target} exists inside the runner image and is not the host's ${target}"
+}
+
+link_host_path "$working_dir"
+
+# Compose files as the daemon recorded them, or as the panel remembered them.
+# Readability is checked through /host; the path handed to Compose is the
+# host's, like --project-directory, so bind mounts resolve on the host.
+files=()
+if [ -n "$config_files" ]; then
+  IFS=',' read -r -a listed <<< "$config_files"
+  for file in "${listed[@]}"; do
+    file="${file#"${file%%[![:space:]]*}"}"
+    file="${file%"${file##*[![:space:]]}"}"
+    [ -n "$file" ] || continue
+    [ -z "$id" ] && assert_request_path "$file" "compose file"
+    [ -n "$id" ] || assert_not_portta_path "$file" "a compose file"
+    [ -f "${HOST_ROOT}${file}" ] || die "compose file ${file} is not readable"
+    case "$file" in
+      "$working_dir"/*) ;;
+      *) link_host_path "${file%/*}" ;;
+    esac
+    files+=(-f "$file")
+  done
+fi
+if [ ${#files[@]} -eq 0 ]; then
+  for name in compose.yaml compose.yml docker-compose.yaml docker-compose.yml; do
+    if [ -f "${HOST_ROOT}${working_dir}/${name}" ]; then
+      files+=(-f "${working_dir}/${name}")
+      break
+    fi
+  done
+fi
+[ ${#files[@]} -gt 0 ] || die "no compose file in ${working_dir}"
+
+compose() {
+  docker compose --project-name "$project" --project-directory "$working_dir" "${files[@]}" "$@"
+}
+
+# The working directory is Docker's label. Removal is the same bound as
+# packages/core/src/paths.ts: absolute, no walk-up, not `/`, not a top-level
+# directory. `realpath` is the last check so a symlink cannot leave /host.
+remove_working_dir() {
+  local dir="$1"
+  [[ "$dir" == /* ]] || die "working directory is not absolute"
+  [[ "$dir" != *..* ]] || die "refusing working directory that walks up"
+  [[ "$dir" != "/" ]] || die "refusing to remove /"
+  case "${dir#/}" in
+    */*) ;;
+    *) die "refusing to remove a top-level directory" ;;
+  esac
+  local target="${HOST_ROOT}${dir}"
+  [ -d "$target" ] || die "working directory ${dir} does not exist on this host"
+  local real
+  real=$(realpath "$target")
+  case "$real" in
+    /host/*) ;;
+    *) die "resolved path is outside /host" ;;
+  esac
+  [ "$real" != "/host" ] && [ "$real" != "/" ] || die "refusing to remove the host root"
+  rm -rf -- "$real"
+}
+
+case "$verb" in
+  up) compose up -d --remove-orphans ;;
+  stop) compose stop ;;
+  restart) compose stop && compose up -d --remove-orphans ;;
+  build)
+    if [ "$nocache" = "1" ]; then
+      compose build --no-cache
+    else
+      compose build
+    fi
+    compose up -d --remove-orphans
+    ;;
+  down) compose down ;;
+  down-volumes)
+    compose down --volumes
+    if [ "$directory" = "1" ]; then
+      remove_working_dir "$working_dir"
+    fi
+    ;;
+esac

package/dist/runtime/templates/README.md

@@ -0,0 +1,43 @@
+# Templates
+
+Reference overlays for the shapes a project usually has. They are **references
+to copy from**, not runtime that projects depend on: nothing here is included,
+mounted or extended by a consumer project. Copy the closest one, adjust the
+service names and ports, and it is yours.
+
+`portta env init <path>` generates the same thing from a project's actual
+Compose file, which is usually faster.
+
+| Template | Shape |
+|---|---|
+| [`01-single-web.yaml`](overlays/01-single-web.yaml) | one HTTP service |
+| [`02-web-api.yaml`](overlays/02-web-api.yaml) | web + API |
+| [`03-web-api-postgres.yaml`](overlays/03-web-api-postgres.yaml) | web + API + a database that stays private |
+| [`04-web-api-postgres-redis.yaml`](overlays/04-web-api-postgres-redis.yaml) | the common full stack |
+| [`05-multiple-apis.yaml`](overlays/05-multiple-apis.yaml) | several APIs behind one namespace |
+| [`06-monorepo.yaml`](overlays/06-monorepo.yaml) | `apps/` and `services/` in one repository |
+| [`07-worktree.env`](overlays/07-worktree.env) | a second copy of a project, in parallel |
+| [`08-nonstandard-port.yaml`](overlays/08-nonstandard-port.yaml) | an HTTP service on an unusual internal port |
+| [`09-tcp-routing.yaml`](overlays/09-tcp-routing.yaml) | opt a datastore into hostname TCP routing |
+| [`10-mailpit.yaml`](overlays/10-mailpit.yaml) | Mailpit UI on the gateway (SMTP stays private) |
+| [`11-rustfs.yaml`](overlays/11-rustfs.yaml) | RustFS console on the gateway (S3 API stays private) |
+
+## The two rules every template follows
+
+**Labels are in list form.** Compose interpolates `${VAR}` inside a list entry
+but **not** inside a mapping key. Written as a map, the Traefik service name
+keeps the literal `${COMPOSE_PROJECT_NAME}` and every worktree of the project
+collapses onto one load balancer.
+
+**Traefik service names carry the namespace.** Those names are flat across the
+whole host. Two projects declaring a bare `web` are merged into a single load
+balancer and start serving each other's traffic.
+
+`portta doctor` reports both.
+
+## For the consumer repository
+
+[`project/PORTTA.md`](project/PORTTA.md) is a short page to copy into
+the project itself: how to start it, its URLs, how to reach its database, how
+to run a second copy. It deliberately does not restate the gateway's
+documentation; this repository stays the single source of the rules.

package/dist/runtime/templates/overlays/01-single-web.yaml

@@ -0,0 +1,23 @@
+# ============================================================================
+# One HTTP service
+# ============================================================================
+#   docker compose -f compose.yaml -f compose.portta.yaml up -d
+#   -> http://<COMPOSE_PROJECT_NAME>-web.localhost
+# ============================================================================
+
+services:
+  web:
+    networks:
+      - default
+      - portta
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      # Only needed when the image's EXPOSE does not match the port the app
+      # actually listens on. It usually does not, so state it.
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/02-web-api.yaml

@@ -0,0 +1,30 @@
+# ============================================================================
+# Web + API
+# ============================================================================
+# Both keep their internal ports. Other projects on this host use the same
+# 3000 and 8000 at the same time, and nothing collides, because neither
+# publishes a host port.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-web.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api.localhost
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/03-web-api-postgres.yaml

@@ -0,0 +1,33 @@
+# ============================================================================
+# Web + API + PostgreSQL
+# ============================================================================
+# Note what is NOT here: postgres. A database has no business on the shared
+# network, since everything else on the host could reach it, and it does not
+# need a host port either.
+#
+# The API reaches it as `postgres:5432` over the project's own network, exactly
+# as before. A human reaches it on demand:
+#
+#   portta access open --project <name> --service postgres
+#   -> 127.0.0.1:<free port>
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/04-web-api-postgres-redis.yaml

@@ -0,0 +1,30 @@
+# ============================================================================
+# Web + API + PostgreSQL + Redis: the common full stack
+# ============================================================================
+# Identical to template 03: adding a cache changes nothing about the contract.
+# Postgres and Redis both stay on the project's private network, both keep
+# their standard ports, and both are reached with `portta access open`.
+#
+# Workers are absent too. A queue consumer serves no HTTP, so it has nothing to
+# route; it stays on `default` and needs no changes at all.
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/05-multiple-apis.yaml

@@ -0,0 +1,37 @@
+# ============================================================================
+# Several APIs in one project
+# ============================================================================
+# Each gets its own hostname from its own service name. They can all listen on
+# 8000 internally; nothing needs renumbering.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-api-auth.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api-billing.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api-search.localhost
+# ============================================================================
+
+services:
+  api-auth:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api-auth.loadbalancer.server.port=8000"
+
+  api-billing:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api-billing.loadbalancer.server.port=8000"
+
+  api-search:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api-search.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/06-monorepo.yaml

@@ -0,0 +1,63 @@
+# ============================================================================
+# Monorepo: apps/ and services/ in one repository
+# ============================================================================
+# A monorepo is one Compose project with more services in it. Nothing about the
+# contract changes, and the gateway needs to know nothing about the layout.
+#
+#   repo/
+#     apps/web/          -> web
+#     apps/admin/        -> admin
+#     services/api/      -> api
+#     services/worker/   -> worker      (no HTTP; not routed)
+#     services/importer/ -> importer    (no HTTP; not routed)
+#     compose.yaml
+#     compose.portta.yaml   <- this file
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-web.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-admin.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api.localhost
+#
+# Build contexts, Dockerfiles and volumes stay exactly where they are. The
+# gateway never centralises any of that.
+#
+# Splitting one monorepo into several namespaces is possible: run separate
+# Compose projects per app: but it is rarely worth it: one namespace keeps the
+# services on a single private network, which is usually what they expect.
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      # Optional, and only useful because inference cannot get them right here:
+      # `portta.git.root` says where the repository actually starts when
+      # the Compose file is not at its root, and `portta.repo` gives the
+      # panel a repository link with no host-side Git at all. Delete both and
+      # everything behaves exactly as it does now.
+      # - "portta.repo=owner/monorepo"
+      # - "portta.git.root=/srv/dev/monorepo"
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  admin:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-admin.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+  # worker and importer are absent on purpose: they serve no HTTP, so they need
+  # no networks and no labels. They keep running exactly as they did.
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/07-worktree.env

@@ -0,0 +1,47 @@
+# ============================================================================
+# A second copy of a project, running in parallel
+# ============================================================================
+# Copy to `.env` in the worktree. This is the entire mechanism: Compose derives
+# container, network and volume names from COMPOSE_PROJECT_NAME, and the gateway
+# derives hostnames from it.
+#
+#   git worktree add ../base-empresarial-issue59 issue59
+#   cd ../base-empresarial-issue59
+#   cp <this file> .env
+#   docker compose -f compose.yaml -f compose.portta.yaml up -d
+#
+#   -> http://base-empresarial-issue59-web.localhost
+#
+# The original environment keeps running. Nothing inside the project changed.
+# Derive the name instead of inventing one:
+#
+#   portta env namespace
+# ============================================================================
+
+COMPOSE_PROJECT_NAME=base-empresarial-issue59
+
+# Saves repeating -f on every command.
+COMPOSE_FILE=compose.yaml:compose.portta.yaml
+
+# Must match PORTTA_NETWORK in the gateway's own .env.
+PORTTA_NETWORK=portta
+
+# ---------------------------------------------------------------------------
+# Optional: say which project this worktree belongs to
+# ---------------------------------------------------------------------------
+# COMPOSE_PROJECT_NAME is a per-worktree namespace, so five worktrees look like
+# five projects in the panel. A `portta.project` label on any one service
+# groups them back under one heading. Nothing depends on it: without it the
+# panel still infers the worktree from the directory name, exactly as before.
+#
+#   labels:
+#     - "portta.project=base-empresarial"
+#     - "portta.repo=owner/base-empresarial"
+
+# ---------------------------------------------------------------------------
+# What must NOT be shared with the other worktree
+# ---------------------------------------------------------------------------
+# Do not point this environment at an external volume or a database the other
+# copy also uses. Two worktrees writing to one database is the failure this
+# whole mechanism exists to prevent, and it is silent until it corrupts
+# something. Let Compose create per-namespace volumes.

package/dist/runtime/templates/overlays/08-nonstandard-port.yaml

@@ -0,0 +1,41 @@
+# ============================================================================
+# An HTTP service on an unusual internal port
+# ============================================================================
+# Traefik guesses the backend port from the image's EXPOSE when only one port
+# is exposed. That guess is wrong whenever the image exposes one port and the
+# application listens on another: which is most of the time once a command or
+# an environment variable moves it.
+#
+# The symptom is a 502 from the gateway: the route matched, the backend did not
+# answer. Stating the port removes the guess.
+#
+# Anything is fine here: 4321, 9090, 1313. The port is internal, so it never
+# competes with another project.
+# ============================================================================
+
+services:
+  docs:
+    # e.g. a static site generator listening on 1313
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-docs.loadbalancer.server.port=1313"
+
+  # A service whose container serves HTTPS internally needs the scheme too,
+  # or Traefik will speak plaintext to a TLS port.
+  secure-backend:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-secure-backend.loadbalancer.server.port=8443"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-secure-backend.loadbalancer.server.scheme=https"
+      # Development backends usually have a self-signed certificate.
+      - "traefik.http.serverstransports.${COMPOSE_PROJECT_NAME}-insecure.insecureskipverify=true"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-secure-backend.loadbalancer.serverstransport=${COMPOSE_PROJECT_NAME}-insecure@docker"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/09-tcp-routing.yaml

@@ -0,0 +1,70 @@
+# ============================================================================
+# Template 09: reach this project's database by hostname
+# ============================================================================
+# Add this on top of your project's own compose file, alongside whichever HTTP
+# overlay you already use. It opts a datastore into hostname routing, so it is
+# reachable on the gateway's shared port without publishing one of its own:
+#
+#   psql "postgresql://user@<project>-postgres.<domain>:5432/db?sslmode=require"
+#
+# Requires PORTTA_TCP=true on the gateway. Read docs/product/guides/tcp-routing.md first:
+# PostgreSQL and Redis work, MySQL cannot, and TLS is not optional.
+#
+#   docker compose -f compose.yaml -f compose.portta.yaml \
+#                  -f compose.portta-tcp.yaml up -d
+#
+# Three details worth copying verbatim:
+#
+# 1. The datastore joins `portta-access`, NOT the shared `portta`
+#    network. Databases have never been on the HTTP network and still are not.
+#
+# 2. The rule is HostSNIRegexp, not HostSNI, so this file does not have to know
+#    the gateway's domain. The same overlay then works unchanged against
+#    `.localhost` on a workstation and `.vpn.example.com` on a VPS. It grants
+#    nothing extra: whoever knows the project name can reach the entrypoint
+#    with the exact hostname anyway, and authentication is still PostgreSQL's.
+#
+# 3. Router and service names carry the project name, because they share one
+#    namespace across every project on the host. `portta doctor` reports
+#    a collision if two projects ever pick the same one.
+# ============================================================================
+
+services:
+  postgres:
+    networks:
+      - default        # keep talking to the rest of the project privately
+      - portta-access
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_ACCESS_NETWORK:-portta-access}"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.entrypoints=postgres"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.rule=HostSNIRegexp(`^${COMPOSE_PROJECT_NAME}-postgres\\..+$`)"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.tls=true"
+      # libpq 17+ offers ALPN `postgresql`; without this option the TLS
+      # handshake is rejected before any Postgres traffic happens.
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.tls.options=postgres@file"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.service=${COMPOSE_PROJECT_NAME}-postgres"
+      - "traefik.tcp.services.${COMPOSE_PROJECT_NAME}-postgres.loadbalancer.server.port=5432"
+
+  redis:
+    networks:
+      - default
+      - portta-access
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_ACCESS_NETWORK:-portta-access}"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.entrypoints=redis"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.rule=HostSNIRegexp(`^${COMPOSE_PROJECT_NAME}-redis\\..+$`)"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.tls=true"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.service=${COMPOSE_PROJECT_NAME}-redis"
+      - "traefik.tcp.services.${COMPOSE_PROJECT_NAME}-redis.loadbalancer.server.port=6379"
+
+  # MySQL and MariaDB are deliberately absent. The MySQL protocol has the
+  # server speak first, so there is no SNI for the gateway to route on before
+  # it must choose a backend. Reach them with `portta access open`, which
+  # works for every protocol. docs/product/guides/tcp-routing.md explains why in full.
+
+networks:
+  portta-access:
+    external: true
+    name: ${PORTTA_ACCESS_NETWORK:-portta-access}

package/dist/runtime/templates/overlays/10-mailpit.yaml

@@ -0,0 +1,24 @@
+# ============================================================================
+# Mailpit: capture outbound mail in development
+# ============================================================================
+# The UI (8025) is HTTP and joins the gateway. SMTP (1025) stays on the
+# project's private network and is reached with `portta access open`.
+#
+# The base Compose file should declare the mailpit service itself; this overlay
+# only adds the network and labels.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-mailpit.localhost
+# ============================================================================
+
+services:
+  mailpit:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-mailpit.loadbalancer.server.port=8025"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/11-rustfs.yaml

@@ -0,0 +1,25 @@
+# ============================================================================
+# RustFS: S3-compatible object storage in development
+# ============================================================================
+# The console (9001) is HTTP and joins the gateway. The S3 API (9000) stays on
+# the project's private network so sibling containers can talk to it as
+# `rustfs:9000` without publishing a host port.
+#
+# The base Compose file should declare the rustfs service itself; this overlay
+# only adds the network and labels for the console.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-rustfs.localhost
+# ============================================================================
+
+services:
+  rustfs:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-rustfs.loadbalancer.server.port=9001"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}