@cyaxis/ulvia 0.0.3 → 0.1.0-beta

package/INSTALLATION.md

@@ -32,16 +32,19 @@ and accessible to the account that executes `ulvia`.
 
 ## 2. Install The CLI
 
-Install the current prerelease globally from the public npm registry:
+Install the current stable CLI globally from the public npm registry:
 
 ```bash
-bun add --global @cyaxis/ulvia@next
+bun add --global @cyaxis/ulvia@latest
 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.
 
+Use an exact version, for example `@cyaxis/ulvia@0.0.3`, when reproducing an
+installation. The `next` tag is reserved for explicitly tested prereleases.
+
 ## 3. Create A Local Site
 
 Start the shared infrastructure, then create one named instance:
@@ -97,10 +100,13 @@ site unavailable because Kernels depend on the shared Provider and proxy.
 
 ## 5. Upgrade Ulvia
 
-Upgrade the host CLI through Bun:
+Upgrade the host CLI through Bun. Naming `latest` explicitly also replaces an
+installation that was originally attached to the `next` channel:
 
 ```bash
-bun update --global @cyaxis/ulvia
+bun add --global @cyaxis/ulvia@latest
+hash -r
+ulvia --version
 ```
 
 Upgrade deployable components independently with exact versions:
@@ -116,6 +122,14 @@ 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.
 
+`upgrade kernel` visits every local Kernel instance in sequence. Upgrades of
+Provider and Repository affect shared services. A failed activation attempts
+to restart the previous image, but this does not restore changed database or
+file contents and is not an atomic rollback across all instances.
+Take a complete backup before an upgrade involving persisted data. Internal
+schema migrations and interrupted-upgrade/restore drills remain
+[open platform work](../TODO.md#internal-persistence-migrations).
+
 ## 6. Public Domain And HTTPS
 
 Configure public networking before creating the first instance because the
@@ -149,6 +163,12 @@ 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.
 
+The CLI has no general backup/restore command. Stop each Kernel with
+`ulvia instance stop <name>`, then stop shared services before copying their
+data. Restore and verify a complete backup in an isolated installation before
+treating it as a recovery guarantee; do not rely on image fallback to recover
+data. See [operational recovery](../TODO.md#backup-and-operational-recovery).
+
 `reset` permanently removes Ulvia-owned local state:
 
 ```bash
@@ -180,3 +200,134 @@ Removing the CLI alone does not delete persistent CMS data or Docker resources.
 
 For implementation diagnostics and contributor-only environment overrides, see
 the [development and validation guide](../development/README.md).
+
+
+## 9. Standalone Repository
+
+A public Repository is independent of CMS shared services. It needs Docker and
+the CLI, with one persistent local volume and one active server. The commands
+below describe the candidate implementation; the exact CLI and image versions
+must be published before they can be installed or pulled from a registry.
+
+On the Repository host, configure networking and start the default deployment:
+
+```bash
+ulvia repository configure --tls external --public-url https://repository.example
+ulvia repository start --version 0.1.0
+ulvia repository status
+ulvia repository stop
+ulvia repository start
+ulvia repository upgrade --version 0.1.1
+```
+
+The versions above are examples, not a claim that those images are published.
+No `global`, `community` or deployment name is required. The CLI pulls an exact
+official image, validates its labels and pins its immutable registry digest.
+It does not build or publish images. A failed activation attempts to restart the
+previous image; it does not reverse data migrations. Back up data before upgrades.
+
+Choose one persistent network mode:
+
+| Mode | Configuration | Exposure |
+| --- | --- | --- |
+| Local | `repository configure --tls local --port 5010` | Loopback HTTP only |
+| External proxy | `repository configure --tls external --public-url https://repository.example` | Loopback backend; operator supplies the HTTPS proxy |
+| Managed ACME | `repository configure --tls acme --public-url https://repository.example --acme-email ops@example.com` | Dedicated proxy on host ports 80/443, plus certificate renewals |
+
+Run `repository start` after configuring to apply changes. External proxies
+forward to `127.0.0.1:5010` (or the configured port), preserve request bodies and
+allow 100 MiB assets plus protocol overhead. Managed ACME requires public DNS
+pointing to this host and ports 80/443 available; it cannot share these ports
+with another local proxy. It starts only Repository, proxy and ACME containers.
+Certificate issuance requires the public domain; local tests validate the
+Compose model without issuing a public certificate. `REPOSITORY_PUBLIC_URL`
+controls resource links; forwarded headers do not override it.
+
+On an author's machine, save the connection once:
+
+```bash
+ulvia repository login https://repository.example
+ulvia identity list
+ulvia namespace claim acme
+ulvia namespace status acme
+ulvia release /path/to/authored-resource
+ulvia push contract acme/example.contract@1.0.0
+ulvia pull contract acme/example.contract@1.0.0
+```
+
+Login creates a default local identity if needed and saves the Repository's
+persistent identity. It does not log into a bearer-token session: every mutation
+is signed locally. Claim is public, first valid claimant wins. The resource's
+`publisherId` must match the owned namespace. Release and push are separate;
+dependencies must be released and pushed first. Collections and provider
+manifests use `push collection` and `push provider` with exact coordinates.
+Publishing an artifact does not install it on a CMS site.
+
+Create or import named signing identities when needed:
+
+```bash
+ulvia identity create official
+ulvia identity import imported --key-file /private/existing.pem
+ulvia identity use official
+ulvia identity public-key official
+ulvia repository login https://repository.example --identity official
+ulvia identity create replacement
+ulvia namespace rotate acme --replacement-identity replacement
+ulvia namespace revoke acme --yes
+ulvia repository logout
+```
+
+Rotation requires the current owner's key and proof of the replacement key.
+Publication automatically selects the saved key matching the current namespace
+owner. Revocation is permanent. Losing every copy of an owner key is permanent;
+there is no operator recovery. Logout preserves local identities.
+
+The official public Repository will use `https://repo.ulvia.fr`. Its namespace
+`ulvia.official` follows exactly the same first-claim rule. Initialize it on the
+host while the service is still available only over loopback:
+
+```bash
+ulvia repository start --version 0.1.0
+ulvia identity create official
+ulvia repository login http://127.0.0.1:5010 --identity official
+ulvia namespace claim ulvia.official
+ulvia repository configure --tls acme --public-url https://repo.ulvia.fr --acme-email ops@ulvia.fr
+ulvia repository start
+ulvia repository login https://repo.ulvia.fr --identity official
+ulvia release /path/to/official-contract
+ulvia push contract ulvia.official/example.contract@1.0.0
+```
+
+Run the first claim before opening public access. A separate signing machine can
+reach the loopback listener through an SSH tunnel instead. There is no reserved
+namespace bootstrap or operator token. After the first claim, existing ownership
+survives restarts, upgrades, rotations and terminal revocation.  Tests use temporary local
+repositories; they never contact or publish to `repo.ulvia.fr`.
+
+Client settings and identities live in `$XDG_CONFIG_HOME/ulvia` or
+`~/.config/ulvia`, overridable with `ULVIA_CONFIG_DIR`. `config.json` contains
+public keys, key-file references and the active connection; private PEM files
+live in `keys/`. Files are private (0600), directories 0700. Preserve secure
+backups of keys. Setting only `ULVIA_DATA_DIR` isolates client settings beneath
+`<data>/config`, useful for tests or separate installations.
+
+Deployment configuration lives in `<data>/repository-service/config.json`;
+`service.json` records the last applied image and configuration; `data/` holds
+Repository identity, namespace history, releases and upload/replay state.
+Managed TLS material lives in `proxy/`. Back up the complete stopped deployment
+and the matching signing identities. `reset --yes` affects the CMS installation
+and local release cache; it preserves independent Repository deployments and
+client identities. There is no compatibility path for previous Repository states, deployment names
+or token credentials.
+
+For a contributor's unpublished candidate, use the local Docker regression
+runner instead of `repository start`, which intentionally pulls a published
+registry image:
+
+```bash
+bun run infra/images/build.ts build --version 0.1.0-repository.0 repository
+ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test infra/images/official-repository/tests
+```
+
+These tests launch loopback-only containers, exercise the CLI against their local
+endpoints and remove their temporary data. They publish nothing externally.

package/README.md

@@ -10,15 +10,15 @@ bundled without workspace dependencies and published publicly as
 `@cyaxis/ulvia`:
 
 ```bash
-bun add --global @cyaxis/ulvia@next
+bun add --global @cyaxis/ulvia@latest
 ulvia --help
 ```
 
 From the workspace, build and publish one exact release with:
 
 ```bash
-bun run cli:build --version 0.0.2 --stack-version 0.0.1-beta
-bun run cli:publish --version 0.0.2
+bun run cli:build --version 0.0.3 --stack-version 0.0.1-beta
+bun run cli:publish --version 0.0.3
 ```
 
 The build creates a checked npm archive and SHA-256 receipt below
@@ -29,8 +29,8 @@ accepts only the exact pair, targets the public npm registry, and uses the
 credentials configured outside the repository.
 
 ```bash
-bun run ulvia -- start
 bun run ulvia -- configure network
+bun run ulvia -- services start --version 0.0.1-beta
 bun run ulvia -- services status
 bun run ulvia -- instance create preview --label "Preview site"
 bun run ulvia -- instance list
@@ -52,6 +52,12 @@ bun run ulvia -- restore collection ulvia.official/ulvia-official@1.0.0 --reposi
 bun run ulvia -- prune
 ```
 
+The stack version above is an example of an exact published image tag. Workspace
+source has no embedded initial stack version: its first `services start`
+requires `--version`. Packaged releases embed that default at build time. Later
+starts reuse installed digests. Building workspace source does not replace
+running images or upgrade installed collections.
+
 The lifecycle commands manage the same Docker Compose projects for loopback and
 public installations from any directory. Persistent
 data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
@@ -104,6 +110,31 @@ previously created local instance; it never creates an implicit instance.
 
 The lifecycle boundary is deliberate:
 
+Independent Repository deployments use `ulvia repository start`, `status`, `stop`
+and `upgrade --version <exact-version>`. Their default volume and image pin live
+below `<data>/repository-service`. No deployment name or `global`/`community`
+qualifier is required. The command does not start
+shared services or a Kernel.
+
+`ulvia repository login <url>` verifies and saves the remote identity and creates
+a default local signing identity if none exists. `ulvia identity create`, `import`,
+`use`, `list` and `public-key` manage reusable Ed25519 identities. Namespace
+commands and publication use the saved connection and select an identity matching
+the namespace's current owner. No environment exports are needed. `logout`
+removes only the connection, preserving keys.
+
+Client configuration lives in `$XDG_CONFIG_HOME/ulvia/config.json` or
+`~/.config/ulvia/config.json`; private keys live in its `keys/` directory. Files
+use mode 0600, directories 0700. `ULVIA_CONFIG_DIR` overrides that location;
+`ULVIA_DATA_DIR` alone isolates client configuration under `<data>/config`.
+Deployment configuration is separate: `<data>/repository-service/config.json`.
+`repository configure` persists local, external HTTPS proxy or managed ACME
+networking. All namespaces, including `ulvia.official`, use public first claim.
+Claim platform-owned names locally before enabling public access. Ownership
+persists across restarts and cannot be reset through deployment configuration.
+See the [installation guide](../../../docs/installation/README.md#9-standalone-repository)
+and [Repository architecture](../../../docs/architecture/community-repository.md).
+
 | Command | Provider tenant | Kernel container |
 | --- | --- | --- |
 | `services start` | Does not create one | Does not start one |
@@ -112,14 +143,14 @@ The lifecycle boundary is deliberate:
 | `start` | Never provisions | Starts every existing Kernel after shared services |
 
 `instance credentials <name>` prints only that administrator's email and
-password. Repository, Provider operator and instance bearer tokens remain in
+password. Provider operator and instance bearer tokens remain in
 private runtime files. Shared services and every instance have independent
 `stop`, `status`, and `logs` boundaries. Software upgrades are explicit and
 component-scoped through `upgrade <component> --version <exact-version>`.
 Normal starts always reuse the installed digest and never follow a newer tag.
 `reset --yes`
-removes every Compose project, instance, shared state and repository
-release. It does not inspect or modify the current working directory.
+removes shared Compose projects, instances, shared state and local repository
+releases. It preserves independent Repository deployments and signing identities. It does not inspect or modify the current working directory.
 `release <resource-directory>` reads `definition.json` and routes by `kind`:
 `collection`, `contract`, or `provider-manifest`. It validates and stores one
 immutable release. A provider manifest must reference exact contract releases
@@ -156,10 +187,10 @@ a disposable provider environment.
 `push` publishes one exact local coordinate, and `pull` downloads and re-admits
 one exact remote coordinate before storing it locally. Both support
 `collection`, `contract`, and `provider`; dependencies must be transferred
-first. `ULVIA_REPOSITORY_URL` can replace `--repository`.
-Repository writes require `ULVIA_REPOSITORY_TOKEN`; the token is never accepted
-as a command-line argument. Every mutation carries a timestamp, one-time nonce,
-body digest, and HMAC-SHA-256 signature. The server rejects stale or replayed
+first. `repository login` saves the default endpoint; `--repository` and
+`ULVIA_REPOSITORY_URL` remain explicit overrides. Owner signatures bind Repository
+identity, namespace revision, action, content digest, timestamp and nonce.
+The server rejects stale or replayed
 requests, serializes writes across processes, re-runs admission and evolution
 rules, and stages every declared asset as a separately signed raw stream. A final
 idempotent commit makes the immutable artifact visible only after all byte lengths
@@ -168,9 +199,10 @@ release. An exact republish is idempotent; different bytes at an existing coordi
 reject.
 
 The protocol, exact-coordinate client and mutation endpoint live in
-`@bernouy/cms-repository/repository/publication`; the CLI only composes them with
-the reference filesystem adapter and its loopback listener. The filesystem
-composition persists upload sessions and replay claims below the repository root.
+`@bernouy/cms-repository/repository/publication`. The CLI uses the publication
+client and local filesystem release storage; `official-repository-server`
+composes the HTTP listener inside its container. The filesystem composition
+persists upload sessions and replay claims below the repository root.
 A production repository can replace those ports without depending on this
 executable package.
 
@@ -178,9 +210,7 @@ executable package.
 resolution without deleting its exact historical bytes. `restore` exposes it
 again. Contract yanks block new dependent publications while previously
 published provider manifests remain readable. The loopback Repository uses the
-same write protocol and keeps its generated repository token in the private
-runtime directory. The removed integration repository/Supabase bridge is not
-run.
+same owner-signing protocol. Signing keys stay in local identities.
 
 A collection keeps immutable administration copy in recursive locale
 directories such as `translations/en/collection.json` and
@@ -224,19 +254,20 @@ and do not affect release identity.
 
 The Official Repository image contains the admitted CMS contracts, provider
 manifest, and administration collection. It installs that snapshot only into
-empty persistent storage. To publish the same resources manually, release the
-CMS contracts before the manifest:
+absent or empty persistent storage. A non-empty repository is never overlaid on
+image upgrade. The workspace bootstrap command builds the admitted snapshot
+used by the image:
 
 ```bash
-bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.access
-bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.installations
-bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.content
-bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.files
-bun run ulvia -- release packages/official-repository/contracts/ulvia.provider.cms-instances
-bun run ulvia -- release packages/official-repository/providers/ulvia.official
-bun run ulvia -- start
+bun run generate:official-bootstrap
 ```
 
+That command neither publishes to a running repository nor upgrades an existing
+instance. For individual manual releases, use `release` in dependency order:
+exact contract dependencies before dependent contracts and provider manifests.
+Publication, provider profile transitions, collection upgrades and container
+image replacement remain separate actions.
+
 `instance create` provisions the named instance through the Provider operator
 API, then starts its Kernel. Connection review validates the runtime report and
 exact manifest claims; it does not yet execute a live conformance suite.

package/dist/definitions/repository-tls.yml

@@ -0,0 +1,38 @@
+services:
+    repository:
+        environment:
+            VIRTUAL_HOST: ${ULVIA_REPOSITORY_DOMAIN}
+            VIRTUAL_PORT: "3000"
+            LETSENCRYPT_HOST: ${ULVIA_REPOSITORY_DOMAIN}
+    proxy:
+        image: nginxproxy/nginx-proxy:1.11.5@sha256:e06db5fb9586234e9c2bdef707c8b8d784caa4fb49fbe7285eb3730a501c3eaa
+        restart: unless-stopped
+        ports:
+            - "0.0.0.0:80:80"
+            - "0.0.0.0:443:443"
+        volumes:
+            - /var/run/docker.sock:/tmp/docker.sock:ro
+            - ./nginx/client_max_body.conf:/etc/nginx/conf.d/zzz_client_max_body.conf:ro
+            - ./nginx/query_safe_access_log.conf:/etc/nginx/conf.d/zzz_query_safe_access_log.conf:ro
+            - ${ULVIA_REPOSITORY_PROXY_DIR}/certificates:/etc/nginx/certs
+            - ${ULVIA_REPOSITORY_PROXY_DIR}/virtual-hosts:/etc/nginx/vhost.d
+            - ${ULVIA_REPOSITORY_PROXY_DIR}/challenge:/usr/share/nginx/html
+        healthcheck:
+            test: ["CMD", "nginx", "-t"]
+            interval: 30s
+            timeout: 5s
+            retries: 3
+            start_period: 5s
+    acme:
+        image: nginxproxy/acme-companion:2.8.1@sha256:ccfceb9798b9f6586d47eeeadbb8e185c8897b34e011a2739a9b82d5e92a8b6c
+        restart: unless-stopped
+        depends_on:
+            proxy:
+                condition: service_healthy
+        volumes_from:
+            - proxy
+        volumes:
+            - /var/run/docker.sock:/var/run/docker.sock:ro
+            - ${ULVIA_REPOSITORY_PROXY_DIR}/acme:/etc/acme.sh
+        environment:
+            DEFAULT_EMAIL: ${ULVIA_ACME_EMAIL}

package/dist/definitions/repository.yml

@@ -0,0 +1,32 @@
+services:
+    repository:
+        image: ${OFFICIAL_REPOSITORY_IMAGE}
+        restart: unless-stopped
+        init: true
+        user: "${ULVIA_UID}:${ULVIA_GID}"
+        environment:
+            MODE: PROD
+            NODE_ENV: production
+            REPOSITORY_HOST: 0.0.0.0
+            REPOSITORY_PORT: "3000"
+            REPOSITORY_PUBLIC_URL: ${ULVIA_REPOSITORY_PUBLIC_URL}
+            ULVIA_REPOSITORY_DIR: /var/lib/ulvia-repository
+            ULVIA_REPOSITORY_SEED_DIR: ""
+        volumes:
+            - type: bind
+              source: ${ULVIA_REPOSITORY_DIR}
+              target: /var/lib/ulvia-repository
+        ports:
+            - "127.0.0.1:${ULVIA_REPOSITORY_PORT}:3000"
+        read_only: true
+        tmpfs:
+            - /tmp:rw,nosuid,nodev,noexec,size=64m
+        cap_drop: [ALL]
+        security_opt: [no-new-privileges:true]
+        stop_grace_period: 30s
+        healthcheck:
+            test: ["CMD", "bun", "-e", "const r=await fetch('http://127.0.0.1:3000/readyz'); if(!r.ok) process.exit(1); await r.body?.cancel()"]
+            interval: 30s
+            timeout: 5s
+            retries: 3
+            start_period: 5s

package/dist/definitions/services.yml

@@ -59,10 +59,11 @@ services:
             NODE_ENV: production
             REPOSITORY_HOST: 0.0.0.0
             REPOSITORY_PORT: "3000"
+            REPOSITORY_PUBLIC_URL: http://127.0.0.1:${ULVIA_REPOSITORY_PORT}
             ULVIA_LOG_FILE: /var/log/ulvia/repository.ndjson
             ULVIA_REPOSITORY_DIR: /var/lib/ulvia-repository
             ULVIA_REPOSITORY_SEED_DIR: /opt/ulvia-repository-seed
-            ULVIA_REPOSITORY_TOKEN: ${ULVIA_REPOSITORY_TOKEN}
+        stop_grace_period: 30s
         volumes:
             - type: bind
               source: ${ULVIA_REPOSITORY_DIR}