@codions/portta 0.0.0-develop.149.sha-240655c → 0.0.0-develop.150.sha-ed65081

package/dist/runtime/.env.example

@@ -182,9 +182,11 @@ 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.
+#   disabled  every request is the local operator. Legal wherever the set of
+#             people who can reach the panel is already an authenticated set:
+#             `local` (this machine), `tailscale` (a device somebody enrolled)
+#             and `vpn` (a client of the VPN). Refused at boot with `public`
+#             and `domain`, which answer whoever finds the address.
 #   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.
@@ -192,6 +194,14 @@ PORTTA_WEB_READ_ONLY=false
 # See docs/development/adr/0035-authentication-lives-in-the-panel.md and docs/product/guides/authentication.md.
 PORTTA_AUTH_MODE=disabled
 
+# The one case the access mode does not settle: `local` bound to something
+# other than loopback is the LAN, and "everyone on this Wi-Fi" is not an
+# authenticated set. Turning the login off there needs this said out loud.
+#
+# `portta doctor` warns while it is true, and refuses the combination while it
+# is not.
+PORTTA_AUTH_ALLOW_LAN=false
+
 # 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.
@@ -224,18 +234,15 @@ PORTTA_RUNTIME_DOCS=true
 # 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=
+# Panel persistence: one SQLite file under this installation, at
+# `state/panel/portta.db`. There is nothing to configure, no password to
+# generate and no service to start — the file is created on first open
+# (docs/development/adr/0037-sqlite-is-the-panel-database.md).
+#
+# This is the path INSIDE the panel container, and `state/panel` is bind-mounted
+# onto it. Changing it is for a different mount, not for a different database;
+# `portta db` operates the one this points at.
+PORTTA_RUNTIME_DATABASE_FILE=/app/state/panel/portta.db
 
 # The panel image. A normal installation pulls this; it never builds, because
 # an installed PORTTA_HOME holds no application source. Pinned like every other
@@ -410,43 +417,21 @@ CF_DNS_API_TOKEN=
 CLOUDFLARE_ZONE=
 
 # ----------------------------------------------------------------------------
-# GitHub App: optional, off by default
+# Issues: GitHub through `gh`, and Linear
 # ----------------------------------------------------------------------------
-# 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.
+# Nothing is configured here, and that is the point.
 #
-# 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.
+# The panel reads and writes issues through the host daemon, which runs the
+# GitHub CLI as whoever is signed in on the host — so the credential is `gh
+# auth`'s, kept where `gh` keeps it, and never in this file or in the panel's
+# container (docs/development/adr/0018-github-issues-through-the-gh-cli.md).
 #
-# 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.
+#   gh auth login            once, on the host
+#   portta host serve        the daemon the panel reaches it through
 #
-# Set 0 on a panel that DOES receive webhooks, where the timer would do the
-# same work twice.
-GITHUB_SYNC_INTERVAL_MINUTES=15
+# Linear is optional and works the same way: export LINEAR_API_KEY in the
+# environment that runs `portta host serve`. It is deliberately not a variable
+# here, because this file is one the panel itself can write.
 
 # ----------------------------------------------------------------------------
 # Cloudflare Tunnel: optional connector (credential stays in state/cloudflared)

package/dist/runtime/VERSION

@@ -1 +1 @@
-0.0.0-develop.149.sha-240655c
+0.0.0-develop.150.sha-ed65081

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

@@ -0,0 +1,44 @@
+# ============================================================================
+# Portta: the panel's way to the host daemon
+# ============================================================================
+# Applied whenever the panel is on.
+#
+# The panel is a container with no `gh`, no git, no tmux, no agent CLI and no
+# project directory, and ADR 0001 keeps it that way. Work that needs the host
+# runs in `portta host serve` instead, and the panel reaches it over HTTP and
+# WebSocket through its authorised proxy
+# (docs/development/adr/0047-host-daemon-and-panel-proxy.md).
+#
+# This used to ride with Task Flow, because Task Flow was the only thing that
+# needed the host. Issues need it too, and Issues are the panel's work surface
+# now (docs/development/adr/0018-github-issues-through-the-gh-cli.md) — so the
+# connection is part of having a panel, and Task Flow is left as the switch for
+# its own routes.
+#
+# What this adds to the panel, and nothing else
+# ----------------------------------------------
+#   host.docker.internal  a name for the host. Docker Desktop resolves it on
+#                         its own; on Linux `host-gateway` maps it to the
+#                         bridge gateway, which is where the daemon must bind
+#                         (PORTTA_HOST_BIND=172.17.0.1, or the address of the
+#                         bridge in use). The daemon's loopback default is not
+#                         reachable from a container on Linux.
+#   state/host/token      the daemon's token, read-only. `portta up` and
+#                         `portta web up` create it first: a bind mount of a
+#                         file that does not exist would become a directory.
+#
+# The panel never receives a project directory, a socket or the daemon's own
+# databases: only a URL and a secret. A daemon that is not running is not a
+# failure to start — it is a panel that reports which of its surfaces are
+# unavailable and why.
+# ============================================================================
+
+services:
+  web:
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      PORTTA_HOST_URL: ${PORTTA_HOST_URL:-http://host.docker.internal:${PORTTA_HOST_PORT:-5111}}
+      PORTTA_RUNTIME_HOST_TOKEN_FILE: /app/state/host/token
+    volumes:
+      - ./state/host/token:/app/state/host/token:ro

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

@@ -1,38 +1,15 @@
 # ============================================================================
-# Portta: the panel's way to the host daemon (Task Flow)
+# Portta: Task Flow
 # ============================================================================
 # Applied when PORTTA_TASKFLOW=true and the panel is on.
 #
-# Task Flow's work needs the host: git worktrees, tmux, agent CLIs and the
-# project directories. The panel is a container with none of those, and ADR
-# 0001 keeps it that way. So the work runs in `portta host serve` on the host,
-# and the panel reaches it over HTTP and WebSocket through its authorised
-# module proxy. See docs/development/adr/0047-host-daemon-and-panel-proxy.md.
-#
-# What this adds to the panel, and nothing else
-# ----------------------------------------------
-#   host.docker.internal  a name for the host. Docker Desktop resolves it on
-#                         its own; on Linux `host-gateway` maps it to the
-#                         bridge gateway, which is where the daemon must bind
-#                         (PORTTA_HOST_BIND=172.17.0.1, or the address of the
-#                         bridge in use). The daemon's loopback default is not
-#                         reachable from a container on Linux.
-#   state/host/token      the daemon's token, read-only. `portta up` and
-#                         `portta web up` create it first: a bind mount of a
-#                         file that does not exist would become a directory.
-#
-# The panel never receives a project directory, a socket or the daemon's
-# database: only a URL and a secret, and every request it forwards is checked
-# against a Portta permission first.
+# One variable, because that is all this module needs now: the connection to
+# the host daemon moved to `panel-host.yaml`, which the panel always gets, and
+# what is left here is the switch that decides whether the panel mounts Task
+# Flow's routes and sockets at all (ADR 0046).
 # ============================================================================
 
 services:
   web:
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
     environment:
       PORTTA_TASKFLOW: ${PORTTA_TASKFLOW:-false}
-      PORTTA_HOST_URL: ${PORTTA_HOST_URL:-http://host.docker.internal:${PORTTA_HOST_PORT:-5111}}
-      PORTTA_RUNTIME_HOST_TOKEN_FILE: /app/state/host/token
-    volumes:
-      - ./state/host/token:/app/state/host/token:ro

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

@@ -118,11 +118,10 @@ services:
     # 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:-}
+      # The panel's database is a file under $PORTTA_HOME, bind-mounted below.
+      # There is nothing to configure and no service to wait for: the file is
+      # created on first open (ADR 0037).
+      PORTTA_RUNTIME_DATABASE_FILE: /app/state/panel/portta.db
       PORTTA_AUTH_SIGNIN_ATTEMPTS: ${PORTTA_AUTH_SIGNIN_ATTEMPTS:-}
       ACME_CHALLENGE: ${ACME_CHALLENGE:-dns}
       ACME_DNS_RESOLVERS: ${ACME_DNS_RESOLVERS:-}
@@ -209,24 +208,6 @@ services:
       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.
@@ -237,7 +218,7 @@ services:
       #   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/panel      the panel's SQLite database, read-write and its own
       #   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
@@ -252,8 +233,11 @@ services:
       - ./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
+      # The panel's own database. A directory rather than the file, because
+      # SQLite in WAL mode is three files and creates two of them itself — a
+      # bind mount of one path would leave the -wal and -shm inside the
+      # container, which is how a restart loses the most recent writes.
+      - ./state/panel:/app/state/panel
       - ./state/auth:/app/state/auth
       - ./state/ssh:/app/state/ssh
       - ./config/traefik/dynamic:/app/state/traefik-dynamic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codions/portta",
-  "version": "0.0.0-develop.149.sha-240655c",
+  "version": "0.0.0-develop.150.sha-ed65081",
   "description": "Machine-first CLI for a shared Docker development gateway",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
     "@clack/prompts": "^1.1.0",
     "@devcontainers/cli": "0.89.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "better-sqlite3": "^13.0.3",
+    "better-sqlite3": "^12.11.1",
     "commander": "14.0.2",
     "execa": "9.6.1",
     "pi-acp": "^0.0.33",

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

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

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

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