home-hosted 0.7.3 → 0.7.4

package/AGENTS.md

@@ -277,10 +277,12 @@ either is a last resort, and never an accidental one.
   boot through `.state/<id>.json` before any port preflight (`nannyIsAlive` = live pid **and** a fresh
   heartbeat, the `HHOSTED_SERVER_ID` marker or the argv), tails that file for live logs, and reads
   `lastExit` once so a crash nobody watched is reported. The spawn spec is consumed by the read and
-  swept at boot — it carries expanded env. Two lifetimes are pinned: the nanny **exits with its child**
+  swept at boot — it carries expanded env. Three lifetimes are pinned: the nanny **exits with its child**
   (an inherited pipe would keep it alive, and the panel would report a healthy entry whose server is a
-  detached stranger), and a stop reaches the child by pid from the state file, because `SIGKILL` and
-  `killGroup: false` cannot be forwarded — which is why a self-restarting program belongs on `reclaim`.
+  detached stranger), a stop reaches the child by pid from the state file, because `SIGKILL` and
+  `killGroup: false` cannot be forwarded — which is why a self-restarting program belongs on `reclaim` —
+  and its `SIGTERM`/`SIGINT` traps are armed *before* the child exists and before that state file
+  appears, so a stop that beats the spawn can never orphan a child nobody has a record of.
   The nanny never restarts anything: retries and health stay the supervisor's. `logs.persist: false`
   keeps that file out of the Logs page but never stops it being written — it is the transport.
 - **A port is only ever freed by re-listing its listeners.** `POST /api/servers/:id/free-port` never

package/README.md

@@ -25,7 +25,7 @@ them, watches them, restarts what dies, and shows you one page of what is going
 
 <div align="center">
 
-![Six views of the panel: the stock UI, the NOC-console, and UI examples](docs/media/tour.gif)
+![Eight views of the panel: the stock UI and its reverse proxy, the NOC-console, and UI examples](docs/media/tour.gif)
 
 <sub>The stock panel, the [NOC-console](./uis/noc-console) that ships alongside it (for TUI and
 shortcuts wizards), and UI directions you could build yourself —
@@ -163,13 +163,13 @@ Worked example, with per-server data inside the project:
 <sub>Call them as `pnpm run up` — `pnpm up` is pnpm's own update, not your script.</sub>
 
 > [!TIP]
-> Give a project its own panel port (`control.port`, e.g. `4399`) — the default `3999` is what the
-> global instance and every other project also want.
+> Recommended to give a project its own panel port (`control.port`, e.g. `4399`), to avoid port conflict
+> with other projects.
 
 </details>
 
 <details>
-<summary><b>🧰 Run it under systemd or Docker (no daemon needed)</b></summary>
+<summary><b>🧰 Run it under systemd or Docker</b></summary>
 
 ```bash
 home-hosted up --foreground     # stays in the foreground, logs to stderr
@@ -179,12 +179,16 @@ home-hosted up --foreground     # stays in the foreground, logs to stderr
 [Unit]
 Description=home-hosted
 [Service]
+User=$YOUR_USER
 ExecStart=/usr/local/bin/home-hosted up --foreground
 Environment=HHOSTED_HOME=/srv/home-hosted
 Restart=always
 [Install]
 WantedBy=multi-user.target
 ```
+> [!CAUTION]
+> Note: change `$YOUR_USER` to your actual user account, or remove for `root`.
+> You could also change `/srv/home-hosted` to change where the data stores.
 
 </details>
 
@@ -231,8 +235,7 @@ default workspace.
 | `GET /healthz` | no session needed — the one an external monitor wants (its per-server detail needs a credential) | ❌ |
 | `GET /api/metrics` | Prometheus text (needs a token or session, like every `/api` route) | ❌ |
 
-✅ takes `?workspace=<id>`; ❌ is panel-wide. Omitting it means the panel's default workspace — never
-another one.
+✅ takes `?workspace=<id>`; ❌ is panel-wide. Omitting `?workspace` means `default` workspace is used.
 
 `GET /openapi/spec.json` describes all of it, `/openapi/ui` is the browsable version, and every error
 comes back as one envelope (`{ message, code, detail }`) with a stable `code` a tool can branch on.
@@ -273,7 +276,7 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 | 🔔 **Notifications** | Telegram on crash, unhealthy, forced restart, recovery, host thresholds and DNS changes — [setup here](./docs/NOTIFICATIONS.md). |
 | 🌐 **Dynamic DNS** | Keep hostnames pointed at your public IP — Cloudflare, Namecheap, Spaceship, Porkbun, GoDaddy, Gandi and more. [DDNS.md](./docs/DDNS.md) |
 | 🔀 **Reverse proxy** | One engine in front of everything, with automatic HTTPS: `git.example.com` → a Gitea entry, `media.example.com` → a service on another box, `panel.example.com` → the panel. Caddy, installed and supervised by the panel. [REVERSE_PROXY.md](./docs/REVERSE_PROXY.md) |
-| 💾 **Backups** | Two levels: pick global settings, global secrets, TLS or a whole workspace at the top, then the pieces inside it (settings, servers, secrets, data directories) — plain `.zip`, or AES-256 with a password, restored per path. |
+| 💾 **Backups** | Deep and customizable: pick global settings, global secrets, TLS, Workspaces, then the pieces inside it (workspace settings, servers, secrets, data directories) — plain `.zip`, or AES-256 with a password, customized restore is supported too! |
 | 🎨 **BYOU — Bring Your Own UI** | Upload a static build, `ui-update` to follow its releases, `ui-revert` to go back. [UI_CREATION.md](./docs/UI_CREATION.md) |
 | 🔐 **Security** | Cookie sessions, API tokens, scrypt hashes, per-IP lockout, optional TLS, and a refusal to expose itself without a password. |
 | 🧩 **No special treatment** | A server is `command` + `args` + `env` + `cwd`; nothing is built in for any particular app. |
@@ -283,27 +286,17 @@ can be told what to be: *"Help me build a UI for home-hosted: nostalgic game the
 
 ## 🗂 Workspaces
 
-A workspace is the ownership boundary: its own servers, secrets, logs, nanny state and settings. The
-header picker is the whole control — choose one, create one, rename it, or delete it (which stops
-what it supervises first). The first boot creates a `default` workspace; a pre-workspaces instance is
-relocated into one automatically.
-
-> [!IMPORTANT]
-> **Upgrading from before workspaces (0.6 → 0.7)?** That release is breaking: state moves under
-> `$HHOSTED_HOME/.hh`, settings split global vs. per-workspace, and backups become two-level. The
-> relocation runs on the next command — `home-hosted migrate` reports it and stamps every file. See
-> [Upgrading](#-cli).
+A workspace is the ownership boundary: its own servers, secrets, logs, states and settings.
+The first boot creates a `default` workspace.
 
 | page | url | scope |
 | --- | --- | --- |
 | **Overview** | `/w/<workspace>` | the selected workspace: its servers, counts and live status |
 | **Servers** · **Logs** · **Workspace settings** | `/w/<workspace>/servers` · `/w/<workspace>/logs` · `/w/<workspace>/settings` | the selected workspace |
+| **One server** | `/w/<workspace>/servers/<id>` | that entry: config, live logs, resources |
 | **Global Overview** | `/global/overview` | host vitals plus every server from every workspace |
 | **Global settings** | `/global/settings` | Listener, Authentication, Host vitals, Backups, TLS, Interface, Paths |
-
-Every page is bookmarked by its own URL: the workspace id is part of it, so a link opens the same
-workspace even in a browser that never selected it. `/` opens **Global Overview**. The sidebar lists
-the panel-wide pages first, then the selected workspace's.
+| **Reverse Proxy** | `/proxy` | panel-wide: one engine, every workspace's servers ([REVERSE_PROXY.md](./docs/REVERSE_PROXY.md)) |
 
 <details>
 <summary><b>🗂 What lives where</b></summary>
@@ -334,6 +327,7 @@ An entry is a few lines. Add one with **➕ Add server**, or write it into the s
 ```
 
 `dataEnvs` declares a data directory once: it is exported to the process *and* picked up by Backups.
+
 **Every field, every placeholder, the port-conflict policies (including adopting a server that
 restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.md).**
 
@@ -352,9 +346,9 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted set-password` | set the panel password without opening a browser |
 | `home-hosted set-token` | set the API token scripts and agents use (`--generate`, `--clear`) |
 | `home-hosted migrate` | relocate a pre-workspaces state directory and stamp every config for this release (`--dry-run`, `--yes`) |
-| `home-hosted init` | scaffold a project that keeps `state/` and its data in the repo |
+| `home-hosted init` | scaffold a self-contained project (`HHOSTED_HOME` sets to the repo) |
 | `home-hosted ui-switch` | install a UI from a release asset, a zip file or a URL (interactive) |
-| `home-hosted ui-update` | bring an installed UI up to date, or pick a release (`--old`, `--check`) |
+| `home-hosted ui-update` | bring an installed UI up to date automatically (official UI) or pick a release (`--old`, `--check`) |
 | `home-hosted ui-revert` | go back to the stock panel UI after uploading your own |
 
 <details>
@@ -390,16 +384,6 @@ for a launcher that pins one; a workspace picked in the UI keeps its own. `start
 <details>
 <summary><b>🧭 Upgrading, and why the panel sometimes refuses to start</b></summary>
 
-> **Breaking in 0.7 — workspaces.** State moved under `$HHOSTED_HOME/.hh`: global files at its top
-> level, one directory per workspace. Settings split into panel-wide **Global settings** and
-> per-workspace **Workspace settings**, backups became two-level, and `--config` now points at the
-> default workspace's servers file. The old `servers.config.json` becomes
-> `.hh/default/servers.config.json`.
-
-Relocation is automatic: the CLI relocates a pre-`.hh` `$HHOSTED_HOME` before any command runs, so an
-existing instance keeps working after the upgrade. `home-hosted migrate` reports what it moved and
-stamps every file for this release:
-
 ```bash
 home-hosted migrate --dry-run   # print the steps, write nothing
 home-hosted migrate             # ask, then write — keeps a .bak beside each rewritten file
@@ -582,7 +566,10 @@ run.json                     the running panel (pid, url, token, mode 0600)
 <details>
 <summary><b>Which ports does it use?</b></summary>
 
-Just the control panel, `3999` by default. Supervised servers use the ports you give them.
+The control panel, `3999` by default. Supervised servers use the ports you give them. The reverse
+proxy is the one panel-wide listener, and only when you switch it on: `80`/`443` for automatic HTTPS,
+or `4480`/`4443` unprivileged with your router forwarding to them
+([REVERSE_PROXY.md](./docs/REVERSE_PROXY.md#ports)).
 
 </details>
 
@@ -634,7 +621,7 @@ plus types; `pnpm test` is vitest; `pnpm run media` regenerates the GIF above.
 <details>
 <summary><b>🔗 Interesting resources</b></summary>
 
-- [dsh-home-hosted](https://github.com/NamesMT/dsh-home-hosted) — home-hosted servers management with boot autostart from inside [DeepSeek Harness](https://github.com/deepseek-ai/dsh)
+- [dsh-home-hosted](https://github.com/NamesMT/dsh-home-hosted) — home-hosted servers management with boot autostart from inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
 
 <sub><i>+ PR to add yours</i></sub>
 

package/dist/cli.js

@@ -17657,34 +17657,42 @@ async function runNanny(spec, statePath) {
 			text
 		});
 	};
+	let stopping = false;
+	let pending = null;
+	let spawned = null;
+	const stopChild = (child, signal) => {
+		emit("system", `${signal} — stopping this entry (grace ${spec.stop.graceMs}ms)`);
+		terminate(child, {
+			signal: spec.stop.signal,
+			killGroup: false,
+			graceMs: spec.stop.graceMs
+		});
+	};
+	const onSignal = (signal) => {
+		if (stopping) return;
+		stopping = true;
+		if (spawned === null) pending = signal;
+		else stopChild(spawned, signal);
+	};
+	process.on("SIGTERM", () => onSignal("SIGTERM"));
+	process.on("SIGINT", () => onSignal("SIGINT"));
 	const child = spawnManaged({
 		command: spec.command,
 		args: spec.args,
 		cwd: spec.cwd,
 		env: spec.env
 	}, { detached: false });
+	spawned = child;
 	childPid = child.pid ?? null;
 	persistState();
 	emit("system", `persistent: nanny pid ${process.pid} runs this entry`);
+	if (pending !== null) stopChild(child, pending);
 	const stdout = new LineSplitter((stream, text) => emit(stream, text));
 	const stderr = new LineSplitter((stream, text) => emit(stream, text));
 	child.stdout?.on("data", (chunk) => stdout.push("stdout", chunk));
 	child.stderr?.on("data", (chunk) => stderr.push("stderr", chunk));
 	const heartbeat = setInterval(persistState, NANNY_HEARTBEAT_MS);
 	heartbeat.unref();
-	let stopping = false;
-	const onSignal = (signal) => {
-		if (stopping) return;
-		stopping = true;
-		emit("system", `${signal} — stopping this entry (grace ${spec.stop.graceMs}ms)`);
-		terminate(child, {
-			signal: spec.stop.signal,
-			killGroup: false,
-			graceMs: spec.stop.graceMs
-		});
-	};
-	process.on("SIGTERM", () => onSignal("SIGTERM"));
-	process.on("SIGINT", () => onSignal("SIGINT"));
 	await new Promise((resolve) => {
 		let settled = false;
 		const finish = (code, signal, runtimeMs, note) => {