@cyaxis/ulvia 1.0.3 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/INSTALLATION.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Install Ulvia
2
2
 
3
- This guide installs the Ulvia CLI and runs a CMS instance or a standalone
4
- Repository on Ubuntu. For a Repository-only server, follow section 1 and the
5
- standalone Repository procedure in section 9.
3
+ This guide installs the Ulvia CLI and runs CMS instances on Ubuntu, including
4
+ a Repository application. For a dedicated Repository host, use the same shared
5
+ services and follow section 9.
6
6
  It is for operators and site owners; workspace contributors should use the
7
7
  [development guide](../development/README.md).
8
8
 
@@ -29,7 +29,7 @@ docker compose version
29
29
  bun --version
30
30
  ```
31
31
 
32
- The current release toolchain targets Bun 1.4.2 or newer. Docker must be running
32
+ The current release toolchain targets Bun 1.4.4 or newer. Docker must be running
33
33
  and accessible to the account that executes `ulvia`.
34
34
 
35
35
  ## 2. Install The CLI
@@ -44,7 +44,7 @@ ulvia --help
44
44
  If `ulvia` is not found, reopen the terminal and check that `~/.bun/bin` is in
45
45
  `PATH`, as described by the Bun installation guide.
46
46
 
47
- Use an exact version, for example `@cyaxis/ulvia@0.0.3`, when reproducing an
47
+ Use an exact version, for example `@cyaxis/ulvia@1.0.7`, when reproducing an
48
48
  installation. The `next` tag is reserved for explicitly tested prereleases.
49
49
 
50
50
  ## 3. Create A Local Site
@@ -58,18 +58,22 @@ ulvia instance credentials my-site
58
58
  ```
59
59
 
60
60
  The first start uses the exact software version bundled into the installed CLI.
61
- To bootstrap a different exact prerelease explicitly, use
62
- `ulvia services start --version 0.0.1-beta`. This option never upgrades an
61
+ To select an exact initial version explicitly, use
62
+ `ulvia services start --version 1.0.7`. This option never upgrades an
63
63
  existing installation.
64
64
 
65
+ First startup reuses locally cached exact-version images after checking their
66
+ component, stack API, version and immutable digest. It downloads missing images.
67
+ With the runtime and infrastructure images already present, initial provisioning
68
+ can run without Internet access. Explicit image upgrades still pull the requested tag.
69
+
65
70
  The site is available at `http://my-site.localhost:5100`. The credentials
66
71
  command prints the initial administrator email and password. It never prints
67
72
  the Provider, Repository, encryption, or instance service secrets.
68
73
 
69
- The Provider uses `https://repo.ulvia.fr` by default for official artifacts,
70
- collection discovery and instance-owned publications. The shared stack still
71
- contains a loopback-only Repository service, but the Provider uses it only
72
- when explicitly configured.
74
+ The Provider uses `https://repo.ulvia.fr` by default for resource discovery
75
+ and connected-account publications. The shared stack contains the proxy, MongoDB and Provider. Repository hosting
76
+ is selected explicitly on a named CMS instance.
73
77
 
74
78
  When initializing a node, select another Repository by setting
75
79
  `CMS_REPOSITORY_URL` on the first configuration or startup command. For an
@@ -80,19 +84,26 @@ CMS_REPOSITORY_URL=http://repository:3000 \
80
84
  CMS_REPOSITORY_ALLOW_INSECURE_HTTP=true ulvia services start
81
85
  ```
82
86
 
87
+ Here `repository:3000` is a Repository CMS Edge address reachable from the
88
+ Provider containers. Initial provisioning uses the bundled application profile
89
+ before the remote catalogue is available.
90
+
83
91
  The selected connection is persisted as `repository.url` and
84
92
  `repository.allowInsecureHttp` in
85
93
  `~/.local/share/ulvia/services/installation.json`. Later environment changes
86
94
  do not replace an existing connection. To change it, update those fields and
87
- run `ulvia services start`. The target Repository must contain the exact
88
- official contracts, Provider manifest and collection required by the installed
89
- Provider image.
95
+ run `ulvia services start`. The Provider bundles admitted resources needed for initial provisioning; it
96
+ does not need to contact this Repository to bootstrap its shipped profiles.
97
+ Remote discovery and publication still require the configured Repository. An
98
+ origin remains required in configuration even when it is unavailable at bootstrap.
99
+ Creating a Repository instance neither changes that connection nor publishes the
100
+ image-owned bootstrap artifacts into its public catalogue.
90
101
 
91
102
  Ulvia deliberately separates shared services from sites:
92
103
 
93
104
  | Command | Responsibility |
94
105
  | --- | --- |
95
- | `ulvia services start` | Starts the proxy, MongoDB, Official Repository, and Provider. |
106
+ | `ulvia services start` | Starts the proxy, MongoDB and Provider. |
96
107
  | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Edge. |
97
108
  | `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
98
109
  | `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
@@ -136,9 +147,8 @@ ulvia --version
136
147
  Upgrade deployable components independently with exact versions:
137
148
 
138
149
  ```bash
139
- ulvia upgrade edge --version 0.0.1-beta
140
- ulvia upgrade provider --version 0.0.1-beta
141
- ulvia upgrade repository --version 0.0.1-beta
150
+ ulvia upgrade edge --version 1.0.7
151
+ ulvia upgrade provider --version 1.0.7
142
152
  ```
143
153
 
144
154
  Ulvia resolves each official Docker Hub tag to an immutable digest and reuses
@@ -146,8 +156,9 @@ that digest on subsequent starts. Registry channels such as `next` or `latest`
146
156
  may identify releases for humans, but an installation never persists or
147
157
  silently follows those mutable tags.
148
158
 
149
- `upgrade edge` visits every local Edge instance in sequence. Upgrades of
150
- Provider and Repository affect shared services. A failed activation attempts
159
+ `upgrade edge` visits every local Edge instance in sequence. A Provider
160
+ upgrade affects shared services; Repository instances use those same Provider
161
+ and Edge images. A failed activation attempts
151
162
  to restart the previous image, but this does not restore changed database or
152
163
  file contents and is not an atomic rollback across all instances.
153
164
  Take a complete backup before an upgrade involving persisted data. Internal
@@ -178,8 +189,9 @@ TCP traffic on ports 80 and 443. Review Docker's documented firewall behavior:
178
189
  published container ports can bypass some `ufw` and `firewalld` rules unless
179
190
  the host policy uses Docker's supported chains.
180
191
 
181
- Repository and Provider management endpoints remain bound to loopback. Only the
182
- shared proxy is exposed publicly.
192
+ The Provider operator endpoint remains bound to loopback. A Repository is a
193
+ named CMS instance exposed through its Edge and the same shared proxy; it has
194
+ no separate management listener.
183
195
 
184
196
  ## 7. Backup, Reset, And Removal
185
197
 
@@ -227,194 +239,114 @@ For implementation diagnostics and contributor-only environment overrides, see
227
239
  the [development and validation guide](../development/README.md).
228
240
 
229
241
 
230
- ## 9. Standalone Repository
231
-
232
- This is the standard installation on a dedicated Ubuntu server. The CLI owns
233
- one Repository deployment and its HTTPS proxy. No CMS instance, Provider or
234
- database is required.
235
-
236
- ### Prepare The Server
237
-
238
- Complete the Docker Engine, Compose and Bun prerequisites in section 1. The
239
- account running Ulvia must be able to execute `docker version` and
240
- `docker compose version` without `sudo`.
241
-
242
- Before enabling HTTPS:
242
+ ## 9. Repository CMS Instance
243
243
 
244
- - Point the domain's DNS A record to the server's public IPv4 address.
245
- - Make inbound TCP ports 80 and 443 reachable and available on the host.
246
- - Choose a real email address for certificate registration and renewal notices.
244
+ A Repository uses the normal Edge, official Provider and MongoDB deployment.
245
+ It has its own CMS accounts, namespace ownership, uploads and catalogue. No
246
+ separate Repository image or signing-key configuration is required.
247
247
 
248
- Replace `repository.example.com`, `ops@example.com` and the example namespace
249
- `acme` below with your own values. Install the published CLI version:
248
+ For a local installation:
250
249
 
251
250
  ```bash
252
- bun add --global @cyaxis/ulvia@0.1.0-beta
253
- ulvia --version
251
+ ulvia services start
252
+ ulvia instance create registry --profile ulvia.repository@1.0.0
253
+ ulvia instance status registry
254
+ ulvia instance credentials registry
254
255
  ```
255
256
 
256
- The CLI bundles `0.1.0-beta` as its initial stack version. No deployment name or
257
- `global`/`community` qualifier is required.
258
-
259
- ### Start Locally And Claim The Publisher
257
+ The Registry API is available below
258
+ `http://registry.localhost:5100/.cms/call/ulvia.repository`. Its public identity
259
+ endpoint is `GET /v1/info` relative to that prefix. Ordinary CMS instances do not
260
+ expose this contract. The profile creates ordinary CMS Pages for the public
261
+ catalogue, search, resource details, registration/login and personal namespaces,
262
+ publications and PAT management. These Pages use the `ulvia-repository` collection
263
+ and shared `ulvia-official` resources.
260
264
 
261
- Start the Repository before exposing it publicly:
265
+ For public hosting, configure network exposure and ACME as described in section 6
266
+ before creating instances, then create the application on its public domain:
262
267
 
263
268
  ```bash
264
- ulvia repository start
265
- ulvia repository status
266
- curl --fail http://127.0.0.1:5010/readyz
269
+ ulvia instance create registry --domain repository.example.com --profile ulvia.repository@1.0.0
267
270
  ```
268
271
 
269
- The endpoint initially binds only to `127.0.0.1:5010`. Create a local signing
270
- identity and claim the publisher namespace while the server is still private:
272
+ Replace the example domain with a domain routed to this host. The same shared
273
+ proxy handles its HTTPS certificate. Provider management remains on loopback.
271
274
 
272
- ```bash
273
- ulvia identity create owner
274
- ulvia repository login http://127.0.0.1:5010 --identity owner
275
- ulvia namespace claim acme
276
- ulvia namespace status acme
277
- ```
278
-
279
- Save a secure backup of the signing identity before continuing. By default its
280
- private key is `~/.config/ulvia/keys/owner.pem`; preserve the matching client
281
- configuration too. There is no operator recovery after losing every key copy.
282
-
283
- Every namespace follows public first claim, including `ulvia.official`. For an
284
- official Repository, claim that namespace instead of `acme` before public access.
285
- There is no reserved-name bootstrap or operator publication token.
286
-
287
- ### Enable Public HTTPS
275
+ ### Publisher Accounts And Credentials
288
276
 
289
- Persist the domain and certificate configuration, then apply it:
277
+ Registration, password login and PAT management use the normal Access bindings
278
+ under `/.cms/call/ulvia.cms.access`. Registration follows the instance policy.
279
+ An ordinary account can claim and publish; it does not need CMS administrator
280
+ privileges. The protected publisher operations use a shared CMS PAT.
290
281
 
291
- ```bash
292
- ulvia repository configure \
293
- --tls acme \
294
- --public-url https://repository.example.com \
295
- --acme-email ops@example.com
296
-
297
- ulvia repository start
298
- ulvia repository status
299
- ```
282
+ The current API flow is:
300
283
 
301
- This starts the Repository, a dedicated Nginx proxy and its ACME companion.
302
- Only the proxy publishes ports 80/443; the Repository's host endpoint stays on
303
- loopback. Certificates and renewal state persist with the deployment. Issuance
304
- requires working public DNS and HTTP access to port 80. Container readiness does
305
- not by itself confirm that the public certificate has been issued.
284
+ 1. `POST /signup` with `email` and `password`.
285
+ 2. `POST /login-password` with the same credentials; retain its session cookies.
286
+ 3. `POST /personal-access-tokens` with the session cookies and a token `name`.
287
+ An optional `expiresAt` bounds its lifetime. The plaintext token is returned
288
+ only at creation.
289
+ 4. Supply that token to the CLI using bounded stdin or `ULVIA_REPOSITORY_TOKEN`.
306
290
 
307
- After issuance, verify public access and save the HTTPS connection:
291
+ Browser/session mutations use the instance's normal Origin and cookie
292
+ protections. Tokens can be listed with `GET /personal-access-tokens` and revoked
293
+ with `DELETE /personal-access-tokens/:id` by their owning account.
308
294
 
309
295
  ```bash
310
- curl --fail https://repository.example.com/readyz
311
- curl --fail https://repository.example.com/v1/repository
312
- ulvia repository login https://repository.example.com --identity owner
296
+ ulvia repository login https://repository.example.com --token-stdin
297
+ ulvia namespace claim acme
313
298
  ulvia namespace status acme
314
- ```
315
-
316
- The Repository identity and namespace ownership must match the local endpoint.
317
- Public catalogue reads need no credentials; writes require the namespace owner's
318
- signature. Login saves the endpoint and verifies the Repository identity. It
319
- does not create a bearer-token session; private keys stay on the signing host.
320
-
321
- ### Publish Resources
322
-
323
- On a signing machine with the owner identity, release an authored resource and
324
- push its exact coordinate:
325
-
326
- ```bash
327
- ulvia release /path/to/authored-resource
328
- ulvia push contract acme/example.contract@1.0.0
329
- ```
330
-
331
- The development CLI adds recursive release, inferred push kinds and `push all`:
332
-
333
- ```bash
334
299
  ulvia release /path/to/resources --recursive
335
- ulvia push acme/example.contract@1.0.0
336
300
  ulvia push all
337
301
  ```
338
302
 
339
- Recursive release prepares sources locally. `push all` publishes every
340
- non-yanked release in the local cache to the saved Repository, respecting local
341
- dependency order. It verifies all artifacts and namespace owner keys before
342
- uploading. A failed batch can leave completed publications; rerun it to resume
343
- idempotently. A type is required only when a coordinate matches several local
344
- resource kinds. The published `0.1.0-beta` CLI does not yet include these additions.
303
+ Each published resource's `publisherId` must match a namespace owned by the
304
+ account. Contract, Provider manifest and collection dependencies must be present
305
+ before dependent publication; `push all` orders locally available releases.
306
+ Publication never installs a collection on a site.
345
307
 
346
- The resource's `publisherId` must match the owned namespace. Dependencies must
347
- be released and pushed first. Collections and provider manifests use
348
- `push collection` and `push provider`. Publishing does not install a collection
349
- on a CMS site.
308
+ Namespace claims are atomic and limited to 32 owned names per account. Transfer
309
+ uses an explicit target account and expected revision. Suspension retains the
310
+ name; account deletion is refused while it owns namespaces. Startup does not
311
+ reserve or reclaim names, including `ulvia.official`.
350
312
 
351
- Other authors use `repository login` and `namespace claim` with their own local
352
- identities and namespace names. No environment exports are needed.
353
-
354
- ### Daily Operations And Upgrades
313
+ ### Restart And Updates
355
314
 
356
315
  ```bash
357
- ulvia repository status
358
- ulvia repository stop
359
- ulvia repository start
316
+ ulvia instance stop registry
317
+ ulvia instance start registry
318
+ ulvia services status
319
+ ulvia instance status registry
320
+ ulvia upgrade provider --version VERSION
321
+ ulvia upgrade edge --version VERSION
360
322
  ```
361
323
 
362
- Stopping preserves data, identities and certificates. Starts reuse the installed
363
- image digest. To upgrade, use `ulvia repository upgrade --version VERSION`,
364
- replacing `VERSION` with an exact published version. The CLI pulls the tag,
365
- checks the image labels and pins its immutable digest. A failed activation
366
- attempts to restart the previous image; it does not reverse data migrations.
367
- Back up the stopped deployment and signing identities before upgrading.
368
-
369
- `identity import NAME --key-file PATH` copies an existing private key into a
370
- managed local identity. Rotation uses `namespace rotate NAMESPACE
371
- --replacement-identity NAME` and requires both owner and replacement keys.
372
- Revocation uses `namespace revoke NAMESPACE --yes` and is permanent.
373
- `repository logout` removes the connection while preserving local keys.
374
-
375
- ### Configuration And Storage
376
-
377
- Client configuration lives in `$XDG_CONFIG_HOME/ulvia` or `~/.config/ulvia`,
378
- overridable with `ULVIA_CONFIG_DIR`. `config.json` contains public keys, private
379
- key-file references and the active connection; PEM files live in `keys/`.
380
- Files use mode 0600 and directories 0700. Setting only `ULVIA_DATA_DIR` isolates
381
- client settings below `<data>/config`.
382
-
383
- Deployment data defaults to `$XDG_DATA_HOME/ulvia/repository-service` or
384
- `~/.local/share/ulvia/repository-service`, overridable through `ULVIA_DATA_DIR`:
385
-
386
- | Path | Content |
387
- | --- | --- |
388
- | `config.json` | Desired network configuration |
389
- | `service.json` | Installed image digest and last applied configuration |
390
- | `data/` | Repository identity, namespace history, releases and upload/replay state |
391
- | `proxy/` | Certificates, virtual hosts, HTTP challenges and ACME renewal state |
392
-
393
- A complete backup includes the stopped deployment and matching signing
394
- identities. `reset --yes` affects the CMS installation and local release cache;
395
- it preserves the independent Repository deployment and client identities.
396
-
397
- ### Other Network Modes
324
+ Replace `VERSION` with an exact available image version. The CLI pins image
325
+ digests, checks Provider retention before replacing it, and attempts to restore
326
+ the previous image if activation fails. Accounts, ownership, releases, Pages and
327
+ credentials remain in the normal CMS storage.
398
328
 
399
- The standard procedure above uses managed ACME. The CLI also supports:
329
+ A profile change is separate from an image replacement:
330
+ `ulvia instance upgrade-profile registry ID@VERSION`. The target must be a
331
+ supported explicit transition shipped by the Provider and retain the
332
+ `ulvia.repository` application ID. The CLI saves the exact new reference only
333
+ after the Provider acknowledges it. Restart never selects a different profile.
400
334
 
401
- | Mode | Command | Exposure |
402
- | --- | --- | --- |
403
- | Local | `repository configure --tls local --port 5010` | Loopback HTTP only |
404
- | External proxy | `repository configure --tls external --public-url https://repository.example.com` | Loopback backend; the operator supplies and connects the HTTPS proxy |
335
+ Back up the Provider database, file storage, matching encryption credentials and
336
+ private instance configuration together, following section 7. The Repository is
337
+ part of this installation: `reset --yes` deletes its data with the other CMS
338
+ instances. Client `repository logout` removes its saved PAT connection without
339
+ revoking the token remotely.
405
340
 
406
- Run `repository start` after configuration changes. An external proxy must
407
- forward to the backend, allow 100 MiB assets plus protocol overhead and preserve
408
- request bodies. The CLI's external mode does not configure the operator's proxy
409
- or join its Docker network. The public origin controls resource links; forwarded
410
- headers do not override it.
341
+ ### Contributor Verification
411
342
 
412
- Local regression tests validate deployment configuration and publication using
413
- temporary repositories. They do not issue public certificates or contact the
414
- official Repository. Contributor-only image builds and Docker regression tests
415
- are separate from the installation procedure:
343
+ Build Edge and Provider together. The Repository tests create an instance on an
344
+ internal Docker network and use ordinary account PATs; they do not publish
345
+ images or contact the public Repository.
416
346
 
417
347
  ```bash
418
- bun run infra/images/build.ts build --version 0.1.0-repository.0 repository
419
- ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test ./tests/images/official-repository
348
+ bun run images:build --version 0.1.0-integration all
349
+ ULVIA_MCP_EDGE_DOCKER_IMAGE=docker.io/cyaxis/ulvia-edge:0.1.0-integration \
350
+ ULVIA_MCP_PROVIDER_DOCKER_IMAGE=docker.io/cyaxis/ulvia-provider:0.1.0-integration \
351
+ bun test ./tests/images/repository
420
352
  ```