First-run setup in one step, and the dashboard stays private until you open it

The first time you open Pingularity there's now a short Quick Setup: it asks how
often to run speed tests, who can reach the dashboard, whether to check for
updates, and optionally sets a login - then applies all of it at once. Nothing
starts probing your connection until you've said go, and you can change any of it
later in Settings.

The dashboard now starts private everywhere - it answers only the machine it's
running on until you decide otherwise. That includes Docker, which used to open
itself to the network by guessing at the setup; it no longer guesses. To reach
Pingularity from other devices, turn on network access in Settings or start it
with -access network (in a container, -e PINGULARITY_ACCESS=network), and set a
login. A container's published port stays closed until you do, so it can't be
exposed by accident.

Fixes that came with it:
- The browser's own login popup no longer appears on top of Pingularity's, and if
  your session expires mid-download you're sent to the app's login, not the
  browser's. "Redact PII" now downloads the masked log, not the raw one.
- Quick Setup works with a keyboard and a screen reader, and a login that pops up
  over it is usable instead of stuck behind it.
- Saving one setting no longer quietly re-saves all the others (which could pin a
  value you'd set on the command line).
- Automatic speed tests pick a server that actually answers instead of ranking an
  unreachable one first, don't run twice right after startup, and read FreeBSD's
  congestion-control list correctly.
- A backup too big for the browser now tells you to copy the database file or
  fetch it with curl, instead of freezing the tab.
- Self-built container images stop warning about a data directory they never
  touched, and a malformed release tag is refused instead of shipping the wrong
  thing.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cansofgrease

.github/workflows/release.yml

@@ -3,6 +3,12 @@ name: Release
 on:
   push:
     tags: ['v*']
+  # Manual escape hatch for a stranded tag: the 2026-08-06 Actions outage
+  # throttled webhooks and the TAG event never replayed (push events did, tag
+  # events do not), leaving a pushed tag with no release run - the remedy was
+  # deleting and re-pushing the tag. With this, dispatch the workflow AT the
+  # tag ref instead (Actions UI -> Release -> Run workflow -> pick the tag).
+  workflow_dispatch:
 
 # Only one release run per tag at a time. Re-cutting a tag (delete + re-push, as the
 # rc loop does) cancels the in-flight run instead of racing it, which otherwise
@@ -19,6 +25,19 @@ jobs:
   guard:
     runs-on: ubuntu-latest
     steps:
+      # workflow_dispatch (the stranded-tag escape hatch) can fire on a BRANCH,
+      # and a branch may be NAMED like a version - the SemVer check below reads
+      # GITHUB_REF_NAME and would pass it, while GoReleaser publishes the git tag
+      # at HEAD instead. On a v-named branch whose HEAD sits on an existing
+      # release tag that would OVERWRITE a shipped release. Refuse anything that
+      # is not a tag ref outright, before any checkout or token use.
+      - name: Require a tag ref
+        run: |
+          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
+            echo "::error::release runs only on a tag ref (got ${GITHUB_REF_TYPE} '${GITHUB_REF_NAME}'); dispatch the workflow with a tag ref, not a branch"
+            exit 1
+          fi
+
       # The trigger glob 'v*' also matches junk like 'v', 'vtest', or 'v1.2' - a
       # stray or malformed tag must not cut a release. Enforce a proper SemVer
       # grammar (leading v) before any checkout or token use. This is a regex, not a
@@ -31,9 +50,21 @@ jobs:
           tag="${GITHUB_REF_NAME}"
           semver='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?$'
           if ! printf '%s' "$tag" | grep -Eq "$semver"; then
-            echo "::error::tag '$tag' is not a valid SemVer tag (vMAJOR.MINOR.PATCH[-prerelease][+build]); refusing to release"
+            echo "::error::tag '$tag' is not a valid SemVer tag (vMAJOR.MINOR.PATCH[-prerelease]); refusing to release"
             exit 1
           fi
+          # SemVer permits +build metadata, but this pipeline CANNOT ship it
+          # safely: the prerelease test below is a shell `*-*` glob, and build
+          # metadata like +build-1 contains a hyphen, so a STABLE tag with build
+          # metadata would be misread as a prerelease and skip the immutable-
+          # stable overwrite guard. Docker tags reject '+' outright as well.
+          # Reject build metadata here rather than silently mishandle it.
+          case "$tag" in
+            *+*)
+              echo "::error::tag '$tag' carries +build metadata, which this release pipeline does not support (it breaks the stable/prerelease split and Docker tagging); cut vMAJOR.MINOR.PATCH[-prerelease] instead"
+              exit 1
+              ;;
+          esac
 
       # Stable releases are immutable: their checksums are attested in the publish
       # job, so silently overwriting a published stable asset would invalidate that
@@ -83,6 +114,19 @@ jobs:
         with:
           go-version-file: go.mod
 
+      # GoReleaser publishes the tag it resolves at HEAD (git describe --exact-match),
+      # not GITHUB_REF_NAME. The guard job validated the ref name; assert they are the
+      # same tag here, so a dispatch can never publish a DIFFERENT release than the one
+      # that passed the guards.
+      - name: Assert HEAD tag matches the ref
+        run: |
+          head_tag="$(git describe --exact-match --tags HEAD)" || {
+            echo "::error::HEAD is not on an exact tag; refusing to release"; exit 1; }
+          if [ "$head_tag" != "${GITHUB_REF_NAME}" ]; then
+            echo "::error::HEAD tag '$head_tag' != ref '${GITHUB_REF_NAME}'; the release would publish a different version than was guarded"
+            exit 1
+          fi
+
       - name: Log in to GHCR
         uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:

Dockerfile

@@ -32,7 +32,13 @@ ARG TARGETPLATFORM
 COPY $TARGETPLATFORM/pingularity /pingularity
 # +ep: effective+permitted, so the cap is raised automatically on exec even for
 # a non-root user. `mkdir /data` seeds the data dir the final stage chowns.
-RUN setcap cap_net_raw+ep /pingularity && mkdir -p /data
+# The .pingularity-image-dir marker is a volume-lineage HEURISTIC (not a proof
+# of volume type): Docker's copy-up carries it into a fresh named volume, so the
+# daemon's container carve-out (store.go) can tell content that came from OUR
+# image from an empty PVC or a plain bind-mounted host directory, which never
+# carry it. A bind mount restored FROM a marked volume would carry it too - an
+# accepted edge, since the content is genuinely ours.
+RUN setcap cap_net_raw+ep /pingularity && mkdir -p /data && touch /data/.pingularity-image-dir
 
 # --- final image: distroless nonroot, carrying the capped binary ---
 FROM gcr.io/distroless/static-debian13:nonroot@sha256:f7f8f729987ad0fdf6b05eeeae94b26e6a0f613bdf46feea7fc40f7bd72953e6

Dockerfile.iperf

@@ -36,7 +36,13 @@ COPY $TARGETPLATFORM/pingularity /pingularity
 # preserves the security.capability xattr across the COPY into the final image
 # (same guarantee the default Dockerfile relies on), so the final stage needs no
 # libcap2-bin of its own.
-RUN setcap cap_net_raw+ep /pingularity && mkdir -p /data
+# The .pingularity-image-dir marker is a volume-lineage HEURISTIC (not a proof
+# of volume type): Docker's copy-up carries it into a fresh named volume, so the
+# daemon's container carve-out (store.go) can tell content that came from OUR
+# image from an empty PVC or a plain bind-mounted host directory, which never
+# carry it. A bind mount restored FROM a marked volume would carry it too - an
+# accepted edge, since the content is genuinely ours.
+RUN setcap cap_net_raw+ep /pingularity && mkdir -p /data && touch /data/.pingularity-image-dir
 
 # --- final image: debian-slim carrying iperf3 + the capped binary ---
 FROM debian:13-slim@sha256:020c0d20b9880058cbe785a9db107156c3c75c2ac944a6aa7ab59f2add76a7bd
@@ -65,6 +71,13 @@ COPY --from=setcap /pingularity /pingularity
 # 0755 (COPY does not carry the source mode across) and the daemon spends every
 # start warning that its own data directory is readable by others.
 COPY --from=setcap --chown=65532:65532 --chmod=0700 /data /var/lib/pingularity
+# Belt and braces: some BuildKit versions apply COPY --chmod to the files but
+# not the directory itself (observed: buildx honors it, ubuntu-latest's plain
+# docker build does not), and this image HAS a shell to correct it. The
+# distroless default image cannot RUN anything; its published buildx output is
+# verified 0700, and the daemon tightens its own container data dir at boot
+# either way (store.go's container carve-out).
+RUN chmod 0700 /var/lib/pingularity
 EXPOSE 9000
 VOLUME /var/lib/pingularity
 USER pingularity

README.md

@@ -21,13 +21,14 @@ go build -o pingularity .   # requires Go 1.25.12+; pure Go, no cgo
 ./pingularity               # probes every 5s; UI on http://localhost:9000
 ```
 
-No flags needed. The UI binds `:9000` by default, but a fresh native install
-starts **private**: a built-in filter answers only the machine it runs on, and
-other devices get `403` until you flip **Network access** on in the settings
-drawer's Access tab (flip it on and hit Save; the tab shows the address to use). Docker
-installs skip the filter - it can't work behind container networking - so
-there the dashboard is LAN-reachable immediately. `-listen 127.0.0.1:9000`
-hard-pins it to local-only at the socket level.
+No flags needed. The UI binds `:9000` by default, but every install starts
+**private**: a built-in filter answers only the machine it runs on, and other
+devices get `403` until you flip **Network access** on in the settings drawer's
+Access tab (flip it on and hit Save; the tab shows the address to use), or start
+with `-access network`. This is true in a container too - a published port
+returns `403` until you set `-access network` (or `-e PINGULARITY_ACCESS=network`),
+so a container is never accidentally exposed. `-listen 127.0.0.1:9000` hard-pins
+it to local-only at the socket level regardless.
 
 Connectivity is probed over **both IPv4 and IPv6** (each as an independent
 quorum of three anycast anchors). IPv6 is auto-detected - skipped on IPv4-only
@@ -191,6 +192,14 @@ The image is multi-arch (amd64 + arm64). Two flags matter:
   Exit row shows as unavailable (everything else still works). Spelling it out
   keeps the command correct everywhere.
 
+> **Reaching the dashboard from other devices.** Every install starts
+> loopback-only, containers included - it is never guessed open from the network
+> setup. With `--network=host` the dashboard answers on the *host's*
+> `localhost:9000`, but other devices on your LAN get `403` until you opt in with
+> `-access network` (or `-e PINGULARITY_ACCESS=network`) - set a login at the same
+> time. A bridged container that publishes a port with `-p` needs the same flag,
+> or the published port returns `403`.
+
 The **`-v pingularity-data:/var/lib/pingularity`** volume is what makes updates
 safe: the SQLite database *and* `pingularity.key` (which encrypts saved iperf3
 passwords) live there. Skip the volume and a `docker pull` + recreate throws
@@ -623,8 +632,12 @@ and persist across restarts:
   config / latency / speed / downtime, export them to a JSON file, and import one
   back - time-series data is **merged** (existing/newer local rows are kept, only
   missing rows are added) while **config is overwritten** and reloaded live.
-  Both ends stream, so even a multi-hundred-MB export of years of history
-  round-trips. The import warns you when it matters: restored rows older than
+  Both ends stream on the wire, but the *browser* download buffers the file in
+  memory, so a very large backup (years of dense history) can outgrow the tab -
+  the dashboard stops and says so rather than hanging. For one that big, copy the
+  SQLite database file at the `-db` path (that single file *is* the complete
+  backup), or stream `/api/export` straight to disk with `curl -OJ` (add
+  `-u user:pass` when a login is set). The import warns you when it matters: restored rows older than
   your current retention windows will be pruned within the hour (raise
   retention first to keep them), and a config restore that carried "login on"
   without a password leaves login off until you set one.
@@ -640,15 +653,12 @@ and persist across restarts:
 - **Access** → access controls (changes here apply on **Save**).
   **Network access** decides whether other devices can reach the dashboard /
   API / `/metrics`, or only this machine - a live loopback filter, so remote
-  clients get 403. It starts **off on native installs** (localhost-only until
-  you flip it) and **on in Docker**. In a *bridged* container the network hides
-  who a request really came from, so there the filter cannot be enforced -
-  publish the port narrowly and use the login password instead (the API reports
-  the difference as `local_only` vs `local_only_active`, and the tab says so). A
-  `--network=host` container sees real peer addresses, so local-only is enforced
-  there exactly as on a native install. The tab shows the **reachable
-  address(es)** with port plus a static-IP hint. **Require login** (off by
-  default) gates
+  clients get 403. It starts **off everywhere** (localhost-only until you flip
+  it), containers included: the loopback filter is enforced the same way in every
+  environment, and a container that must be reachable opts in explicitly with
+  `-access network` (or `-e PINGULARITY_ACCESS=network`) rather than being guessed
+  open. The tab shows the **reachable address(es)** with port plus a static-IP
+  hint. **Require login** (off by default) gates
   everything behind a password: browsers get a login form + session cookie,
   while API clients and Prometheus use HTTP Basic with the same credentials
   (passwords are capped at 72 bytes, the bcrypt limit). Failed logins are
@@ -733,6 +743,7 @@ the settings drawer afterward and persists across restarts.
 | Flag | Default | Purpose |
 | --- | --- | --- |
 | `-listen` | `:9000` | UI + metrics address (`127.0.0.1:9000` = local-only at the socket) |
+| `-access` | `local` | who may open the dashboard: `local` (loopback only) or `network` (reachable from the LAN - set a login). A container that publishes a port needs `network` (or `PINGULARITY_ACCESS=network`), or the published port returns 403. Also settable in the UI |
 | `-db` | per-OS ([details](#run-in-the-background-systemd--launchd--windows-service)) | SQLite path (dir auto-created) |
 | `-interval` | `5s` | time between probe rounds, `1s`-`1h` (a value saved in the UI takes precedence) |
 | `-timeout` | `3s` | per-target dial timeout, `1s`-`30s` (a value saved in the UI takes precedence) |
@@ -747,10 +758,19 @@ the settings drawer afterward and persists across restarts.
 | `-allow-host` | *(none)* | extra `Host` header values the DNS-rebinding guard accepts - only needed behind a reverse proxy on a public domain |
 | `-trusted-proxy` | *(none)* | proxy IPs/CIDRs whose `X-Forwarded-For` identifies the real client, so one visitor's failed logins can't rate-limit everyone behind the proxy |
 | `-metrics-token` | *(none)* | optional read-only token a scraper presents to `/metrics` (Bearer or Basic password) instead of the admin login, so Prometheus needn't hold an account that can change settings; only consulted when Require login is on |
+| `-quick-setup` | `prompt` | headless first-run: `skip` starts monitoring immediately and never shows the browser Quick Setup dialog; `prompt` leaves it for a first visit |
 
 Out-of-range numeric flags are rejected at startup (and at `pingularity
 install`) rather than silently adjusted.
 
+> **Headless installs:** a genuinely fresh install waits (monitoring paused) for
+> a first-run consent - either the browser **Quick Setup** dialog or an explicit
+> flag - so it never starts probing before someone has said to. Passing any
+> monitoring flag (`-speedtest`, `-speedtest-interval`, `-latency`, `-interval`)
+> counts as that consent; if you only tune other knobs (say `-timeout` or
+> `-ipv6`) pass `-quick-setup=skip` so the service starts monitoring at boot
+> instead of holding for the dialog.
+
 ## Metrics (optional)
 
 > **Grafana users:** there is an official importable dashboard (latency
@@ -1064,7 +1084,11 @@ constant memory.
   uptime to report, exactly as `pingularity_uptime_ratio` is then absent. A
   running speedtest is reported as `speedtest_running` plus `speedtest_run_id`
   (`0` when idle) - that id is what `/api/speedtest/abort` takes, so a stop can
-  name the run it was decided against
+  name the run it was decided against. A fresh install awaiting first-run consent
+  reports `quick_setup_pending`, and `access_local_only` mirrors the loopback-only
+  access filter (so a client can default the Quick Setup access choice to how the
+  install booted); `bridged_container` is present only in a bridged container,
+  where measurements describe the container network rather than the host's
 - `GET /api/series?mins=…[&exclude=…]` - latency / online time series (server-side
   bucketed); `exclude` drops targets from the lowest-latency line. Also takes an
   absolute window as `?from=&to=` (unix seconds, half-open `[from, to)`; omit `to`
@@ -1121,6 +1145,13 @@ constant memory.
   has already measured a server keeps that result; an abort before the first
   result stores nothing
 - `GET|POST /api/monitoring` - read / set `{enabled}` master start/stop (the power toggle)
+- `POST /api/quick-setup` - apply the first-run **Quick Setup** answer in ONE
+  transaction (speedtest cadence, network access, update check, and an optional
+  login) and mark it answered so the dialog never returns; `{dismiss:true}` marks
+  it answered without changing anything else. `auth_enabled` must agree with
+  whether a `password` is sent, and it refuses (`403`) once a login is already
+  configured - change access under Settings then. Fresh installs only; the offer
+  is `quick_setup_pending` in `/api/status`
 - `GET|POST /api/update` - update-check status / toggle the daily release poll
 - `GET|POST /api/logs` - the About-tab log viewer: read recent lines (or
   `?download=1` for a text file, still the complete buffer) / set log level, PII
@@ -1171,6 +1202,14 @@ constant memory.
 > and the database file `0600` (owner-only).
 > Keep it that way if you relocate the DB with `-db`.
 >
+> **Legacy Docker volumes:** the database file is always owner-only, but a named
+> volume created by an *older* image may have a group/world-readable directory
+> root (Docker's volume copy-up loosens it), and Pingularity won't silently
+> re-lock a directory it can't prove is its own - so it logs a one-line notice on
+> start instead. The data is already private; to clear the notice, tighten the
+> directory once: `docker exec <container> chmod 700 /var/lib/pingularity`. Fresh
+> volumes are recognized automatically and need nothing.
+>
 > The full picture - what the trust boundary is, what privilege each install
 > channel runs with, what the defaults protect and how to deploy it safely - is in
 > [docs/security-model.md](docs/security-model.md). To report a vulnerability,

RELEASING.md

@@ -18,9 +18,13 @@ git push origin v1.2.3
 
 The `-X main.version=` ldflag is set from the tag, so `pingularity version`
 reports `1.2.3`. Use a valid SemVer tag with a leading `v`
-(`vMAJOR.MINOR.PATCH`, optionally `-prerelease`/`+build`). The release workflow
-guards the tag with a SemVer regex and refuses the obviously malformed shapes
-(bare `v`, `v1.2`, leading-zero identifiers) before it does anything - but that
+(`vMAJOR.MINOR.PATCH`, optionally `-prerelease`). Do **not** append `+build`
+metadata: SemVer allows it, but the workflow rejects it, because the hyphen in
+a value like `+build-1` makes the stable-vs-prerelease shell test misfire (a
+stable tag would skip the immutable-release guard) and Docker tags cannot carry
+`+` at all. The release workflow guards the tag with a SemVer regex and refuses
+the obviously malformed shapes (bare `v`, `v1.2`, leading-zero identifiers, and
+any `+build` metadata) before it does anything - but that
 regex is *close to*, not exactly, SemVer, so a pathological tag can still slip
 past it and is then rejected by GoReleaser itself. Either way, a tag that is not
 valid SemVer would never register as "newer" with running installs, because the

defaults_test.go

@@ -32,7 +32,7 @@ func TestDefaultSettings(t *testing.T) {
 		SpeedtestOnReconnect: true,
 		IPv6Mode:             "on",
 	}
-	v := defaultSettings(cfg, false)
+	v := defaultSettings(cfg)
 
 	// Mapping: each distinct input lands on its own field. A swap flips one of these.
 	checks := []struct {
@@ -89,13 +89,20 @@ func TestDefaultSettings(t *testing.T) {
 		t.Errorf("DegradedPingMS/SpeedBusyMbps = %v/%v, want 150/5", v.DegradedPingMS, v.SpeedBusyMbps)
 	}
 
-	// AccessLocalOnly: on for a native install (LAN opt-in), off in a container
-	// (unenforceable there). The containerized inversion is easy to get backwards.
-	if !defaultSettings(cfg, false).AccessLocalOnly {
-		t.Error("native install must default AccessLocalOnly=true (LAN access opt-in)")
-	}
-	if defaultSettings(cfg, true).AccessLocalOnly {
-		t.Error("container install must default AccessLocalOnly=false (filter unenforceable)")
+	// Access is EXPLICIT, not guessed: loopback-only by default everywhere, and
+	// off ONLY when the operator set -access network. No container heuristic.
+	if !defaultSettings(cfg).AccessLocalOnly {
+		t.Error("default (no -access) must be loopback-only everywhere, containers included")
+	}
+	net := cfg
+	net.Access = "network"
+	if defaultSettings(net).AccessLocalOnly {
+		t.Error("-access network must default AccessLocalOnly=false")
+	}
+	loc := cfg
+	loc.Access = "local"
+	if !defaultSettings(loc).AccessLocalOnly {
+		t.Error("-access local must default AccessLocalOnly=true")
 	}
 }