Install authenticated native web proxy with user autostart

Register the existing native supervisor with launchd/systemd, include the dependency-free authenticated web proxy, detect Node, and keep the API loopback by default. Preserve existing web credentials and configured host harness defaults. Clarify single-step setup, lifecycle selection, and optional ntfy limits.

Checks: 44 mocked native installer/lifecycle tests; 8 entrypoint tests; 42 Docker installer tests; GOPROXY=off GOTOOLCHAIN=local go test ./internal/installation ./cmd/pipelines; sh -n install install.sh; git diff --check. No live install, deployment, restart, downloads, real autostart/login verification or native Linux verification.
This commit is contained in:
2026-10-20 21:30:07 +01:00
parent b56d6af180
commit ae6ba6ae10
6 changed files with 397 additions and 46 deletions
+111 -21
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""Install Pipelines natively on the host (macOS and Linux).
The installer only detects the tools it needs (go, python3, git, curl and a C
The installer only detects the tools it needs (go, python3, node, git, curl and a C
compiler for ntfy's SQLite driver); it never installs or upgrades them, and it
never installs, upgrades or downloads OpenCode or Pi. It builds the server, CLI
and ntfy from source into a per-user prefix, generates an ntfy configuration that
@@ -16,6 +16,9 @@ import importlib.util
import ipaddress
import json
import os
import platform
import plistlib
import secrets
import shutil
import subprocess
import sys
@@ -40,7 +43,8 @@ tokens = module("save_ntfy_token", "save-ntfy-token.py")
DEFAULT_PREFIX = Path.home() / ".local/share/pipelines"
MARKER = "pipelines-install.json"
LABEL = "net.a-wan.pipelines"
REQUIRED_TOOLS = ("go", "python3", "git", "curl")
SERVICE_MARKER = "Managed by Pipelines native installer"
REQUIRED_TOOLS = ("go", "python3", "git", "curl", "node")
# ntfy's SQLite driver (mattn/go-sqlite3) is cgo, so a C compiler is required to
# build the server. Upstream's macOS release asset is client-only, so both
# platforms compile ntfy from the pinned Go module.
@@ -48,11 +52,8 @@ C_COMPILERS = ("cc", "clang", "gcc")
NTFY_BUILD_TAGS = "sqlite_omit_load_extension,osusergo,netgo"
DEFAULT_NTFY_PORT = 8090
DEFAULT_SERVER_PORT = 8080
# The phone client reaches the server over the LAN, matching the Docker install
# (which published 0.0.0.0). Use --bind-address 127.0.0.1 for a loopback-only
# server; the Pipelines API has no authentication, so keep it on a trusted
# LAN/VPN either way.
DEFAULT_BIND_ADDRESS = "0.0.0.0"
# Only the authenticated web proxy is exposed; the control API stays loopback.
DEFAULT_BIND_ADDRESS = "127.0.0.1"
class Setup:
@@ -100,6 +101,51 @@ class Setup:
pi = shutil.which("pi")
return {"opencode": str(Path(opencode).resolve()), "pi": str(Path(pi).resolve()) if pi else ""}
def service_path(self):
system = platform.system()
if system == "Darwin":
path = Path.home() / "Library/LaunchAgents" / (LABEL + ".plist")
tool = "launchctl"
elif system == "Linux":
root = Path(self.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
path = root / "systemd/user" / (LABEL + ".service")
tool = "systemctl"
else:
raise ValueError("Native installation supports macOS (launchd) and Linux (systemd --user) only")
if not shutil.which(tool):
raise ValueError(f"{tool} is required for login autostart; run setup in a logged-in user session")
if path.is_symlink() or (path.exists() and SERVICE_MARKER not in path.read_text()):
raise ValueError(f"Refusing to replace an unmanaged autostart definition: {path}")
return path
def register_service(self, path, manifest):
"""Register the paired native services, not a second standalone server."""
prefix = Path(manifest["prefix"])
command = [manifest["python"], str(prefix / "lib/manage.py"),
"supervise", "--prefix", str(prefix)]
if platform.system() == "Darwin":
content = plistlib.dumps({
"Label": LABEL, "Comment": SERVICE_MARKER,
"ProgramArguments": command, "RunAtLoad": True,
"KeepAlive": {"SuccessfulExit": False}, "ThrottleInterval": 5,
"EnvironmentVariables": {"HOME": str(Path.home()), "PATH": manifest["path"]},
"StandardOutPath": str(prefix / "logs/supervisor.log"),
"StandardErrorPath": str(prefix / "logs/supervisor.log"), "Umask": 0o077,
})
else:
def quote(value):
if any(char in value for char in "\r\n\x00"):
raise ValueError("Autostart paths cannot contain line breaks or NUL")
return '"' + value.replace('\\', '\\\\').replace('"', '\\"').replace('%', '%%').replace('$', '$$') + '"'
content = (f"# {SERVICE_MARKER}\n[Unit]\nDescription=Pipelines native services\n"
"\n[Service]\nType=simple\nExecStart=" + " ".join(map(quote, command))
+ "\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=90\nUMask=0077\n"
"\n[Install]\nWantedBy=default.target\n").encode()
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
self._write_atomic(path, content, 0o600)
manifest["registration"] = str(path)
# --- host harness profiles ------------------------------------------
MODEL_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_./:-"
@@ -154,15 +200,19 @@ class Setup:
if not harness_model or not pipeline_model:
continue
# Host mode: no docker_directory, executable is the detected host binary.
merged[name] = {"executable": harness[name], "model": harness_model, "pipeline_model": pipeline_model}
profile = dict(current)
profile.pop("docker_directory", None)
profile.update(executable=harness[name], model=harness_model, pipeline_model=pipeline_model)
merged[name] = profile
configured.append(name)
if not configured:
print("Host harness profiles were not written: no valid model was found for "
+ ", ".join(order) + ". Run 'pipelines harness setup opencode --host' to configure authoring.")
return None
# Prefer the primary detected harness, so a stale Docker-era default ("pi")
# never survives a native install.
default = "opencode" if "opencode" in configured else configured[0]
# Keep a configured host default; only a stale Docker default must change.
default = existing.get("default")
if default not in configured or profiles.get(default, {}).get("docker_directory"):
default = "opencode" if "opencode" in configured else configured[0]
data = dict(existing)
data["default"] = default
data["profiles"] = merged
@@ -193,6 +243,36 @@ class Setup:
os.chmod(target, 0o700)
return target
def configure_web(self, prefix, args):
node = str(Path(shutil.which("node")).resolve())
version = self.runner([node, "--version"], capture_output=True, text=True)
try:
major = int(version.stdout.strip().removeprefix("v").split(".")[0])
except (ValueError, AttributeError):
major = 0
if version.returncode or major < 18:
raise ValueError("Node.js 18 or newer is required for the authenticated web proxy")
# Reuse the proxy's existing credential location; never disable its gate.
auth = Path(self.environ.get("PIPELINES_WEB_AUTH_FILE")
or Path.home() / ".config/pipelines/web-auth.json").expanduser().resolve()
if auth.exists():
data = json.loads(auth.read_text())
if (not isinstance(data, dict) or not isinstance(data.get("password"), str)
or len(data["password"]) < 8 or not isinstance(data.get("secret"), str)
or len(data["secret"]) < 32):
raise ValueError(f"Invalid existing web auth file; retained unchanged: {auth}")
if auth.stat().st_mode & 0o077:
raise ValueError(f"Web auth file must be private (chmod 600): {auth}")
else:
auth.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
self._write_atomic(auth, (json.dumps({"password": secrets.token_urlsafe(18),
"secret": secrets.token_urlsafe(48)}) + "\n").encode(), 0o600)
target = prefix / "lib/web"
shutil.copytree(Path(__file__).resolve().parents[1] / "web", target, dirs_exist_ok=True,
ignore=shutil.ignore_patterns("test", "node_modules", ".DS_Store"))
return {"node": node, "script": str(target / "serve.mjs"),
"auth_file": str(auth), "host": args.web_host, "port": args.web_port}
# --- build and skill -------------------------------------------------
def build(self, prefix):
@@ -493,20 +573,26 @@ class Setup:
raise ValueError("Invalid ntfy port; choose a value between 1024 and 65535")
if args.ntfy_port == args.port:
raise ValueError("The server and ntfy ports must differ")
if not 1024 <= args.web_port <= 65535 or args.web_port in (args.port, args.ntfy_port):
raise ValueError("Web port must be between 1024 and 65535 and differ from server/ntfy ports")
try:
ipaddress.IPv4Address(args.bind_address)
ipaddress.IPv4Address(args.web_host)
except ValueError:
raise ValueError("Invalid bind address; use an IPv4 address such as 0.0.0.0 or 127.0.0.1") from None
raise ValueError("Invalid API/web bind address; use an IPv4 address such as 0.0.0.0 or 127.0.0.1") from None
prefix = self.resolve_prefix()
self.prepare_layout(prefix)
harness = self.harness()
service_path = self.service_path()
# Reuse an already built ntfy binary and skip the release lookup, so a
# reinstall with the same version makes no network requests at all.
installed = self._existing_ntfy_version(prefix)
if (prefix / "bin/ntfy").is_file() and installed:
resolution = {"module": release_lookup.NTFY_MODULE, "version": installed, "tag": installed}
else:
self.require_compiler()
resolution = self.resolve_ntfy()
self.prepare_layout(prefix)
web = self.configure_web(prefix, args)
self.build(prefix)
self.check_path_shadow(prefix)
self.install_skill(prefix)
@@ -561,7 +647,9 @@ class Setup:
"ntfy": {"mode": "native", "bin": str(prefix / "bin/ntfy"),
"config": str(config_path), "base_url": base_url,
"version": resolution.get("tag") or resolution.get("version")},
"web": web,
}
self.register_service(service_path, manifest)
self.write_manifest(prefix, manifest)
# Save the address the host CLI/TUI dials by default, so a plain
# `pipelines` (or its TUI) reaches this installation instead of a stale
@@ -579,16 +667,17 @@ class Setup:
if started.returncode:
raise ValueError(
"The native services were installed but could not be started; run "
f"'{prefix}/bin/pipelines start' to see the error. Check that ports "
f"{args.port} and {args.ntfy_port} are free (a running Docker installation uses them).")
print(f"ntfy is configured for {base_url} and both services are running.")
f"'PIPELINES_PREFIX={prefix} {prefix}/bin/pipelines start' to see the error. "
"Check your login service manager and that ports "
f"{args.port}, {args.ntfy_port} and {args.web_port} are free (a running Docker installation may use them).")
print(f"ntfy is configured for {base_url}; server, web proxy and ntfy have login autostart ({service_path}).")
print(f"Web: http://{lan_ip if args.web_host == '0.0.0.0' else args.web_host}:{args.web_port}/ "
f"(sign-in password in {web['auth_file']}; existing credentials retained).")
if args.bind_address == "0.0.0.0":
print(f"Phone client server URL: ws://{lan_ip}:{args.port}/connect "
"(use a workspace path that exists on this server).")
else:
print(f"Server bound to {args.bind_address}:{args.port}; a phone on the LAN needs a LAN bind "
"(re-run with --bind-address 0.0.0.0).")
print("Create the phone account password if it is a new account, then subscribe to the pipelines topic.")
print(f"Unauthenticated API bound to {args.bind_address}:{args.port}; use the authenticated web URL.")
def arguments(argv=None):
@@ -597,9 +686,10 @@ def arguments(argv=None):
parser.add_argument("--ntfy-url", help="Override the auto-detected LAN ntfy address")
parser.add_argument("--timezone", help="Override the detected timezone (fallback: UTC)")
parser.add_argument("--port", type=int, default=DEFAULT_SERVER_PORT, help="Pipelines server port")
parser.add_argument("--web-port", type=int, default=8082, help="Authenticated web proxy port (default 8082)")
parser.add_argument("--web-host", default="0.0.0.0", help="Web proxy bind address (default 0.0.0.0)")
parser.add_argument("--bind-address", default=DEFAULT_BIND_ADDRESS,
help="Server bind address (default 0.0.0.0, the LAN, so the phone client can reach it; "
"use 127.0.0.1 for a loopback-only server)")
help="Unauthenticated server bind address (default 127.0.0.1; expose only the web proxy)")
parser.add_argument("--ntfy-port", type=int, default=DEFAULT_NTFY_PORT, help="ntfy listen port")
parser.add_argument("--model", help="Record an explicit default model; otherwise host OpenCode configuration is reused")
parser.add_argument("--replace-data", action="store_true",