@cyaxis/ulvia 0.0.1-alpha.9 → 0.0.3

package/INSTALLATION.md

@@ -0,0 +1,182 @@
+# Install Ulvia
+
+This guide installs the Ulvia CLI and creates a first CMS instance on Ubuntu.
+It is for operators and site owners; workspace contributors should use the
+[development guide](../development/README.md).
+
+> **Prerelease availability:** `@cyaxis/ulvia` is the official release package.
+> Prereleases use the npm `next` tag; stable releases use `latest`.
+
+## 1. Prerequisites On Ubuntu
+
+Ulvia requires a supported Ubuntu host, Docker Engine with the Docker Compose
+plugin, and Bun. Follow the upstream instructions rather than copying an
+unversioned third-party installation script:
+
+- [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
+- [Install the Docker Compose plugin on Linux](https://docs.docker.com/compose/install/linux/)
+- [Run Docker without `sudo` and configure startup](https://docs.docker.com/engine/install/linux-postinstall/)
+- [Install Bun on Linux](https://bun.com/docs/installation)
+
+Docker's Ubuntu packages include the Compose plugin when
+`docker-compose-plugin` is installed. Verify the complete toolchain:
+
+```bash
+docker version
+docker compose version
+bun --version
+```
+
+The current release toolchain targets Bun 1.4.2 or newer. Docker must be running
+and accessible to the account that executes `ulvia`.
+
+## 2. Install The CLI
+
+Install the current prerelease globally from the public npm registry:
+
+```bash
+bun add --global @cyaxis/ulvia@next
+ulvia --help
+```
+
+If `ulvia` is not found, reopen the terminal and check that `~/.bun/bin` is in
+`PATH`, as described by the Bun installation guide.
+
+## 3. Create A Local Site
+
+Start the shared infrastructure, then create one named instance:
+
+```bash
+ulvia services start
+ulvia instance create my-site --label "My site"
+ulvia instance credentials my-site
+```
+
+The first start uses the exact software version bundled into the installed CLI.
+To bootstrap a different exact prerelease explicitly, use
+`ulvia services start --version 0.0.1-beta`. This option never upgrades an
+existing installation.
+
+The site is available at `http://my-site.localhost:5100`. The credentials
+command prints the initial administrator email and password. It never prints
+the Provider, Repository, encryption, or instance service secrets.
+
+Ulvia deliberately separates shared services from sites:
+
+| Command | Responsibility |
+| --- | --- |
+| `ulvia services start` | Starts the proxy, MongoDB, Official Repository, and Provider. |
+| `ulvia instance create <name>` | Provisions one Provider tenant and starts its Kernel. |
+| `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
+| `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
+
+List and inspect the installation at any time:
+
+```bash
+ulvia services status
+ulvia instance list
+ulvia instance status my-site
+```
+
+Persistent data lives below `$XDG_DATA_HOME/ulvia` or
+`~/.local/share/ulvia`. Commands can be run from any working directory.
+
+## 4. Daily Operations
+
+```bash
+ulvia start
+ulvia instance stop my-site
+ulvia instance start my-site
+ulvia services logs all --level warn
+ulvia instance logs my-site kernel
+ulvia services stop
+```
+
+Stopping containers preserves persistent data. `services stop` also makes every
+site unavailable because Kernels depend on the shared Provider and proxy.
+
+## 5. Upgrade Ulvia
+
+Upgrade the host CLI through Bun:
+
+```bash
+bun update --global @cyaxis/ulvia
+```
+
+Upgrade deployable components independently with exact versions:
+
+```bash
+ulvia upgrade kernel --version 0.0.1-beta
+ulvia upgrade provider --version 0.0.1-beta
+ulvia upgrade repository --version 0.0.1-beta
+```
+
+Ulvia resolves each official Docker Hub tag to an immutable digest and reuses
+that digest on subsequent starts. Registry channels such as `next` or `latest`
+may identify releases for humans, but an installation never persists or
+silently follows those mutable tags.
+
+## 6. Public Domain And HTTPS
+
+Configure public networking before creating the first instance because the
+canonical Kernel URLs become part of Provider provisioning:
+
+```bash
+ulvia configure network \
+  --bind 0.0.0.0 \
+  --http-port 80 \
+  --tls acme \
+  --https-port 443 \
+  --acme-email ops@example.com
+
+ulvia services start
+ulvia instance create website --domain example.com
+ulvia instance credentials website
+```
+
+Before starting, point the domain's DNS records to the host and allow inbound
+TCP traffic on ports 80 and 443. Review Docker's documented firewall behavior:
+published container ports can bypass some `ufw` and `firewalld` rules unless
+the host policy uses Docker's supported chains.
+
+Repository and Provider management endpoints remain bound to loopback. Only the
+shared proxy is exposed publicly.
+
+## 7. Backup, Reset, And Removal
+
+Stop the installation before taking a filesystem-level backup of the Ulvia data
+directory. Preserve the complete directory, including MongoDB, files,
+credentials, encryption material, Repository state, and instance definitions.
+Do not restore only selected secret or database files from different snapshots.
+
+`reset` permanently removes Ulvia-owned local state:
+
+```bash
+ulvia reset --yes
+```
+
+Remove the CLI separately after stopping or resetting the installation:
+
+```bash
+bun remove --global @cyaxis/ulvia
+```
+
+Removing the CLI alone does not delete persistent CMS data or Docker resources.
+
+## 8. Troubleshooting
+
+- **Docker permission denied:** complete Docker's Linux post-installation steps,
+  then start a new login session.
+- **`docker compose` is unknown:** install the official Compose plugin rather
+  than the retired standalone `docker-compose` package.
+- **Port 5100, 80, or 443 is occupied:** inspect the owner before changing the
+  persisted network configuration.
+- **An image cannot be pulled:** verify network access and that the requested
+  exact Cyaxis image version has been published.
+- **An instance returns 503:** check `ulvia services status`, then the Provider
+  and instance Kernel logs.
+- **Stored encrypted data cannot be opened:** do not generate replacement keys
+  over an existing data directory; restore the matching complete backup.
+
+For implementation diagnostics and contributor-only environment overrides, see
+the [development and validation guide](../development/README.md).

package/README.md

@@ -2,6 +2,9 @@
 
 Ulvia installation and release CLI.
 
+For the operator journey from a fresh Ubuntu host to a running local or public
+site, follow the [canonical installation guide](INSTALLATION.md).
+
 The workspace package contains private source code. Official releases are
 bundled without workspace dependencies and published publicly as
 `@cyaxis/ulvia`:
@@ -14,14 +17,16 @@ ulvia --help
 From the workspace, build and publish one exact release with:
 
 ```bash
-bun run cli:build --version 0.0.1-alpha.9
-bun run cli:publish --version 0.0.1-alpha.9
+bun run cli:build --version 0.0.2 --stack-version 0.0.1-beta
+bun run cli:publish --version 0.0.2
 ```
 
 The build creates a checked npm archive and SHA-256 receipt below
-`artifacts/cli`. Publishing accepts only that exact pair, targets the public npm
-registry, and uses the `next` tag for prereleases or `latest` for stable versions.
-It requires npm credentials configured outside the repository.
+`artifacts/cli`. The CLI package version and its compatible initial Docker stack
+version are independent and both are sealed into that receipt. Publishing
+accepts only the exact pair, targets the public npm registry, and uses the
+`next` tag for prereleases or `latest` for stable versions. It requires npm
+credentials configured outside the repository.
 
 ```bash
 bun run ulvia -- start
@@ -33,9 +38,9 @@ bun run ulvia -- instance credentials preview
 bun run ulvia -- instance stop preview
 bun run ulvia -- instance delete preview --yes
 bun run ulvia -- services stop
-bun run ulvia -- upgrade kernel --version 0.0.1-alpha.9
-bun run ulvia -- upgrade provider --version 0.0.1-alpha.9
-bun run ulvia -- upgrade repository --version 0.0.1-alpha.9
+bun run ulvia -- upgrade kernel --version 0.0.1-beta
+bun run ulvia -- upgrade provider --version 0.0.1-beta
+bun run ulvia -- upgrade repository --version 0.0.1-beta
 bun run ulvia -- reset --yes
 bun run ulvia -- release packages/official-repository/collections/ulvia-official
 bun run ulvia -- release /path/to/contract-directory
@@ -80,6 +85,10 @@ after the first instance because its canonical Kernel URL is part of Provider
 provisioning. Repository and Provider management ports remain loopback-only.
 
 `services start` starts only the shared proxy, MongoDB, Repository and Provider.
+On first initialization it uses the exact version embedded by `cli:build`, or
+an explicit `services start --version <version>` override. Later starts reuse
+the persisted digests and reject a conflicting `--version`; component changes
+must go through `upgrade`.
 `instance create` provisions one isolated Provider tenant and immediately starts
 its dedicated Kernel. `instance start` restarts only an already-provisioned
 instance's Kernel. All Kernels use the shared proxy port: an instance named

package/dist/index.js

@@ -2002,7 +2002,6 @@ function parseComposeServices(source) {
 }
 
 // packages/runtimes/ulvia-cli/src/runtime/stack/orchestration/images.ts
-var DEFAULT_STACK_VERSION = "0.0.1-alpha.9";
 var SUPPORTED_STACK_API = "1";
 var REPOSITORIES = {
   kernel: "docker.io/cyaxis/ulvia-kernel",
@@ -2139,6 +2138,18 @@ function localKernelEnvironment(instance, config, connection, services, image) {
   };
 }
 
+// packages/runtimes/ulvia-cli/src/runtime/stack/version.ts
+var injectedCliVersion = "0.0.3";
+var injectedStackVersion = "0.0.1-beta";
+var CLI_VERSION = injectedCliVersion ?? "development";
+var DEFAULT_STACK_VERSION = injectedStackVersion ?? "unbundled";
+function defaultStackVersion() {
+  if (!injectedStackVersion) {
+    throw new Error("This development CLI has no bundled stack version. Pass --version <version> on the first start.");
+  }
+  return injectedStackVersion;
+}
+
 // packages/runtimes/ulvia-cli/src/runtime/stack/orchestration/state.ts
 import { createHash } from "crypto";
 import { chmod as chmod6, readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
@@ -2238,12 +2249,10 @@ function validServiceImages(value) {
 }
 
 // packages/runtimes/ulvia-cli/src/runtime/stack/orchestration/services.ts
-async function startLocalServices(paths, installation, log) {
+async function startLocalServices(paths, installation, log, requestedVersion) {
   const installed = await loadLocalServicesState(paths);
-  const images = installed?.images ?? {
-    provider: await pullOfficialImage("provider", DEFAULT_STACK_VERSION, log),
-    repository: await pullOfficialImage("repository", DEFAULT_STACK_VERSION, log)
-  };
+  assertStartVersion(installed, requestedVersion);
+  const images = installed?.images ?? await pullInitialImages(requestedVersion ?? defaultStackVersion(), log);
   await ensureOfficialImage(images.provider);
   await ensureOfficialImage(images.repository);
   const credentials = await serviceCredentials(paths);
@@ -2259,6 +2268,22 @@ async function startLocalServices(paths, installation, log) {
   await saveLocalServicesState(paths, installation, images);
   log(`Shared services are ready (Provider ${images.provider.version}, Repository ${images.repository.version}).`);
 }
+async function pullInitialImages(version, log) {
+  const [provider, repository] = await Promise.all([
+    pullOfficialImage("provider", version, log),
+    pullOfficialImage("repository", version, log)
+  ]);
+  return { provider, repository };
+}
+function assertStartVersion(state, requestedVersion) {
+  if (!state || !requestedVersion) {
+    return;
+  }
+  const current = new Set([state.images.provider.version, state.images.repository.version]);
+  if (current.size !== 1 || !current.has(requestedVersion)) {
+    throw new Error("Shared services are already initialized with different versions. Use ulvia upgrade provider and ulvia upgrade repository.");
+  }
+}
 async function upgradeLocalService(paths, component, version, log) {
   const installed = await loadLocalServicesState(paths);
   if (!installed) {
@@ -2339,7 +2364,7 @@ async function startLocalKernel(paths, name, log) {
   const services = await requireServices(paths);
   await requireRunningLocalProvider(paths);
   const installed = await loadLocalKernelState(runtime.paths);
-  const image = installed?.image ?? await pullOfficialImage("kernel", DEFAULT_STACK_VERSION, log);
+  const image = installed?.image ?? await pullOfficialImage("kernel", services.images.provider.version, log);
   await ensureOfficialImage(image);
   const projectName = installed?.projectName ?? localKernelProjectName(paths, name);
   await composeUp(kernelProject(runtime.paths, runtime.config, runtime.connection, services, projectName, image));
@@ -3219,11 +3244,28 @@ async function makeTreeOwnerRemovable(path) {
 }
 
 // packages/runtimes/ulvia-cli/src/commands/local/services.ts
+var SERVICES_HELP = `Usage: ulvia services <start | stop | status | logs>
+
+Manage the shared proxy, MongoDB, Repository, and Provider.`;
+var START_HELP = `Usage: ulvia services start [--version <version>]
+
+Start shared services. On their first start, use the bundled stack version by
+default or the exact version supplied here. Existing installations keep their
+pinned image digests; use ulvia upgrade for later changes.
+
+Bundled initial stack version: ${DEFAULT_STACK_VERSION}`;
 async function servicesCommand(args, paths, installation, log) {
   const [action, ...rest] = args;
+  if (!action || action === "help" || action === "--help" || action === "-h") {
+    log(SERVICES_HELP);
+    return;
+  }
   if (action === "start") {
-    expectNone(rest, "Usage: ulvia services start");
-    await startLocalServices(paths, installation, log);
+    if (isHelp(rest)) {
+      log(START_HELP);
+      return;
+    }
+    await startLocalServices(paths, installation, log, parseStartVersion(rest));
     return;
   }
   if (action === "stop") {
@@ -3243,6 +3285,19 @@ async function servicesCommand(args, paths, installation, log) {
   }
   throw new Error("Usage: ulvia services <start | stop | status | logs>");
 }
+function parseStartVersion(args, usage = "Usage: ulvia services start [--version <version>]") {
+  if (args.length === 0) {
+    return;
+  }
+  if (args.length !== 2 || args[0] !== "--version" || !args[1]) {
+    throw new Error(usage);
+  }
+  assertImageVersion(args[1]);
+  return args[1];
+}
+function isHelp(args) {
+  return args.length === 1 && (args[0] === "help" || args[0] === "--help" || args[0] === "-h");
+}
 async function printServicesStatus(paths, log) {
   const { state, services } = await describeLocalServices(paths);
   const expected = ["proxy", "mongo", "provider", "repository"];
@@ -3366,10 +3421,18 @@ async function localCommand(command, args, paths, log, environment) {
     await resetLocalInstallation(paths, log);
     return;
   }
-  if (command !== "start" || args.length > 0) {
-    throw new Error("Usage: ulvia start");
+  if (command !== "start") {
+    throw new Error("Usage: ulvia start [--version <version>]");
+  }
+  if (args.length === 1 && ["help", "--help", "-h"].includes(args[0] ?? "")) {
+    log(`Usage: ulvia start [--version <version>]
+
+Start shared services and every existing instance. The exact version only
+selects Provider and Repository images when shared services are uninitialized.`);
+    return;
   }
-  await startLocalServices(paths, installation, log);
+  const requestedVersion = parseStartVersion(args, "Usage: ulvia start [--version <version>]");
+  await startLocalServices(paths, installation, log, requestedVersion);
   const instances = await listLocalInstanceNames(paths);
   if (instances.length === 0) {
     log("Shared services are ready. Create an instance with: ulvia instance create <name>");
@@ -29509,9 +29572,10 @@ function assertDigest(actual, expected) {
 var HELP = `Ulvia CMS CLI
 
 Usage:
-  ulvia start
+  ulvia start [--version <version>]
   ulvia configure network [network options]
-  ulvia services <start | stop | status | logs>
+  ulvia services start [--version <version>]
+  ulvia services <stop | status | logs>
   ulvia instance create <name> [--label <label>] [--domain <domain>]
   ulvia instance <start | stop | status | credentials | logs> <name>
   ulvia instance list
@@ -29558,7 +29622,7 @@ async function runCli(args, options = {}) {
     return;
   }
   if (command === "--version" || command === "-v") {
-    log("0.1.0");
+    log(CLI_VERSION);
     return;
   }
   if (![...LOCAL_COMMANDS, "release", "push", "pull", "yank", "restore", "prune"].includes(command)) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cyaxis/ulvia",
-    "version": "0.0.1-alpha.9",
+    "version": "0.0.3",
     "description": "Ulvia CMS installation and release CLI.",
     "license": "MIT",
     "type": "module",
@@ -10,6 +10,7 @@
     "files": [
         "dist/",
         "README.md",
+        "INSTALLATION.md",
         "LICENSE"
     ],
     "engines": {