nylorun 0.5.0-beta → 0.6.0-beta

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # nylorun
 
+## 0.6.0-beta
+
+### Minor Changes
+
+- 0cbd5c9: **Breaking (`nylorun`): readable Docker names, several Tenants on one machine, and Studio at `http://<name>.localhost:4160`.** See MIGRATION.md.
+
+  - **Breaking (`nylorun`): names.** Every container, the network and every volume carries the Tenant's Compose project: containers `nylorun-<name>-postgres`, `-restate`, `-s2-lite`, `-gateway`, `-runtime`, `-studio` (were `…-1`), network `nylorun-<name>` (was `nylorun-<name>_default`), volumes `nylorun-<name>-postgres`, `-restate`, `-s2-lite`, `-workspaces` (were `nylorun-<name>_postgres`, …), each labelled `dev.nylorun.tenant: <name>`. The Compose service `s2` is now `s2-lite` (`nylorun logs s2-lite`).
+  - **Breaking (`nylorun`): Tenants created by 0.5 start fresh.** `start` on a Tenant whose data is in the old volumes exits 3 without starting it and names them; `nylorun reset --tenant <name>` starts it anew. `reset` and `delete` also remove the old volumes and the old network.
+  - **Studio proxy.** One Caddy container per machine (`nylorun-proxy`, files in `~/.nylorun/proxy/`) gives each Tenant's Studio the address `http://<name>.localhost:<port>` (`NYLORUN_PROXY_PORT`, 4160 or a free port chosen once), on `127.0.0.1` and `[::1]` (IPv4 only, saying so, when Docker refuses `::1`). It holds no Tenant data and routes browsers only. `start` brings it up when Studio starts, prints Studio's proxy URL and signs in there (on Studio's own port when the proxy does not answer); a proxy failure never fails `start`. `status` shows both URLs, `ls` and `nylorun studio` the proxy's. `NYLORUN_PROXY_DISABLED=1` turns it off; a Tenant under `NYLORUN_HOME` or `NYLORUN_COMPOSE_PROJECT` does not use it. `doctor` has a `proxy` row.
+  - **Several Tenants.** Restate's RocksDB memory is capped at 256 MiB, so a Tenant uses about 600–700 MB (was about 1.3 GB). `nylorun ls` has a `MEMORY` column (`memoryBytes` in `--json`). `start` names the other running Tenants and their memory. `nylorun stop --all` stops every running Tenant and the proxy, keeping their volumes.
+  - **`@nylorun/studio`.** `NYLORUN_STUDIO_PUBLIC_ORIGINS` lists exact `http:` origins Studio also serves (Host and `Origin` checks); a login token's URL is on the origin it was minted on; `NYLORUN_STUDIO_SESSION_COOKIE` names the session cookie (default `nylorun_studio_session`; `nylorun` sets `nylorun_studio_<name>`, so Studios on one host keep their own sessions); the `421` answer lists the served origins.
+
+### Patch Changes
+
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+
 ## 0.5.0-beta
 
 ### Minor Changes

package/README.md

@@ -36,12 +36,12 @@ npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the Tenan
 ```sh
 nylorun up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
                                    # create (first run) and start the Tenant; link the project; print the URLs; open Studio signed in
-nylorun down|stop [--tenant <name>]   # stop the containers; keep volumes
+nylorun down|stop [--tenant <name> | --all]   # stop the containers (--all: every Tenant's, and the Studio proxy); keep volumes
 nylorun status [--tenant <name>] [--json]   # the Tenant, its Host root and id, services, endpoints, Runtime health
-nylorun logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2, gateway, runtime, studio
+nylorun logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2-lite, gateway, runtime, studio
 nylorun studio [--tenant <name>] [--no-open]   # sign a browser in to Studio on the Tenant; starts it if needed
 nylorun reset [--tenant <name>] [--yes]        # delete the Tenant's volumes, Tenant directory and vault key; the next start creates it anew
-nylorun ls [--json]                # the Tenants on this machine
+nylorun ls [--json]                # the Tenants on this machine, with their state, memory and URLs
 nylorun delete <tenant> --yes      # remove a Tenant: containers, volumes, Host root and vault key
 nylorun doctor [--json]            # prerequisites and the Tenant's health
 nylorun telemetry [status|enable|disable]   # Studio's anonymous usage analytics
@@ -78,6 +78,42 @@ name). nylorun 0.4 kept Host roots in `~/.nylorun/stacks/`: the first command
 of this release moves them to `~/.nylorun/tenants/`, keeping their Compose
 projects and volumes.
 
+### Several Tenants
+
+Tenants run side by side, each on its own ports, containers, network and
+volumes ([The containers](#the-containers)); a running Tenant uses about
+600–700 MB. Each Studio has its own address through the
+[Studio proxy](#the-studio-proxy), `http://<name>.localhost:4160`. `nylorun ls`
+lists them with their state, the memory their containers use (`MEMORY`: the sum
+of `docker stats` over the containers labelled `dev.nylorun.tenant=<name>`, `-`
+when stopped; `memoryBytes` in `--json`, `null` when stopped or unknown), the
+Runtime's URL and Studio's:
+
+```text
+TENANT   STATE    MEMORY  RUNTIME                STUDIO                         PROJECT
+api      running  652 MB  http://localhost:8790  http://api.localhost:4160      /Users/me/api
+default  stopped  -       http://localhost:8787  http://default.localhost:4160  -
+```
+
+When other Tenants are running, `start` says so after its summary, on stderr
+(without the size when Docker does not report it):
+
+```text
+Also running: default, api (about 1.3 GB). "nylorun stop --all" stops them all.
+```
+
+`nylorun stop --all` stops every running Tenant on this machine and the Studio
+proxy, keeping their volumes; it cannot be combined with `--tenant` (exit 2).
+`stop` of one Tenant leaves the proxy running.
+
+A Tenant created by nylorun 0.5 keeps its data in volumes Compose named
+`<project>_postgres`, `<project>_restate`, `<project>_s2` and
+`<project>_workspaces`; this release names them `<project>-postgres`, … (see
+[The containers](#the-containers)). `start` on such a Tenant exits 3 without
+starting it, naming the old volumes: run `nylorun reset --tenant <name>` to
+start it fresh. `reset` and `delete` also remove the old volumes (and the old
+network `<project>_default`).
+
 A Tenant refuses only a Runtime older than its own database: `start` records
 the pinned Runtime version in `host.json` (`runtimeVersion`) and exits 5 when
 this nylorun pins an older one. Update nylorun, or pass `--allow-downgrade`
@@ -119,25 +155,79 @@ The Runtime registers the derived principals of `NYLORUN_DERIVED_PRINCIPALS`
 ## The containers
 
 `nylorun start` writes `compose.yaml` and `.env` (mode 0600) under
-`~/.nylorun/tenants/<name>/docker/` on the first run and reuses them after that: `postgres`,
-`restate`, `s2`, `gateway`, `runtime` and `studio`. Postgres initialises the
-Tenant's database with C collation. The Runtime and Studio images are pinned by
+`~/.nylorun/tenants/<name>/docker/` on every start; `.env` keeps the ports and
+secrets chosen on the first run. The services are `postgres`, `restate`,
+`s2-lite`, `gateway`, `runtime` and `studio`. Container, network and volume
+names are global on the Docker engine, so each carries the Tenant's Compose
+project, and each has the label `dev.nylorun.tenant: <name>`. For Tenant `shop`:
+
+| Thing | Name |
+| --- | --- |
+| Containers | `nylorun-shop-postgres`, `nylorun-shop-restate`, `nylorun-shop-s2-lite`, `nylorun-shop-gateway`, `nylorun-shop-runtime`, `nylorun-shop-studio` |
+| Network | `nylorun-shop` |
+| Volumes | `nylorun-shop-postgres`, `nylorun-shop-restate`, `nylorun-shop-s2-lite`, `nylorun-shop-workspaces` |
+
+Postgres initialises the Tenant's database with C collation. Restate's RocksDB
+memory is capped at 256 MiB (`RESTATE_ROCKSDB_TOTAL_MEMORY_SIZE`; Restate's
+default is 2 GiB), so several Tenants fit on a laptop: a Tenant uses about
+600–700 MB, down from about 1.3 GB. The Runtime and Studio images are pinned by
 this release (`package.json` `nylorun.runtime` and `nylorun.studio`);
 `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them (local builds,
 CI). Ports publish on loopback only: the Runtime on `8787`, its operator
 listener (Admin API) on `8788`, Studio on `4161` and the Restate UI on `9070`,
 or free ports chosen on the Tenant's first start, avoiding the ports other
-Tenants keep, and kept in its `.env`.
-
-`start` prints Studio as `http://localhost:<port>`. Studio has no password: in a
-terminal (not in CI, and not with `--no-open`), `start` asks the Studio container
-for a single-use login token with the admin key (`POST /_studio/login-tokens`)
-and opens `http://localhost:<port>/login?token=…` on the Tenant's page in the
-browser. That sets a session cookie for 30 days, which survives Studio
-restarts, so the printed URL keeps working in that browser. The token itself is
-never printed unless no browser starts. Otherwise `start` says to run `nylorun
-studio`, which signs a browser in the same way; `nylorun studio --no-open`
-prints the login URL (it works once, for two minutes) instead.
+Tenants and the Studio proxy keep, and kept in its `.env`.
+
+`start`, `ls` and `nylorun studio` give Studio as `http://<name>.localhost:4160`,
+its address through the Studio proxy (below); `status` adds Studio's own
+`http://localhost:<port>` (`--json` has both: `studio.url` is Studio's own port,
+which an embedding app frames, and `studio.proxyUrl` the proxy's). Studio has no
+password: in a terminal (not in CI, and not with `--no-open`), `start` asks the
+Studio container for a single-use login token with the admin key (`POST
+/_studio/login-tokens`, through the proxy; on Studio's own port, saying so,
+when the proxy does not answer) and opens `…/login?token=…` on the Tenant's
+page in the browser. That sets a session cookie for 30 days, which survives
+Studio restarts, so the printed URL keeps working in that browser. The token
+itself is never printed unless no browser starts. Otherwise `start` says to run
+`nylorun studio`, which signs a browser in the same way; `nylorun studio
+--no-open` prints the login URL (it works once, for two minutes) instead.
+
+Each Tenant's Studio sets its own session cookie, `nylorun_studio_<name>`
+(`NYLORUN_STUDIO_SESSION_COOKIE`).
+
+### The Studio proxy
+
+One small Caddy container per machine (`nylorun-proxy`, Compose project
+`nylorun-proxy`, label `dev.nylorun.proxy: "true"`) gives every Tenant's Studio
+the address `http://<name>.localhost:<port>`. Browsers keep cookies per host,
+not per port, so separate hosts keep the Studios' sessions apart. The proxy is
+for browsers only: programs keep using the Runtime's `http://localhost:<port>`.
+It holds no Tenant data; its files are in `~/.nylorun/proxy/` (`compose.yaml`,
+`Caddyfile`, and `.env` with `NYLORUN_PROXY_PORT`, 4160 or a free port chosen
+on its first start and kept; Caddy's own state is tmpfs). Its image is pinned
+by this release (`caddy:2.11.6`).
+
+- Caddy listens on port 80 in the container, published at `NYLORUN_PROXY_PORT`
+  on `127.0.0.1` and `[::1]` (macOS resolves `*.localhost` to `::1` only); when
+  Docker refuses `::1` (IPv6 off), it publishes on `127.0.0.1` alone and says
+  so once.
+- It routes every Tenant under `~/.nylorun/tenants/`: it joins each Tenant's
+  network and reaches `<project>-studio:3000`, passing the browser's `Host`
+  through, which Studio checks. A stopped Tenant answers 502 naming
+  `nylorun start --tenant <name>`; an unknown host 404 naming `nylorun ls`.
+- `start` rewrites its files, brings it up (only when Studio starts: not with
+  `--no-studio`), joins every Tenant's network and reloads Caddy; Studio learns
+  its proxy origin from `NYLORUN_STUDIO_PUBLIC_ORIGINS`, written to the
+  Tenant's `.env` on every start. A proxy that does not come up never fails
+  `start`: it warns once and prints Studio's own URL.
+- `reset` and `delete` detach it from the Tenant's network first; `delete`
+  removes the Tenant's route. `stop --all` stops it.
+- `NYLORUN_PROXY_DISABLED=1` turns it off: Studio is `http://localhost:<port>`.
+  A Tenant under `NYLORUN_HOME` or `NYLORUN_COMPOSE_PROJECT` (the repository's
+  smokes) does not use it either.
+
+`nylorun doctor` reports it on a `proxy` row: running (on which loopbacks and
+port), stopped, not created yet, or disabled.
 
 ### Embedding Studio in a desktop app
 
@@ -201,7 +291,7 @@ containers, volumes and Host root: the vault key (KEK) and all its data go with
 | 0 | Success |
 | 1 | Generic failure, including a missing Docker or Compose v2 |
 | 2 | Usage error (including no Tenant selected, or `delete` without `--yes`), or a removed or moved command |
-| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no Tenant yet; `delete`: no such Tenant |
+| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no Tenant yet; `delete`: no such Tenant; `start`: a Tenant created by nylorun 0.5 (reset it) |
 | 4 | The Runtime port is held by another Host |
 | 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the Tenant; update nylorun, or `start --allow-downgrade` |
 | 7 | The containers, the Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
@@ -218,5 +308,7 @@ containers, volumes and Host root: the vault key (KEK) and all its data go with
 | Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `~/.nylorun/tenants/<name>/docker/.env` |
 | Logs | `nylorun logs runtime -f` |
 | Studio login expired | `nylorun studio` |
+| `http://<name>.localhost:<port>` does not answer | `nylorun doctor` (the `proxy` row); `nylorun start` brings the proxy up; Studio's own port is in `nylorun status` |
+| `Tenant … was created by nylorun 0.5` (exit 3) | `nylorun reset --tenant <name>` (its data starts fresh) |
 
 See [MIGRATION.md](../MIGRATION.md).

package/dist/doctor.d.ts

@@ -1,4 +1,4 @@
-import { type Check, type StackDeps, type StackStatus } from "./stack/index.js";
+import { type Check, type ProxyStatus, type StackDeps, type StackStatus } from "./stack/index.js";
 export interface StackDoctorReport {
     node: {
         version: string;
@@ -9,6 +9,8 @@ export interface StackDoctorReport {
     tenant?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway">;
     /** Why no Tenant was checked: none is selected here (a project without a link). */
     noTenant?: string;
+    /** The machine's Studio proxy (`http://<tenant>.localhost:<port>`); never a failure. */
+    proxy?: ProxyStatus;
 }
 /**
  * `nylorun doctor`: check the prerequisites of a local Tenant (Node 24+,

package/dist/doctor.js

@@ -1,5 +1,5 @@
 import { CliError } from "./errors.js";
-import { checkDocker, defaultStackDeps, readStackStatus, } from "./stack/index.js";
+import { checkDocker, defaultStackDeps, readProxyReport, readStackStatus, } from "./stack/index.js";
 /** Oldest Node nylorun and the developer's application run on. */
 const MIN_NODE_MAJOR = 24;
 /**
@@ -36,6 +36,7 @@ export async function doctorStack(options) {
                 throw error;
             report.noTenant = error.message;
         }
+        report.proxy = await readProxyReport(deps);
     }
     const broken = report.tenant?.state === "running" &&
         (!report.tenant.runtime.healthy ||
@@ -95,9 +96,25 @@ export async function doctorStack(options) {
                         ? `✓ ${local.tenant.id ?? "?"} open`
                         : `✗ ${local.tenant.id ?? "?"} unavailable${local.tenant.cause ? `: ${local.tenant.cause.code}: ${local.tenant.cause.repair}` : " (opening)"}`,
                 ]);
-            rows.push(["studio", `${local.studio.url ?? "?"} · ${local.studio.state}`]);
+            rows.push(["studio", `${local.studio.proxyUrl ?? local.studio.url ?? "?"} · ${local.studio.state}`]);
         }
     }
+    const proxy = report.proxy;
+    if (proxy) {
+        const on = proxy.port
+            ? `127.0.0.1:${proxy.port}${proxy.ipv6 ? ` and [::1]:${proxy.port}` : ""}`
+            : "";
+        rows.push([
+            "proxy",
+            proxy.state === "running"
+                ? `✓ running on ${on} (http://<tenant>.localhost:${proxy.port ?? "?"})`
+                : proxy.state === "disabled"
+                    ? "- disabled (NYLORUN_PROXY_DISABLED): Studio is on each Tenant's own port"
+                    : proxy.state === "stopped"
+                        ? `- stopped${on ? ` (${on})` : ""}: nylorun start starts it`
+                        : "- not created yet: nylorun start creates it",
+        ]);
+    }
     const width = Math.max(...rows.map(([key]) => key.length)) + 2;
     for (const [key, value] of rows)
         log(`  ${key.padEnd(width)}${value}`);

package/dist/stack/commands.d.ts

@@ -1,8 +1,9 @@
 import type { HostTenant } from "@nylorun/core/contracts";
 import { type ComposeService, type DockerRunner } from "./docker.js";
 import type { PortProbe } from "./ports.js";
+import { type ProxyStatus } from "./proxy.js";
 import { type FetchLike } from "./studio-login.js";
-export declare const STACK_SERVICES: readonly ["postgres", "restate", "s2", "gateway", "runtime", "studio"];
+export declare const STACK_SERVICES: readonly ["postgres", "restate", "s2-lite", "gateway", "runtime", "studio"];
 export declare const stackUsage: string;
 export interface StackDeps {
     /** Environment snapshot (NYLORUN_HOME, NYLORUN_TENANT, image overrides, NYLORUN_COMPOSE_PROJECT). */
@@ -73,7 +74,10 @@ export interface StackStatus {
     /** The Tenant as the Runtime reports it, while it answers. */
     tenant?: StackTenant;
     studio: {
+        /** Studio's own port: what an embedding app frames (same site as its own localhost). */
         url?: string;
+        /** Through the Studio proxy, when it serves the Tenant. */
+        proxyUrl?: string;
         state: string;
         /** Exact origins that may show Studio in a frame (Studio §8.9). */
         embedOrigins?: string[];
@@ -88,6 +92,8 @@ export interface StackStatus {
     };
     services: ComposeService[];
 }
+/** The Studio proxy, as data (`nylorun doctor`). */
+export declare function readProxyReport(deps: StackDeps): Promise<ProxyStatus>;
 /** What `nylorun status` reports, as data (`nylorun doctor`). */
 export declare function readStackStatus(deps: StackDeps, options?: {
     name?: string;
@@ -105,6 +111,8 @@ export interface StackEndpoints {
     hostId: string;
     adminKey: string;
     studioPort: number;
+    /** Through the proxy when it serves the Tenant, else Studio's own port. */
+    studioUrl: string;
     /** Studio is running and healthy. */
     studioUp: boolean;
     /** This call started the Runtime (it was not running before). */
@@ -127,7 +135,7 @@ export declare function tenantStudioPath(tenantId: string): string;
  * Mint a fresh Studio login URL on a running Tenant, landing on `next`.
  * Undefined (after a warning) when Studio does not answer.
  */
-export declare function studioLoginUrl(deps: StackDeps, running: Pick<StackEndpoints, "studioPort" | "adminKey">, next?: string): Promise<string | undefined>;
+export declare function studioLoginUrl(deps: StackDeps, running: Pick<StackEndpoints, "studioPort" | "studioUrl" | "adminKey">, next?: string): Promise<string | undefined>;
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export declare function runStudioCommand(args: readonly string[], deps: StackDeps, options?: {
     next?: string;