portta 0.8.0

package/dist/runtime/.env.example

@@ -0,0 +1,440 @@
+# Portta environment structure: 1
+# ============================================================================
+# Portta: configuration
+# ============================================================================
+# Copy to `.env` and adjust. `.env` is git-ignored and may contain secrets.
+#
+#   cp .env.example .env
+#   ./bin/portta bootstrap
+#
+# This template defines installation structure. Preparation fills missing secrets
+# and host identities; subsequent runs preserve configured values.
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# Common: applies to every profile
+# ----------------------------------------------------------------------------
+
+# Active profile: local | remote-private | remote-public
+# Used as the default for `portta up` when no profile is given.
+PORTTA_PROFILE=local
+
+# Compose project name of the gateway itself. Keep it stable: `doctor` and the
+# ownership checks rely on it to tell gateway resources from consumer ones.
+PORTTA_PROJECT_NAME=portta
+
+# Where this Node expects managed Projects to live. One directory per
+# installation. Development examples named portta-demo-* are discovered here.
+# Changing it changes the reference; files are not moved.
+# Default: ~/projects (user) or /srv/projects (root). Not PORTTA_HOME.
+PORTTA_PROJECTS_HOME=
+# PORTTA_PROJECTS_HOME=
+
+# Shared external Docker network that consumer projects attach published
+# HTTP services to. Created by `bootstrap`, never removed automatically.
+PORTTA_NETWORK=portta
+
+# Private, `internal: true` network carrying Traefik -> Docker socket proxy
+# traffic. Never joined by consumer projects, never published to the host.
+PORTTA_CONTROL_NETWORK=portta-control
+
+# Private network used by persistent TCP forwarders (see docs/product/guides/tcp-access.md).
+PORTTA_ACCESS_NETWORK=portta-access
+
+# Log level for gateway components: DEBUG | INFO | WARN | ERROR
+PORTTA_LOG_LEVEL=INFO
+
+# Traefik access logs. Useful when debugging routing, noisy otherwise.
+PORTTA_ACCESS_LOG=false
+
+# How Traefik treats request headers whose names contain characters outside
+# [A-Za-z0-9-]: these can alias a canonical header once a backend normalises
+# them (X_Auth_User -> X-Auth-User in CGI/WSGI/PHP/nginx), letting a client
+# spoof headers Traefik manages.
+#   keep   forward as is (Traefik's default; fine behind loopback or a VPN)
+#   delete silently strip them: also strips legitimate underscore headers
+#   reject answer 400 Bad Request
+# The remote-public profile raises this to `delete` on its own.
+PORTTA_ALIAS_HEADERS_STRATEGY=keep
+
+# ----------------------------------------------------------------------------
+# Local profile
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Project domain: what every project hostname is built on
+# ----------------------------------------------------------------------------
+# Hostnames are derived as <compose-project>-<service>.<base>, and this decides
+# the base. It is a name, never an exposure: which interface Traefik answers on
+# is PORTTA_BIND_ADDRESS and PUBLIC_ENABLED, and neither changes here.
+#
+#   local   localhost. Resolves to loopback with no DNS and no /etc/hosts, and
+#           is right for a machine you are sitting at — and useless from
+#           anywhere else, which is why it is not the default on a VPS.
+#   auto    <ip-with-dashes>.sslip.io, derived from PORTTA_PUBLIC_IP below.
+#           The provider answers for any name embedding an address, so this
+#           needs no DNS record, no registration and no account.
+#   custom  PORTTA_DOMAIN as typed, for a wildcard you own.
+#
+#   portta config set domain.mode local|auto|custom
+#
+# switches between them on a running host, re-labelling every project at once.
+# See docs/development/adr/0022-project-domain-modes.md.
+PORTTA_DOMAIN_MODE=local
+
+# Used by `auto`. The installer detects it, and `portta config set domain.mode
+# auto` refreshes it. Kept in the file so no command has to make a network call
+# to know what a hostname should be.
+PORTTA_PUBLIC_IP=
+
+# sslip.io | nip.io. Both resolve <anything>.<ip-with-dashes>.<provider> to
+# that address; sslip.io is the default.
+PORTTA_AUTO_DOMAIN_PROVIDER=sslip.io
+
+# The base itself. Read when the mode is `custom`, and overwritten by the other
+# two modes, so edit the mode rather than this.
+PORTTA_DOMAIN=localhost
+
+# Host interface Traefik publishes on. Keep 127.0.0.1 for local development:
+# it makes the gateway unreachable from the local network.
+# The `remote-public` profile overrides this with 0.0.0.0 on purpose.
+PORTTA_BIND_ADDRESS=127.0.0.1
+
+# Host ports. Change only if 80/443 are already taken on this machine.
+PORTTA_HTTP_PORT=80
+PORTTA_HTTPS_PORT=443
+
+# ----------------------------------------------------------------------------
+# Traefik dashboard: off by default
+# ----------------------------------------------------------------------------
+# When enabled the dashboard is published on loopback only, on its own port.
+# It is never routed through the public entrypoints. See docs/product/concepts/security.md.
+PORTTA_DASHBOARD=false
+PORTTA_DASHBOARD_BIND_ADDRESS=127.0.0.1
+PORTTA_DASHBOARD_PORT=8080
+
+# ----------------------------------------------------------------------------
+# Databases by hostname: off by default
+# ----------------------------------------------------------------------------
+# One host port per protocol, however many instances run behind it, told apart
+# by the hostname the client asks for:
+#
+#   storefront-postgres.localhost:5432  ->  storefront's postgres:5432
+#   checkout-postgres.localhost:5432    ->  checkout's postgres:5432
+#
+# Only services that opt in are routed, and the projects that do join the
+# access network rather than the shared HTTP one. TLS is required, because the
+# hostname travels in the TLS handshake. PostgreSQL and Redis work; MySQL
+# cannot. Read docs/product/guides/tcp-routing.md before turning this on.
+#
+# Refused on the remote-public profile: a database is never reachable from the
+# internet.
+
+PORTTA_TCP=false
+
+# Host ports for the entrypoints. Change them if something already holds the
+# standard ones on this machine.
+PORTTA_TCP_POSTGRES_PORT=5432
+PORTTA_TCP_REDIS_PORT=6379
+
+# ----------------------------------------------------------------------------
+# Web panel: off by default
+# ----------------------------------------------------------------------------
+# The administration panel (see docs/product/guides/web-ui.md). It is published on loopback
+# and never routed through the public entrypoints. `portta web up` sets
+# these for you.
+
+PORTTA_WEB=false
+PORTTA_WEB_BIND_ADDRESS=127.0.0.1
+PORTTA_WEB_PORT=8081
+
+# Where the panel can be reached from. This is panel access, and it is
+# deliberately independent of PORTTA_PROFILE: making the panel reachable never
+# makes an application reachable. See docs/development/adr/0021-panel-access-modes.md.
+#
+#   local      loopback only (default). Reach it over an SSH tunnel:
+#                ssh -L 8081:127.0.0.1:8081 user@host
+#   tailscale  bound to this node's tailnet address only. Set
+#              PORTTA_WEB_BIND_ADDRESS to the 100.x.y.z address; nothing is
+#              published on the public interface.
+#   public     published on every interface through Traefik's own `panel`
+#              entrypoint. Requires PORTTA_AUTH_MODE=required; the panel
+#              authenticates requests itself.
+#   vpn        routed by Traefik at PORTTA_WEB_HOST.<domain>, which is
+#              meaningful only on the remote-private profile. Requires a
+#              credential, and is refused on remote-public.
+#
+#   portta config set panel.access public|tailscale|local
+#
+# switches between them on an installed host without reinstalling.
+PORTTA_WEB_EXPOSE=local
+PORTTA_WEB_HOST=portta-web
+
+# The address the panel is advertised at in `public` mode, where the published
+# port belongs to Traefik and 0.0.0.0 is not something anybody types. The
+# installer fills this with the detected public IP or hostname; it is cosmetic
+# and changes no binding.
+PORTTA_PANEL_ADVERTISED_HOST=
+
+# Refuse every mutating endpoint. Useful when an agent is driving the panel,
+# and the default whenever the panel is routed beyond loopback.
+PORTTA_WEB_READ_ONLY=false
+
+# The panel's own front door, which is now the panel's own business.
+#
+#   disabled  every request is the local operator. Only legal on loopback: the
+#             panel refuses to start any other way, because reaching it there
+#             already means having the machine.
+#   required  the panel signs people in. Accounts, roles, sessions, tokens and
+#             an optional second factor, all in its database. The first person
+#             is created at /setup, once, and creates everyone else.
+#
+# See docs/development/adr/0035-authentication-lives-in-the-panel.md and docs/product/guides/authentication.md.
+PORTTA_AUTH_MODE=disabled
+
+# Signs sessions, for the panel and for the ForwardAuth service in front of
+# project hostnames. Generated by `portta bootstrap` and `portta web up` without
+# ever being printed. Changing it signs everybody out.
+PORTTA_AUTH_SECRET=
+
+# Where a browser reaches the panel. Three things come from it: whether the
+# session cookie may be `Secure`, which origins a sign-in is accepted from, and
+# the address the panel prints. `portta web up` writes it to match the exposure;
+# empty means loopback on the published port.
+PORTTA_PANEL_URL=
+
+# Extra origins a browser may sign in from, comma-separated. Needed only when
+# the panel answers on a name the URL above does not name -- a reverse proxy in
+# front of it, a second hostname on the same port.
+PORTTA_PANEL_TRUSTED_ORIGINS=
+
+# How many sign-in attempts one address gets every ten minutes, before the panel
+# starts answering 429. Five is enough to make guessing expensive. The window is
+# per address, so a whole team behind one NAT is one address: that is what this
+# is for. Between 3 and 100; anything else is read as the default.
+PORTTA_AUTH_SIGNIN_ATTEMPTS=5
+
+# The project's documentation at /docs, served from the panel image. Static
+# text with no host information in it, so a routed panel may serve it.
+PORTTA_RUNTIME_DOCS=true
+
+# The API reference and its console at /docs/api. This one issues real requests
+# against this panel, so it keeps the conservative default: empty means enabled
+# on loopback and disabled when routed. The /api/openapi.json contract is
+# always available.
+PORTTA_RUNTIME_API_DOCS=
+
+# Panel persistence. `bootstrap` or `web up` generates the password; it is
+# never printed or returned by the API. In managed mode the application derives
+# its URL from these fields. A URL is accepted only in explicit external mode.
+PORTTA_DB_NETWORK=portta-data
+PORTTA_DB_VOLUME=portta-db
+# managed: db:5432 is fixed internal DNS/port, with no host publication.
+# external: only PORTTA_RUNTIME_DATABASE_URL determines the connection.
+PORTTA_RUNTIME_DB_MODE=managed
+PORTTA_RUNTIME_DB_NAME=portta
+PORTTA_RUNTIME_DB_USER=portta
+PORTTA_RUNTIME_DB_PASSWORD=
+PORTTA_RUNTIME_DATABASE_URL=
+
+# The panel image. A normal installation pulls this; it never builds, because
+# an installed PORTTA_HOME holds no application source. Pinned like every other
+# component image (docs/development/adr/0004-pinned-versions.md).
+PORTTA_WEB_IMAGE=
+PORTTA_AUTH_IMAGE=
+
+# Build the panel image from this checkout instead of pulling it. Only useful
+# inside the repository: the build context is the repository root.
+PORTTA_WEB_BUILD=false
+
+# Development mode: Next.js and the API in one container with hot reloading.
+PORTTA_WEB_DEV=false
+
+# Private, internal network carrying panel -> its own Docker socket proxy.
+PORTTA_WEB_NETWORK=portta-web
+# Host uid:gid, filled once by preparation so the containers can read/write state.
+PORTTA_WEB_USER=
+PORTTA_AUTH_USER=
+
+# User the panel container runs as. .env is owner-only, so the panel has to run
+# as whoever owns it or the Settings page cannot save. `bootstrap`, `web up` and
+# the installer record "$(id -u):$(id -g)" here when it is missing; the image's
+# own `node` is only right when the host uid happens to be 1000.
+# PORTTA_WEB_USER=1000:1000
+
+# The user the authentication service runs as. Same reason as above: it reads
+# .env once and the owner-only protection store on every request, and both
+# belong to whoever installed Portta. The installer records the right value.
+# PORTTA_AUTH_USER=1000:1000
+
+# ----------------------------------------------------------------------------
+# Applying settings from the panel: optional, off by default
+# ----------------------------------------------------------------------------
+# Traefik reads its static configuration from the environment its container was
+# created with, so a setting the panel saves takes effect only once the gateway
+# containers are RECREATED. Recreating them means Compose, which the panel
+# cannot reach: its Docker permissions stop at start, stop and restart.
+#
+# With this on, `portta up` prepares one stopped, single-purpose container whose
+# command is fixed at creation time -- `portta up`, nothing else, no argument
+# from the panel -- and the panel gains an "Apply and restart" button that only
+# starts it. The panel goes offline for a few seconds while it is recreated, and
+# comes back on its own.
+#
+# Be clear about what this grants: anyone who can write through the panel can
+# run `portta up` on this host. It is refused in read-only mode, the applier
+# takes no input, and the panel never gains `exec`. Leave it false on a host
+# where the panel is reachable by anyone you would not hand a shell.
+#
+# On a repository checkout -- PORTTA_WEB_BUILD or PORTTA_WEB_DEV -- the apply
+# rebuilds the local images first. The build runs on the host daemon, not inside
+# the applier, and Compose builds before it stops anything; the only cost is
+# time, and the panel says so before you confirm.
+# See docs/development/adr/0026-applying-settings-from-the-panel.md.
+
+PORTTA_APPLY=true
+
+# Prepare the project runner the panel may start to drive Compose for one
+# project (up, stop, restart, build, down). Off by default, and deliberately
+# absent from the Settings catalogue — turning it on is an edit on the host.
+# See docs/development/adr/0030-the-panel-and-a-project-lifecycle.md.
+PORTTA_RUNNER=true
+
+# ----------------------------------------------------------------------------
+# TLS
+# ----------------------------------------------------------------------------
+
+# Master switch for HTTPS. When false, only the HTTP entrypoint serves routes.
+TLS_ENABLED=false
+
+# TLS mode: local | acme
+#   local: certificates from a local CA (see `portta tls` and docs)
+#   acme : Let's Encrypt / ACME, requires a real domain (remote profiles)
+TLS_MODE=local
+
+# Contact address for the ACME account. Required when TLS_MODE=acme.
+ACME_EMAIL=
+
+# How the ACME account proves it controls the name: dns | http
+#
+#   dns  (default) One wildcard certificate for *.<domain>. The only challenge
+#        that can issue a wildcard, so a hostname works over HTTPS before
+#        anything runs on it, and the only one that works for a private gateway
+#        Let's Encrypt can never reach. Needs a DNS provider credential below.
+#
+#   http One certificate per hostname, issued the first time a router asks for
+#        it. Needs nothing but :80 reachable from the internet -- no credential.
+#        Cannot issue a wildcard, so a new hostname waits a second or two on its
+#        first request, and Let's Encrypt counts each name against the weekly
+#        limit for the registered domain.
+ACME_CHALLENGE=dns
+
+# ACME directory URL. Point at the staging endpoint while testing to avoid
+# burning Let's Encrypt rate limits.
+# staging: https://acme-staging-v02.api.letsencrypt.org/directory
+ACME_CA_SERVER=https://acme-v02.api.letsencrypt.org/directory
+
+# DNS-01 provider name as understood by Traefik/lego. Required for wildcard
+# certificates, and ignored when ACME_CHALLENGE=http. `cloudflare` is the
+# reference implementation shipped here.
+ACME_DNS_PROVIDER=cloudflare
+
+# Resolvers used to check DNS-01 propagation, comma separated host:port.
+ACME_DNS_RESOLVERS=1.1.1.1:53,8.8.8.8:53
+
+# ----------------------------------------------------------------------------
+# Private access (VPN / Tailscale)
+# ----------------------------------------------------------------------------
+
+# When true, Traefik runs inside the Tailscale container's network namespace
+# and listens on the tailnet address, publishing nothing on the public
+# interface. When false, the remote-private profile falls back to binding
+# PORTTA_BIND_ADDRESS: set that to your VPN interface's address.
+TAILSCALE_ENABLED=false
+
+# Hostname this node takes on the tailnet.
+TAILSCALE_HOSTNAME=portta
+
+# Auth key or OAuth client secret. NEVER commit this. Prefer an ephemeral,
+# tagged, pre-authorized key. See docs/product/guides/tailscale.md.
+TS_AUTHKEY=
+
+# Extra flags forwarded to `tailscale up`. Tag the node so ACLs can name it
+# without depending on a person's identity:
+#   TS_EXTRA_ARGS=--advertise-tags=tag:portta
+TS_EXTRA_ARGS=
+
+# Private wildcard namespace served only over the VPN, e.g. vpn.dev.example.com
+# Leave empty to reuse PORTTA_DOMAIN.
+PRIVATE_DOMAIN=
+
+# ----------------------------------------------------------------------------
+# Public access: opt-in, disabled by default
+# ----------------------------------------------------------------------------
+# Enabling this publishes 80/443 on every host interface. Only HTTP services
+# that explicitly opt in are routed. Databases and caches are never published.
+
+PUBLIC_ENABLED=false
+
+# Public wildcard namespace, e.g. dev.example.com
+PUBLIC_DOMAIN=
+
+# ----------------------------------------------------------------------------
+# Cloudflare: optional DNS provider for wildcard DNS-01
+# ----------------------------------------------------------------------------
+# Use a scoped API Token (Zone:DNS:Edit on the target zone only).
+# Never use the Global API Key. Never commit the token.
+
+CLOUDFLARE_ENABLED=false
+CF_DNS_API_TOKEN=
+CLOUDFLARE_ZONE=
+
+# ----------------------------------------------------------------------------
+# GitHub App: optional, off by default
+# ----------------------------------------------------------------------------
+# The panel's only outbound network access, and its only long-lived secret that
+# is not a Traefik credential. With GITHUB_APP_ENABLED=false the panel makes no
+# request to github.com and behaves exactly as it did without this section.
+#
+# The private key is a FILE, never a value here: the panel can write this .env,
+# and must not be able to write the key that authenticates it. Create the App,
+# download the .pem into `state/github/`, and `chmod 600` it. See
+# docs/product/guides/github.md for the exact permission set.
+
+GITHUB_APP_ENABLED=false
+
+# The numeric App id from the App's settings page. Not a secret.
+GITHUB_APP_ID=
+
+# The .pem inside the panel container. `state/github/` is the only directory
+# mounted there, so the path must begin /app/state/github/. The filename is
+# yours: keep the one GitHub gave the download if you like.
+GITHUB_APP_PRIVATE_KEY_FILE=/app/state/github/app.pem
+
+# Verifies webhook deliveries. Generate one when you create the App.
+GITHUB_APP_WEBHOOK_SECRET=
+
+# GitHub Enterprise Server users: your API root, e.g. https://ghe.example.com/api/v3
+GITHUB_API_URL=https://api.github.com
+
+# How often the panel re-reads what changed on GitHub, in minutes.
+#
+# A loopback panel cannot receive webhook deliveries, so without this the
+# projection is only as fresh as the last time somebody pressed Sync. A pass
+# asks for issues updated since the stored cursor, so a quiet repository costs
+# one conditional request.
+#
+# Set 0 on a panel that DOES receive webhooks, where the timer would do the
+# same work twice.
+GITHUB_SYNC_INTERVAL_MINUTES=15
+
+# ----------------------------------------------------------------------------
+# Cloudflare Tunnel: optional connector (credential stays in state/cloudflared)
+# ----------------------------------------------------------------------------
+CLOUDFLARE_TUNNEL_ENABLED=false
+CLOUDFLARE_TUNNEL_ZONE=
+CLOUDFLARE_TUNNEL_ID=
+PORTTA_CLOUDFLARED_IMAGE=cloudflare/cloudflared:2026.8.3
+
+# Optional Traefik API override. Empty derives the endpoint from the attachment.
+PORTTA_RUNTIME_TRAEFIK_API=

package/dist/runtime/VERSION

@@ -0,0 +1 @@
+0.8.0

package/dist/runtime/config/traefik/dynamic/auth.example.yaml.disabled

@@ -0,0 +1,24 @@
+# ============================================================================
+# Portta project protection: the working middleware is generated for you
+# ============================================================================
+# Do not copy this file into the dynamic directory. `portta-auth.yaml` already
+# defines `portta-forward-auth`; this disabled example documents the project
+# label that opts one existing router into it.
+#
+# 1. Create or rotate the host credential:
+#
+#      portta auth protect demo-web.example.com --project demo --service web
+#
+# 2. Add the middleware to that project's own router:
+#
+#      labels:
+#        - "traefik.http.routers.demo-web.middlewares=portta-forward-auth@file"
+#
+# Portta deliberately does not edit a consumer project's labels. The project
+# owns that router; Portta owns only the credential, login route and ForwardAuth
+# middleware. `/__portta/auth` is reserved on every protected hostname.
+#
+# To remove the credential (the project label remains yours to remove):
+#
+#      portta auth unprotect demo-web.example.com
+# ============================================================================

package/dist/runtime/config/traefik/dynamic/local-tls.yaml

@@ -0,0 +1,11 @@
+# Generated by `portta tls init`. Safe to delete: re-run the command to
+# recreate it. The certificate and key live in config/tls/, which is git-ignored.
+tls:
+  stores:
+    default:
+      defaultCertificate:
+        certFile: /etc/traefik/tls/wildcard.crt
+        keyFile: /etc/traefik/tls/wildcard.key
+  certificates:
+    - certFile: /etc/traefik/tls/wildcard.crt
+      keyFile: /etc/traefik/tls/wildcard.key

package/dist/runtime/config/traefik/dynamic/middlewares.yaml

@@ -0,0 +1,35 @@
+# ============================================================================
+# Portta: reusable dynamic configuration
+# ============================================================================
+# Hot-reloaded by Traefik's file provider. Reference these from a consumer
+# project with, for example:
+#
+#   labels:
+#     traefik.http.routers.web.middlewares: "portta-secure-headers@file"
+#
+# Nothing here is applied automatically: a project opts in per router.
+# ============================================================================
+
+http:
+  middlewares:
+    # Sensible baseline response headers for browser-facing dev environments.
+    portta-secure-headers:
+      headers:
+        frameDeny: false
+        contentTypeNosniff: true
+        browserXssFilter: true
+        referrerPolicy: strict-origin-when-cross-origin
+
+    # Marks responses as coming through the gateway. Handy when debugging
+    # whether a request reached Traefik at all.
+    portta-stamp:
+      headers:
+        customResponseHeaders:
+          X-Portta: "1"
+
+    # Blocks everything. Attach to a router you want reachable only from the
+    # tailnet while you sort out a real policy.
+    portta-deny-all:
+      ipAllowList:
+        sourceRange:
+          - 127.0.0.1/32

package/dist/runtime/config/traefik/dynamic/portta-aliases.yaml

@@ -0,0 +1,9 @@
+# ============================================================================
+# Generated by Portta panel. Edits are overwritten.
+# ============================================================================
+# Hostname aliases: one additional router per aliased service. The project's
+# own router is never touched, so both hostnames answer. See docs/web-ui.md.
+# ============================================================================
+# portta-aliases: []
+
+# No alias is set. A project is reached on the hostname it derives.

package/dist/runtime/config/traefik/dynamic/portta-auth.yaml

@@ -0,0 +1,19 @@
+# ============================================================================
+# Generated by Portta. Edits are overwritten.
+# ============================================================================
+# ForwardAuth is a separate process. The reserved login routers below must
+# never reference either authentication middleware. See ADR 0027.
+# ============================================================================
+http:
+  routers:
+  services:
+    portta-auth:
+      loadBalancer:
+        servers:
+          - url: "http://portta-auth:4180"
+  middlewares:
+    portta-forward-auth:
+      forwardAuth:
+        address: "http://portta-auth:4180/verify"
+        trustForwardHeader: true
+        authResponseHeaders: [X-Forwarded-User, X-Portta-Actor, X-Portta-Actor-Kind]

package/dist/runtime/config/traefik/dynamic/portta-shares.yaml

@@ -0,0 +1,10 @@
+# ============================================================================
+# Generated by Portta panel. Edits are overwritten.
+# ============================================================================
+# Temporary shares: one additional hostname per service, each with an expiry.
+# A project's own router is never touched, and revoking a share deletes a
+# block from this file. See docs/product/guides/sharing.md.
+# ============================================================================
+# portta-shares: []
+
+# Nothing is shared. "Private" is the absence of a share, not a deny rule.

package/dist/runtime/config/traefik/dynamic/tcp.yaml

@@ -0,0 +1,23 @@
+# ============================================================================
+# TLS options for the TCP entrypoints
+# ============================================================================
+# Loaded by the file provider on every profile. It defines options only; the
+# certificate comes from the default store, which is either the local CA
+# (`portta tls init`) or ACME on the remote profiles.
+# ============================================================================
+
+tls:
+  options:
+    # PostgreSQL 17 registered `postgresql` as an ALPN protocol identifier when
+    # it added direct TLS negotiation, and libpq 17+ offers it on every TLS
+    # connection, STARTTLS included. Traefik's entrypoints advertise h2,
+    # http/1.1 and acme-tls/1, so without this the handshake dies before any
+    # Postgres traffic happens:
+    #
+    #   psql: SSL error: tlsv1 alert no application protocol
+    #
+    # Older clients send no ALPN at all and are unaffected, so one option
+    # serves both. See docs/product/guides/tcp-routing.md.
+    postgres:
+      alpnProtocols:
+        - postgresql

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

@@ -0,0 +1,24 @@
+# ============================================================================
+# Attachment: Traefik in its own network namespace, ports on the host
+# ============================================================================
+# Used by the `local` profile, and by remote profiles when Tailscale is not
+# managed by the gateway (a host-native Tailscale, WireGuard, or a plain
+# public VPS).
+#
+# PORTTA_BIND_ADDRESS decides who can reach it:
+#   127.0.0.1   this machine only              (local default)
+#   100.x.y.z   the tailnet only               (host-native Tailscale)
+#   0.0.0.0     everyone                       (remote-public, opt-in)
+#
+# `doctor` fails if the local profile binds to anything but loopback, or if
+# the private profile binds to 0.0.0.0.
+# ============================================================================
+
+services:
+  traefik:
+    networks:
+      - gateway
+      - control
+    ports:
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_HTTP_PORT:-80}:80"
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_HTTPS_PORT:-443}:443"

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

@@ -0,0 +1,70 @@
+# ============================================================================
+# Attachment: Traefik inside the Tailscale container's network namespace
+# ============================================================================
+# The default for the `remote-private` profile.
+#
+# `network_mode: service:tailscale` merges the two containers' network
+# namespaces, so Traefik listens directly on the node's tailnet address. No
+# port is published on the host at all: the gateway is unreachable from the
+# VPS's public interface, and reachable from the tailnet subject to your
+# Tailscale ACLs. See docs/development/adr/0007-tailscale-sidecar.md.
+#
+# Traefik keeps its access to the shared and control networks because the
+# Tailscale container joins them and the two share a namespace.
+#
+# Kernel networking (TS_USERSPACE=false) is required: userspace mode has no
+# real interface in the namespace, so an inbound connection would never reach
+# Traefik. That is what /dev/net/tun and NET_ADMIN are for.
+# ============================================================================
+
+services:
+  tailscale:
+    image: tailscale/tailscale:v1.102.3
+    restart: unless-stopped
+    hostname: ${TAILSCALE_HOSTNAME:-portta}
+    networks:
+      - gateway
+      - control
+    ports:
+      # Loopback by default, so `curl` on the VPS itself works for debugging.
+      # The remote-public profile raises PORTTA_BIND_ADDRESS to 0.0.0.0,
+      # and these become the public listeners: Traefik has none of its own.
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_HTTP_PORT:-80}:80"
+      - "${PORTTA_BIND_ADDRESS:-127.0.0.1}:${PORTTA_HTTPS_PORT:-443}:443"
+    environment:
+      TS_AUTHKEY: ${TS_AUTHKEY:-}
+      # Persisting state across restarts keeps the node identity: and so the
+      # tailnet address and any Tailscale-issued certificate: stable.
+      TS_STATE_DIR: /var/lib/tailscale
+      # Authenticate once, then rely on persisted state. Without this a restart
+      # re-runs `tailscale up` and burns a non-reusable key.
+      TS_AUTH_ONCE: "true"
+      TS_USERSPACE: "false"
+      # Never let MagicDNS rewrite resolv.conf: Traefik shares this namespace
+      # and must keep resolving container names through Docker's resolver.
+      TS_ACCEPT_DNS: "false"
+      TS_HOSTNAME: ${TAILSCALE_HOSTNAME:-portta}
+      TS_EXTRA_ARGS: ${TS_EXTRA_ARGS:-}
+    volumes:
+      - ./state/tailscale:/var/lib/tailscale
+    devices:
+      - /dev/net/tun:/dev/net/tun
+    cap_add:
+      - NET_ADMIN
+      - NET_RAW
+    healthcheck:
+      test: ["CMD", "tailscale", "status", "--peers=false"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 20s
+    labels:
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: tailscale
+
+  traefik:
+    network_mode: service:tailscale
+    depends_on:
+      tailscale:
+        condition: service_healthy