portta 0.8.0

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

@@ -0,0 +1,21 @@
+# ============================================================================
+# Portta: build the panel image locally (development only)
+# ============================================================================
+# Applied when PORTTA_WEB_BUILD=true, which only makes sense inside a checkout:
+# the build context is the repository root, and an installed PORTTA_HOME holds
+# no application source at all.
+#
+# A normal installation pulls the published image instead, so a host never
+# needs a compiler, a lockfile or the panel's source to run the panel.
+# See docs/development/adr/0020-installer-and-portta-home.md.
+# ============================================================================
+
+services:
+  web:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+      target: runtime
+      args:
+        PORTTA_VERSION: ${PORTTA_VERSION:-}
+    image: ${PORTTA_WEB_IMAGE:-fabioassuncao/portta:${PORTTA_VERSION}}

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

@@ -0,0 +1,53 @@
+# ============================================================================
+# Portta: panel in development mode
+# ============================================================================
+# Applied when PORTTA_WEB_DEV=true, or by `portta web dev`.
+#
+# One container, one port. The panel is a single Node process — Next, the Hono
+# API, the event stream and the WebSocket upgrades all behind one dispatcher —
+# so HMR arrives on the same 8081 the API answers on.
+#
+# Only source directories are bind-mounted, so the image's node_modules stay in
+# place and the host never needs Node installed.
+# ============================================================================
+
+services:
+  web:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+      target: dev
+      args:
+        PORTTA_VERSION: ${PORTTA_VERSION:-}
+    image: fabioassuncao/portta:dev
+    # The package script, never a restated command line: it carries
+    # `--conditions=development`, without which the workspace packages resolve
+    # to a dist/ the dev image does not build.
+    command: ["npm", "run", "dev"]
+    environment:
+      NODE_ENV: development
+    volumes:
+      - ./apps/web/app:/app/apps/web/app
+      - ./apps/web/components:/app/apps/web/components
+      - ./apps/web/lib:/app/apps/web/lib
+      - ./apps/web/messages:/app/apps/web/messages
+      - ./apps/web/server:/app/apps/web/server
+      - ./apps/web/public:/app/apps/web/public
+      # The packages the panel composes, so editing one reloads it like its own
+      # source: the shared derivations, the contract, the schema, auth, and the
+      # services and API.
+      - ./packages/core/src:/app/packages/core/src
+      - ./packages/contracts/src:/app/packages/contracts/src
+      - ./packages/auth/src:/app/packages/auth/src
+      - ./packages/db/src:/app/packages/db/src
+      # The generated migrations the process applies on the next migrate.
+      # Without this a newly generated file stays in the image until the next
+      # rebuild, so `portta db migrate` and a restart would both see a stale set.
+      - ./packages/db/drizzle:/app/packages/db/drizzle
+      - ./packages/server/src:/app/packages/server/src
+      # The documentation itself: `app/docs` reads and renders it, so a change
+      # to a Markdown file is visible on the next request.
+      - ./docs:/app/docs:ro
+      - ./README.md:/app/README.md:ro
+      - ./CHANGELOG.md:/app/CHANGELOG.md:ro
+      - ./.env:/app/state/.env

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

@@ -0,0 +1,24 @@
+# ============================================================================
+# Portta: reach the panel over the VPN
+# ============================================================================
+# Applied when PORTTA_WEB_EXPOSE=vpn. It adds a Traefik router for the
+# panel so it is reachable at <host>.<domain> from the tailnet, instead of only
+# on the VPS's own loopback.
+#
+# The CLI refuses this overlay on the remote-public profile, where Traefik
+# binds every interface and a router would therefore be public. It must never
+# be reachable from the internet.
+#
+# There is no middleware on the router: the panel signs people in itself, and
+# `portta web up --expose vpn` refuses unless PORTTA_AUTH_MODE=required. The
+# tailnet is the first boundary and the panel's own login is the second.
+# See docs/development/adr/0035-authentication-lives-in-the-panel.md.
+# ============================================================================
+
+services:
+  web:
+    labels:
+      traefik.enable: "true"
+      traefik.http.routers.portta-web.rule: >-
+        Host(`${PORTTA_WEB_HOST:-portta-web}.${PORTTA_DOMAIN:-localhost}`)
+      traefik.http.services.portta-web.loadbalancer.server.port: "8081"

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

@@ -0,0 +1,283 @@
+# ============================================================================
+# Portta: administration panel (opt-in)
+# ============================================================================
+# Enabled by PORTTA_WEB=true, or by `portta web up`.
+#
+# The panel is a development tool, so it is published on loopback by default
+# and never routed through the public entrypoints. Reaching it over a VPN is a
+# separate, explicit overlay: docker/compose/features/web-vpn.yaml.
+#
+# It gets its OWN Docker socket proxy rather than sharing Traefik's. Traefik
+# needs a strictly read-only view; the panel needs to start, stop, restart and
+# remove containers, and those two permission sets must not be merged into one.
+# See docs/product/guides/web-ui.md and docs/development/adr/0008-web-panel-socket-proxy.md.
+# ============================================================================
+
+networks:
+  # Panel <-> its socket proxy. `internal: true`: the proxy has no route to the
+  # outside world and is reachable from nothing else.
+  webcontrol:
+    name: ${PORTTA_WEB_NETWORK:-portta-web}
+    internal: true
+    labels:
+      portta.managed: "true"
+      portta.component: web-control-network
+
+services:
+  # --------------------------------------------------------------------------
+  # The panel's Docker socket proxy
+  # --------------------------------------------------------------------------
+  # Write access is limited to container lifecycle and interactive exec.
+  # Images, volumes, build, swarm and system endpoints (where prune lives) stay
+  # denied, and the panel enforces its narrower path allowlist on top.
+  web-socket-proxy:
+    image: tecnativa/docker-socket-proxy:v0.5.0
+    restart: unless-stopped
+    read_only: true
+    environment:
+      # -- read ------------------------------------------------------------
+      CONTAINERS: "1"
+      NETWORKS: "1"
+      EVENTS: "1"
+      INFO: "1"
+      VERSION: "1"
+      PING: "1"
+      # -- write, limited to the container lifecycle ----------------------
+      POST: "1"
+      ALLOW_START: "1"
+      ALLOW_STOP: "1"
+      ALLOW_RESTARTS: "1"
+      # -- denied ----------------------------------------------------------
+      ALLOW_PAUSE: "0"
+      ALLOW_UNPAUSE: "0"
+      AUTH: "0"
+      BUILD: "0"
+      COMMIT: "0"
+      CONFIGS: "0"
+      DISTRIBUTION: "0"
+      # Four exec paths are allowed again inside the panel: create, attach,
+      # resize and inspect. Traefik's separate proxy remains read-only.
+      EXEC: "1"
+      GRPC: "0"
+      IMAGES: "0"
+      NODES: "0"
+      PLUGINS: "0"
+      SECRETS: "0"
+      SERVICES: "0"
+      SESSION: "0"
+      SWARM: "0"
+      SYSTEM: "0"
+      TASKS: "0"
+      VOLUMES: "0"
+      LOG_LEVEL: warning
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - webcontrol
+    # No `ports:`. The proxy is reachable only from the panel.
+    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: web-socket-proxy
+
+  # --------------------------------------------------------------------------
+  # The panel: API and UI in one process
+  # --------------------------------------------------------------------------
+  web:
+    # A normal installation never builds: the panel is a published image, and
+    # PORTTA_HOME holds no application source to build from. Developers opt
+    # back into a local build with PORTTA_WEB_BUILD=true
+    # (docker/compose/features/web-build.yaml), and `portta web dev` still
+    # builds the dev target. PORTTA_VERSION comes from the generated runtime
+    # asset, so the installed CLI and panel select the same image.
+    image: ${PORTTA_WEB_IMAGE:-ghcr.io/fabioassuncao/portta:${PORTTA_VERSION}}
+    restart: unless-stopped
+    depends_on:
+      web-socket-proxy:
+        condition: service_healthy
+    # `node` is in both the runtime and the `dev` image; the Dockerfile's
+    # `wget` healthcheck only exists on the runtime stage. start_period covers
+    # the first `next.prepare()`; retries then fit `--wait-timeout 180`.
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8081/api/health').then((r)=>process.exit(r.ok||r.status===401?0:1)).catch(()=>process.exit(1))"]
+      interval: 5s
+      timeout: 3s
+      retries: 24
+      start_period: 60s
+    # Whoever owns .env, which the Settings page writes. `bootstrap` and
+    # `web up` record it; the image's own `node` is only a last resort, and is
+    # right just when the host uid happens to be 1000.
+    user: ${PORTTA_WEB_USER:-node}
+    environment:
+      PORTTA_RUNTIME_DB_MODE: ${PORTTA_RUNTIME_DB_MODE:-managed}
+      PORTTA_RUNTIME_DB_NAME: ${PORTTA_RUNTIME_DB_NAME:-portta}
+      PORTTA_RUNTIME_DB_USER: ${PORTTA_RUNTIME_DB_USER:-portta}
+      PORTTA_RUNTIME_DB_PASSWORD: ${PORTTA_RUNTIME_DB_PASSWORD:-}
+      PORTTA_RUNTIME_DATABASE_URL: ${PORTTA_RUNTIME_DATABASE_URL:-}
+      PORTTA_AUTH_SIGNIN_ATTEMPTS: ${PORTTA_AUTH_SIGNIN_ATTEMPTS:-}
+      ACME_CHALLENGE: ${ACME_CHALLENGE:-dns}
+      ACME_DNS_RESOLVERS: ${ACME_DNS_RESOLVERS:-}
+      CLOUDFLARE_TUNNEL_ENABLED: ${CLOUDFLARE_TUNNEL_ENABLED:-false}
+      CLOUDFLARE_TUNNEL_ZONE: ${CLOUDFLARE_TUNNEL_ZONE:-}
+      PORTTA_RUNTIME_DOCKER_API: http://web-socket-proxy:2375
+      PORTTA_RUNTIME_HOST: 0.0.0.0
+      PORTTA_RUNTIME_PORT: "8081"
+      PORTTA_RUNTIME_ENV_FILE: /app/state/.env
+      PORTTA_RUNTIME_READ_ONLY: ${PORTTA_WEB_READ_ONLY:-false}
+      # The machine contract is always served; its browser defaults on only
+      # while the panel stays on loopback.
+      PORTTA_RUNTIME_DOCS: ${PORTTA_RUNTIME_DOCS:-true}
+      PORTTA_RUNTIME_API_DOCS: ${PORTTA_RUNTIME_API_DOCS:-}
+      # The resolved gateway configuration, so the panel and the CLI always
+      # describe the same gateway.
+      PORTTA_PROFILE: ${PORTTA_PROFILE:-local}
+      # Projects Home as a string, for location classification only: no
+      # project directory is ever mounted here (docs/development/adr/0031-projects-home-and-project.md).
+      PORTTA_PROJECTS_HOME: ${PORTTA_PROJECTS_HOME:-}
+      PORTTA_PROJECT_NAME: ${PORTTA_PROJECT_NAME:-portta}
+      PORTTA_NETWORK: ${PORTTA_NETWORK:-portta}
+      PORTTA_CONTROL_NETWORK: ${PORTTA_CONTROL_NETWORK:-portta-control}
+      PORTTA_ACCESS_NETWORK: ${PORTTA_ACCESS_NETWORK:-portta-access}
+      PORTTA_WEB_NETWORK: ${PORTTA_WEB_NETWORK:-portta-web}
+      PORTTA_TCP: ${PORTTA_TCP:-false}
+      PORTTA_TCP_POSTGRES_PORT: ${PORTTA_TCP_POSTGRES_PORT:-5432}
+      PORTTA_TCP_REDIS_PORT: ${PORTTA_TCP_REDIS_PORT:-6379}
+      PORTTA_DOMAIN: ${PORTTA_DOMAIN:-localhost}
+      # How that base was chosen, so the Settings page can show the mode and
+      # the address behind it rather than a bare hostname with no explanation.
+      # See docs/development/adr/0022-project-domain-modes.md.
+      PORTTA_DOMAIN_MODE: ${PORTTA_DOMAIN_MODE:-local}
+      PORTTA_PUBLIC_IP: ${PORTTA_PUBLIC_IP:-}
+      PORTTA_AUTO_DOMAIN_PROVIDER: ${PORTTA_AUTO_DOMAIN_PROVIDER:-sslip.io}
+      PORTTA_BIND_ADDRESS: ${PORTTA_BIND_ADDRESS:-127.0.0.1}
+      PORTTA_HTTP_PORT: ${PORTTA_HTTP_PORT:-80}
+      PORTTA_HTTPS_PORT: ${PORTTA_HTTPS_PORT:-443}
+      PORTTA_DASHBOARD: ${PORTTA_DASHBOARD:-false}
+      PORTTA_DASHBOARD_BIND_ADDRESS: ${PORTTA_DASHBOARD_BIND_ADDRESS:-127.0.0.1}
+      PORTTA_DASHBOARD_PORT: ${PORTTA_DASHBOARD_PORT:-8080}
+      # Traefik's own API, read-only, and only when the dashboard is enabled.
+      # The panel resolves the host from the attachment (`traefik` normally,
+      # `tailscale` when Traefik shares that namespace) and reaches it over the
+      # shared network it is already on, never over `control`: see
+      # docs/development/adr/0011-bounded-traefik-write-surface.md.
+      PORTTA_RUNTIME_TRAEFIK_API: ${PORTTA_RUNTIME_TRAEFIK_API:-}
+      PORTTA_LOG_LEVEL: ${PORTTA_LOG_LEVEL:-INFO}
+      PORTTA_ACCESS_LOG: ${PORTTA_ACCESS_LOG:-false}
+      PORTTA_WEB_PORT: ${PORTTA_WEB_PORT:-8081}
+      PORTTA_WEB_BIND_ADDRESS: ${PORTTA_WEB_BIND_ADDRESS:-127.0.0.1}
+      PORTTA_WEB_EXPOSE: ${PORTTA_WEB_EXPOSE:-local}
+      # The panel's own front door, which is now the panel's own business.
+      #
+      # `required` makes it sign people in: accounts, roles, sessions and
+      # tokens, all in its database. `disabled` makes every request the local
+      # operator, and the process refuses to start that way on anything but
+      # loopback. The secret signs sessions and is shared with the ForwardAuth
+      # service, which is the only other thing here that signs anything.
+      #
+      # PORTTA_PANEL_URL is where a browser reaches it, and three things come
+      # from it: whether the session cookie may be `Secure`, which origins a
+      # write is accepted from, and the address the panel prints. Empty means
+      # loopback on the published port.
+      PORTTA_AUTH_MODE: ${PORTTA_AUTH_MODE:-disabled}
+      PORTTA_AUTH_SECRET: ${PORTTA_AUTH_SECRET:-}
+      PORTTA_PANEL_URL: ${PORTTA_PANEL_URL:-}
+      PORTTA_PANEL_TRUSTED_ORIGINS: ${PORTTA_PANEL_TRUSTED_ORIGINS:-}
+      PORTTA_RUNTIME_DYNAMIC_DIR: /app/state/traefik-dynamic
+      PORTTA_RUNTIME_AUTH_STORE: /app/state/auth/protections.json
+      PORTTA_RUNTIME_RUNNER_DIR: /app/state/runner
+      PORTTA_RUNTIME_ACCESS_DIR: /app/state/access
+      PORTTA_RUNTIME_SSH_DIR: /app/state/ssh
+      PORTTA_PANEL_ADVERTISED_HOST: ${PORTTA_PANEL_ADVERTISED_HOST:-}
+      TLS_ENABLED: ${TLS_ENABLED:-false}
+      TLS_MODE: ${TLS_MODE:-local}
+      ACME_EMAIL: ${ACME_EMAIL:-}
+      ACME_CA_SERVER: ${ACME_CA_SERVER:-https://acme-v02.api.letsencrypt.org/directory}
+      ACME_DNS_PROVIDER: ${ACME_DNS_PROVIDER:-cloudflare}
+      TAILSCALE_ENABLED: ${TAILSCALE_ENABLED:-false}
+      TAILSCALE_HOSTNAME: ${TAILSCALE_HOSTNAME:-portta}
+      PRIVATE_DOMAIN: ${PRIVATE_DOMAIN:-}
+      PUBLIC_ENABLED: ${PUBLIC_ENABLED:-false}
+      PUBLIC_DOMAIN: ${PUBLIC_DOMAIN:-}
+      CLOUDFLARE_ENABLED: ${CLOUDFLARE_ENABLED:-false}
+      CLOUDFLARE_ZONE: ${CLOUDFLARE_ZONE:-}
+      # The panel's only outbound integration, and its only long-lived secret
+      # that is not a Traefik credential. Off by default: with this false the
+      # panel makes no request to github.com. The private key is passed as a
+      # PATH, never as a value, because the panel can write this .env and must
+      # not be able to write the key that authenticates it.
+      #
+      # The path is the operator's: the Settings field writes it here, and this
+      # is the value the panel reads. What is fixed is the DIRECTORY, because
+      # `./state/github` below is the only place the key is mounted from; the
+      # filename is whatever GitHub called the .pem. The panel refuses a path
+      # outside that directory on save, and `portta doctor` fails on one.
+      # See docs/product/guides/github.md and docs/product/concepts/security.md.
+      GITHUB_APP_ENABLED: ${GITHUB_APP_ENABLED:-false}
+      GITHUB_APP_ID: ${GITHUB_APP_ID:-}
+      GITHUB_APP_PRIVATE_KEY_FILE: ${GITHUB_APP_PRIVATE_KEY_FILE:-/app/state/github/app.pem}
+      GITHUB_APP_WEBHOOK_SECRET: ${GITHUB_APP_WEBHOOK_SECRET:-}
+      GITHUB_API_URL: ${GITHUB_API_URL:-https://api.github.com}
+      GITHUB_SYNC_INTERVAL_MINUTES: ${GITHUB_SYNC_INTERVAL_MINUTES:-15}
+    volumes:
+      # Explicit paths from the host, and nothing else. No project directory is ever
+      # mounted here: see docs/development/adr/0001-decoupled-infrastructure.md.
+      #
+      #   .env             the configuration the Settings page edits
+      #   state/git        metadata `portta repos scan` collected, read-only
+      #   state/metrics    current.json + history from `portta host watch`
+      #   state/environment host readiness report from the same collector
+      #   state/runner     the `{ verb, project }` request the runner reads
+      #   state/access     tunnel records cleaned when a project is removed
+      #   state/github     the GitHub App private key, read-only
+      #   state/auth       credentials the panel manages, never served directly
+      #   state/ssh        SSH credentials the panel manages, never served directly
+      #   traefik/dynamic  read-write, and the ONE place the panel configures
+      #                    Traefik. It may write four generated filenames there
+      #                    and refuses every other path in its own process.
+      #                    See docs/development/adr/0011-bounded-traefik-write-surface.md.
+      - ./.env:/app/state/.env
+      - ./.env.example:/app/state/.env.example:ro
+      - ./.env-lock:/app/state/.env-lock
+      - ./state/git:/app/state/git:ro
+      - ./state/metrics:/app/state/metrics:ro
+      - ./state/environment:/app/state/environment:ro
+      - ./state/runner:/app/state/runner
+      - ./state/access:/app/state/access
+      # The GitHub App private key, read-only. Empty unless you put one there.
+      - ./state/github:/app/state/github:ro
+      - ./state/auth:/app/state/auth
+      - ./state/ssh:/app/state/ssh
+      - ./config/traefik/dynamic:/app/state/traefik-dynamic
+      # The Cloudflare Tunnel connector's generated config and its credential.
+      # Read-write because setting the tunnel up is something the panel is asked
+      # to do; the directory stays 0700 and the credentials file 0600, and the
+      # token itself is never stored anywhere else — not in .env, not in a log,
+      # not in any API response. See docs/development/adr/0025-cloudflare-tunnel.md.
+      - ./state/cloudflared:/app/state/cloudflared
+    networks:
+      # `gateway` so the panel can be published and, with the VPN overlay,
+      # routed by Traefik. `webcontrol` for the socket proxy.
+      - gateway
+      - webcontrol
+    # Deliberately no `ports:` here. Exactly one overlay decides how the panel
+    # is reached, so the two ways can never both bind the same host port:
+    #   docker/compose/features/web-bind.yaml     publishes it on PORTTA_WEB_BIND_ADDRESS
+    #   docker/compose/features/panel-public.yaml routes it through Traefik's
+    #                                             own `panel` entrypoint
+    #   docker/compose/features/panel-domain.yaml routes it on one hostname of
+    #                                             the gateway's own domain
+    labels:
+      # Off unless docker/compose/features/web-vpn.yaml turns it on: the panel is
+      # never routed through the public entrypoints by accident.
+      traefik.enable: "false"
+      portta.managed: "true"
+      portta.component: web

package/dist/runtime/docker/compose/profiles/local-tls.yaml

@@ -0,0 +1,23 @@
+# ============================================================================
+# `local` profile with HTTPS from a local CA
+# ============================================================================
+# Applied automatically when TLS_ENABLED=true and TLS_MODE=local.
+# The certificate itself is generated by `portta tls init` and offered to
+# Traefik through the file provider (config/traefik/dynamic/local-tls.yaml).
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      # Turn TLS on for the entrypoint itself, so a project gets HTTPS without
+      # a single certificate label. Without this, routers attached to :443
+      # would answer there in plaintext.
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_TLS: "true"
+      # Routers now default to :443, and :80 redirects there.
+      TRAEFIK_ENTRYPOINTS_WEB_ASDEFAULT: "false"
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_ASDEFAULT: "true"
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_TO: websecure
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_SCHEME: https
+      # Not permanent: a 301 would be cached by the browser and would outlive
+      # someone turning local TLS back off.
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_PERMANENT: "false"

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

@@ -0,0 +1,15 @@
+# ============================================================================
+# Portta: `local` profile overlay (macOS / Linux workstation)
+# ============================================================================
+# Plain HTTP on loopback, no TLS, no certificates to trust. Hostnames end in
+# `.localhost`, which resolves to loopback without touching /etc/hosts.
+#
+# Applied automatically by: ./bin/portta up local
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      # With no TLS configured, routers that do not name an entrypoint should
+      # attach to :80 only: otherwise they would also answer plaintext on :443.
+      TRAEFIK_ENTRYPOINTS_WEB_ASDEFAULT: "true"

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

@@ -0,0 +1,19 @@
+# ============================================================================
+# `remote-public` profile: the internet can reach this
+# ============================================================================
+# Opt-in, and deliberately never the default. Enabling it only changes who can
+# reach Traefik; it does not publish anything new. A service is still routed
+# only when it sets traefik.enable=true, and databases and caches are still
+# never on the shared network.
+#
+# PORTTA_BIND_ADDRESS is forced to 0.0.0.0 by the CLI for this profile.
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      # Facing the open internet, header aliasing stops being theoretical: a
+      # client can spoof a header Traefik manages if a backend normalises
+      # underscores. Strip them here rather than trusting every backend.
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_ALIASHEADERSSTRATEGY: ${PORTTA_ALIAS_HEADERS_STRATEGY:-delete}
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_ALIASHEADERSSTRATEGY: ${PORTTA_ALIAS_HEADERS_STRATEGY:-delete}

package/dist/runtime/docker/compose/profiles/remote-tls-dns.yaml

@@ -0,0 +1,26 @@
+# ============================================================================
+# ACME over DNS-01: one wildcard certificate for the whole domain
+# ============================================================================
+# The default, and the only challenge that can issue `*.example.com`. It is
+# what makes a hostname work over HTTPS *before* anything is running on it,
+# and the only option for a private gateway the ACME server can never reach:
+# Let's Encrypt has to see a TXT record, not this host.
+#
+# The cost is a DNS provider credential. `remote-tls-http.yaml` is the trade
+# in the other direction. See docs/product/guides/dns-and-tls.md.
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_TLS_DOMAINS_0_MAIN: ${PORTTA_DOMAIN}
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_TLS_DOMAINS_0_SANS: "*.${PORTTA_DOMAIN}"
+
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_DNSCHALLENGE: "true"
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_DNSCHALLENGE_PROVIDER: ${ACME_DNS_PROVIDER:-cloudflare}
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_DNSCHALLENGE_RESOLVERS: ${ACME_DNS_RESOLVERS:-1.1.1.1:53,8.8.8.8:53}
+
+      # -- DNS provider credentials ----------------------------------------
+      # Read by lego inside Traefik. Empty unless the provider is configured;
+      # a scoped token, never a global API key. See docs/product/guides/cloudflare.md.
+      CF_DNS_API_TOKEN: ${CF_DNS_API_TOKEN:-}

package/dist/runtime/docker/compose/profiles/remote-tls-http.yaml

@@ -0,0 +1,32 @@
+# ============================================================================
+# ACME over HTTP-01: one certificate per hostname, and no credential
+# ============================================================================
+# What a public gateway on a public IP can do with nothing but an A record and
+# a wildcard A record. Traefik asks for a certificate the first time a router
+# is created for a hostname, Let's Encrypt fetches a token from this host over
+# :80, and the certificate arrives a second or two later.
+#
+# No entrypoint-level `domains` here, deliberately: a wildcard SAN cannot be
+# issued this way, and asking for one makes every issuance fail. The router's
+# own rule is what names the certificate.
+#
+# What this gives up against DNS-01:
+#
+#   - :80 must be reachable from the internet. A private or VPN-only gateway
+#     cannot use this at all.
+#   - A hostname has no certificate until something answers on it, so the very
+#     first request to a new service waits for issuance.
+#   - Let's Encrypt counts certificates per registered domain, not per name.
+#     A gateway that churns through hostnames will meet the weekly limit that
+#     one wildcard never would.
+#
+# Traefik installs the challenge router ahead of the :80 -> :443 redirection
+# above, so the redirect does not swallow the challenge.
+# See docs/product/guides/dns-and-tls.md.
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE: "true"
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE_ENTRYPOINT: web

package/dist/runtime/docker/compose/profiles/remote-tls.yaml

@@ -0,0 +1,31 @@
+# ============================================================================
+# Remote profiles with TLS: the parts both ACME challenges share
+# ============================================================================
+# Applied on a remote profile when TLS_ENABLED=true, together with exactly one
+# challenge overlay: remote-tls-dns.yaml or remote-tls-http.yaml.
+#
+# Deliberately not applied when TLS is off. Redirecting to an entrypoint with
+# no usable certificate turns a working HTTP URL into a browser warning, which
+# is exactly what a host on an auto domain has: no public CA issues a wildcard
+# for sslip.io, and neither service offers the DNS-01 API one would need.
+# docker/compose/profiles/remote.yaml serves those over plain HTTP instead.
+# See docs/development/adr/0022-project-domain-modes.md.
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      # Routers that name no entrypoint attach to :443 only; :80 just redirects.
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_ASDEFAULT: "true"
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_TO: websecure
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_SCHEME: https
+      TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_PERMANENT: "true"
+
+      # TLS terminates at the entrypoint, so a project gets HTTPS without a
+      # single certificate label of its own.
+      TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_TLS_CERTRESOLVER: letsencrypt
+
+      # -- ACME ------------------------------------------------------------
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_EMAIL: ${ACME_EMAIL:-}
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_CASERVER: ${ACME_CA_SERVER:-https://acme-v02.api.letsencrypt.org/directory}
+      TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_STORAGE: /etc/traefik/acme/acme.json

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

@@ -0,0 +1,23 @@
+# ============================================================================
+# Remote profiles without TLS: plain HTTP on :80
+# ============================================================================
+# Applied on a remote profile when TLS_ENABLED=false, which is the default and
+# the only thing that works on an automatic domain: no public certificate
+# authority issues a wildcard for sslip.io or nip.io, and neither offers the
+# DNS-01 API that a wildcard needs.
+#
+# The point is what this does NOT do. The TLS overlay redirects :80 to :443
+# permanently, and doing that without a certificate the browser accepts turns a
+# URL that works into a warning page — the opposite of the goal. So a host with
+# no TLS answers on :80 and says so.
+#
+# docker/compose/profiles/remote-tls.yaml replaces this once TLS is configured.
+# ============================================================================
+
+services:
+  traefik:
+    environment:
+      # Routers that name no entrypoint attach to :80 only, exactly as they do
+      # on the local profile. Nothing answers on :443, rather than answering
+      # with a certificate nobody can verify.
+      TRAEFIK_ENTRYPOINTS_WEB_ASDEFAULT: "true"

package/dist/runtime/docker/images/README.md

@@ -0,0 +1,12 @@
+# Operational images
+
+These directories are self-contained build contexts for images used by the
+Portta runtime rather than by a Compose service directly:
+
+- `apply/` builds the opt-in applier that recreates the gateway after settings
+  change.
+- `toolbox/` builds the pinned diagnostic and database-client toolbox.
+
+Application images stay with their applications. In particular,
+`apps/web/Dockerfile` remains under `apps/web` because it builds the web and
+authentication workspaces from the repository-root context.

package/dist/runtime/docker/images/apply/Dockerfile

@@ -0,0 +1,45 @@
+# ============================================================================
+# Portta applier
+# ============================================================================
+# The one image that may drive Compose on the host, so that a settings change
+# saved in the panel can be applied without a terminal.
+#
+# It exists because Traefik reads its static configuration from the environment
+# its container was created with (docs/development/adr/0003-traefik-static-config-via-env.md):
+# a saved setting needs the containers *recreated*, and recreating them means
+# Compose, which the panel deliberately cannot reach
+# (docs/development/adr/0008-web-panel-socket-proxy.md).
+#
+# Built on demand and cached locally, like the toolbox; never published. Off
+# unless PORTTA_APPLY=true. See docs/development/adr/0026-applying-settings-from-the-panel.md.
+#
+# Node runs the packaged Portta CLI; Bash remains only for the closed project
+# runner command.
+#
+# buildx, because `up` passes --build on a repository checkout. Nothing is built
+# in here: the context is streamed over the mounted socket and the host daemon
+# does the work, with the host's network and layer cache. The plugin is only how
+# the compose CLI reaches that daemon, which is why --network none is no
+# obstacle -- and why this image needs no toolchain of its own.
+# ============================================================================
+FROM alpine:3.24.1
+
+ARG PORTTA_VERSION
+
+# Pinned base, unpinned packages: Alpine's repositories only carry the current
+# patch level for a release, so `apk add` inside 3.24.1 is already constrained.
+RUN apk add --no-cache \
+      bash \
+      nodejs \
+      docker-cli \
+      docker-cli-buildx \
+      docker-cli-compose
+
+LABEL org.opencontainers.image.title="portta-apply" \
+      org.opencontainers.image.description="Recreates Portta's own containers on the host" \
+      org.opencontainers.image.version="$PORTTA_VERSION" \
+      org.opencontainers.image.source="https://github.com/fabioassuncao/portta" \
+      org.opencontainers.image.licenses="MIT"
+
+ENTRYPOINT []
+CMD ["/bin/bash"]

package/dist/runtime/docker/images/toolbox/Dockerfile

@@ -0,0 +1,38 @@
+# ============================================================================
+# Portta toolbox
+# ============================================================================
+# One small image holding the diagnostic and client tools the gateway needs, so
+# a host only ever has to provide Docker, Git and a shell.
+#
+# Built on demand and cached locally; see `portta toolbox build`.
+# ============================================================================
+FROM alpine:3.24.1
+
+ARG PORTTA_VERSION
+
+# Pinned base, unpinned packages: Alpine's repositories only carry the current
+# patch level for a release, so `apk add` inside 3.24.1 is already constrained.
+RUN apk add --no-cache \
+      bash \
+      ca-certificates \
+      curl \
+      jq \
+      bind-tools \
+      openssl \
+      socat \
+      netcat-openbsd \
+      openssh-client \
+      postgresql-client \
+      mysql-client \
+      redis \
+      iputils \
+  && update-ca-certificates
+
+LABEL org.opencontainers.image.title="portta-toolbox" \
+      org.opencontainers.image.description="Diagnostic and client tools for Portta" \
+      org.opencontainers.image.version="$PORTTA_VERSION" \
+      org.opencontainers.image.source="https://github.com/fabioassuncao/portta" \
+      org.opencontainers.image.licenses="MIT"
+
+ENTRYPOINT []
+CMD ["/bin/bash"]