@cyaxis/ulvia 0.1.0-beta → 1.0.0

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,6 +1,8 @@
1
1
  # Install Ulvia
2
2
 
3
- This guide installs the Ulvia CLI and creates a first CMS instance on Ubuntu.
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.
4
6
  It is for operators and site owners; workspace contributors should use the
5
7
  [development guide](../development/README.md).
6
8
 
@@ -64,12 +66,34 @@ The site is available at `http://my-site.localhost:5100`. The credentials
64
66
  command prints the initial administrator email and password. It never prints
65
67
  the Provider, Repository, encryption, or instance service secrets.
66
68
 
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.
73
+
74
+ When initializing a node, select another Repository by setting
75
+ `CMS_REPOSITORY_URL` on the first configuration or startup command. For an
76
+ isolated local installation:
77
+
78
+ ```bash
79
+ CMS_REPOSITORY_URL=http://repository:3000 \
80
+ CMS_REPOSITORY_ALLOW_INSECURE_HTTP=true ulvia services start
81
+ ```
82
+
83
+ The selected connection is persisted as `repository.url` and
84
+ `repository.allowInsecureHttp` in
85
+ `~/.local/share/ulvia/services/installation.json`. Later environment changes
86
+ 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.
90
+
67
91
  Ulvia deliberately separates shared services from sites:
68
92
 
69
93
  | Command | Responsibility |
70
94
  | --- | --- |
71
95
  | `ulvia services start` | Starts the proxy, MongoDB, Official Repository, and Provider. |
72
- | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Kernel. |
96
+ | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Edge. |
73
97
  | `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
74
98
  | `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
75
99
 
@@ -91,12 +115,12 @@ ulvia start
91
115
  ulvia instance stop my-site
92
116
  ulvia instance start my-site
93
117
  ulvia services logs all --level warn
94
- ulvia instance logs my-site kernel
118
+ ulvia instance logs my-site edge
95
119
  ulvia services stop
96
120
  ```
97
121
 
98
122
  Stopping containers preserves persistent data. `services stop` also makes every
99
- site unavailable because Kernels depend on the shared Provider and proxy.
123
+ site unavailable because Edges depend on the shared Provider and proxy.
100
124
 
101
125
  ## 5. Upgrade Ulvia
102
126
 
@@ -112,7 +136,7 @@ ulvia --version
112
136
  Upgrade deployable components independently with exact versions:
113
137
 
114
138
  ```bash
115
- ulvia upgrade kernel --version 0.0.1-beta
139
+ ulvia upgrade edge --version 0.0.1-beta
116
140
  ulvia upgrade provider --version 0.0.1-beta
117
141
  ulvia upgrade repository --version 0.0.1-beta
118
142
  ```
@@ -122,7 +146,7 @@ that digest on subsequent starts. Registry channels such as `next` or `latest`
122
146
  may identify releases for humans, but an installation never persists or
123
147
  silently follows those mutable tags.
124
148
 
125
- `upgrade kernel` visits every local Kernel instance in sequence. Upgrades of
149
+ `upgrade edge` visits every local Edge instance in sequence. Upgrades of
126
150
  Provider and Repository affect shared services. A failed activation attempts
127
151
  to restart the previous image, but this does not restore changed database or
128
152
  file contents and is not an atomic rollback across all instances.
@@ -133,7 +157,8 @@ schema migrations and interrupted-upgrade/restore drills remain
133
157
  ## 6. Public Domain And HTTPS
134
158
 
135
159
  Configure public networking before creating the first instance because the
136
- canonical Kernel URLs become part of Provider provisioning:
160
+ public Edge URLs become part of Provider provisioning. The CLI separately configures
161
+ a private Gateway callback URL and a unique Docker alias for each instance:
137
162
 
138
163
  ```bash
139
164
  ulvia configure network \
@@ -163,7 +188,7 @@ directory. Preserve the complete directory, including MongoDB, files,
163
188
  credentials, encryption material, Repository state, and instance definitions.
164
189
  Do not restore only selected secret or database files from different snapshots.
165
190
 
166
- The CLI has no general backup/restore command. Stop each Kernel with
191
+ The CLI has no general backup/restore command. Stop each Edge with
167
192
  `ulvia instance stop <name>`, then stop shared services before copying their
168
193
  data. Restore and verify a complete backup in an isolated installation before
169
194
  treating it as a recovery guarantee; do not rely on image fallback to recover
@@ -194,7 +219,7 @@ Removing the CLI alone does not delete persistent CMS data or Docker resources.
194
219
  - **An image cannot be pulled:** verify network access and that the requested
195
220
  exact Cyaxis image version has been published.
196
221
  - **An instance returns 503:** check `ulvia services status`, then the Provider
197
- and instance Kernel logs.
222
+ and instance Edge logs.
198
223
  - **Stored encrypted data cannot be opened:** do not generate replacement keys
199
224
  over an existing data directory; restore the matching complete backup.
200
225
 
@@ -204,130 +229,192 @@ the [development and validation guide](../development/README.md).
204
229
 
205
230
  ## 9. Standalone Repository
206
231
 
207
- A public Repository is independent of CMS shared services. It needs Docker and
208
- the CLI, with one persistent local volume and one active server. The commands
209
- below describe the candidate implementation; the exact CLI and image versions
210
- must be published before they can be installed or pulled from a registry.
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`.
211
241
 
212
- On the Repository host, configure networking and start the default deployment:
242
+ Before enabling HTTPS:
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.
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:
213
250
 
214
251
  ```bash
215
- ulvia repository configure --tls external --public-url https://repository.example
216
- ulvia repository start --version 0.1.0
217
- ulvia repository status
218
- ulvia repository stop
219
- ulvia repository start
220
- ulvia repository upgrade --version 0.1.1
252
+ bun add --global @cyaxis/ulvia@0.1.0-beta
253
+ ulvia --version
221
254
  ```
222
255
 
223
- The versions above are examples, not a claim that those images are published.
224
- No `global`, `community` or deployment name is required. The CLI pulls an exact
225
- official image, validates its labels and pins its immutable registry digest.
226
- It does not build or publish images. A failed activation attempts to restart the
227
- previous image; it does not reverse data migrations. Back up data before upgrades.
256
+ The CLI bundles `0.1.0-beta` as its initial stack version. No deployment name or
257
+ `global`/`community` qualifier is required.
228
258
 
229
- Choose one persistent network mode:
259
+ ### Start Locally And Claim The Publisher
230
260
 
231
- | Mode | Configuration | Exposure |
232
- | --- | --- | --- |
233
- | Local | `repository configure --tls local --port 5010` | Loopback HTTP only |
234
- | External proxy | `repository configure --tls external --public-url https://repository.example` | Loopback backend; operator supplies the HTTPS proxy |
235
- | 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 |
261
+ Start the Repository before exposing it publicly:
236
262
 
237
- Run `repository start` after configuring to apply changes. External proxies
238
- forward to `127.0.0.1:5010` (or the configured port), preserve request bodies and
239
- allow 100 MiB assets plus protocol overhead. Managed ACME requires public DNS
240
- pointing to this host and ports 80/443 available; it cannot share these ports
241
- with another local proxy. It starts only Repository, proxy and ACME containers.
242
- Certificate issuance requires the public domain; local tests validate the
243
- Compose model without issuing a public certificate. `REPOSITORY_PUBLIC_URL`
244
- controls resource links; forwarded headers do not override it.
263
+ ```bash
264
+ ulvia repository start
265
+ ulvia repository status
266
+ curl --fail http://127.0.0.1:5010/readyz
267
+ ```
245
268
 
246
- On an author's machine, save the connection once:
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:
247
271
 
248
272
  ```bash
249
- ulvia repository login https://repository.example
250
- ulvia identity list
273
+ ulvia identity create owner
274
+ ulvia repository login http://127.0.0.1:5010 --identity owner
251
275
  ulvia namespace claim acme
252
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
288
+
289
+ Persist the domain and certificate configuration, then apply it:
290
+
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
+ ```
300
+
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.
306
+
307
+ After issuance, verify public access and save the HTTPS connection:
308
+
309
+ ```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
313
+ 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
253
327
  ulvia release /path/to/authored-resource
254
328
  ulvia push contract acme/example.contract@1.0.0
255
- ulvia pull contract acme/example.contract@1.0.0
256
329
  ```
257
330
 
258
- Login creates a default local identity if needed and saves the Repository's
259
- persistent identity. It does not log into a bearer-token session: every mutation
260
- is signed locally. Claim is public, first valid claimant wins. The resource's
261
- `publisherId` must match the owned namespace. Release and push are separate;
262
- dependencies must be released and pushed first. Collections and provider
263
- manifests use `push collection` and `push provider` with exact coordinates.
264
- Publishing an artifact does not install it on a CMS site.
265
-
266
- Create or import named signing identities when needed:
331
+ The development CLI adds recursive release, inferred push kinds and `push all`:
267
332
 
268
333
  ```bash
269
- ulvia identity create official
270
- ulvia identity import imported --key-file /private/existing.pem
271
- ulvia identity use official
272
- ulvia identity public-key official
273
- ulvia repository login https://repository.example --identity official
274
- ulvia identity create replacement
275
- ulvia namespace rotate acme --replacement-identity replacement
276
- ulvia namespace revoke acme --yes
277
- ulvia repository logout
334
+ ulvia release /path/to/resources --recursive
335
+ ulvia push acme/example.contract@1.0.0
336
+ ulvia push all
278
337
  ```
279
338
 
280
- Rotation requires the current owner's key and proof of the replacement key.
281
- Publication automatically selects the saved key matching the current namespace
282
- owner. Revocation is permanent. Losing every copy of an owner key is permanent;
283
- there is no operator recovery. Logout preserves local identities.
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.
345
+
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.
284
350
 
285
- The official public Repository will use `https://repo.ulvia.fr`. Its namespace
286
- `ulvia.official` follows exactly the same first-claim rule. Initialize it on the
287
- host while the service is still available only over loopback:
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
288
355
 
289
356
  ```bash
290
- ulvia repository start --version 0.1.0
291
- ulvia identity create official
292
- ulvia repository login http://127.0.0.1:5010 --identity official
293
- ulvia namespace claim ulvia.official
294
- ulvia repository configure --tls acme --public-url https://repo.ulvia.fr --acme-email ops@ulvia.fr
357
+ ulvia repository status
358
+ ulvia repository stop
295
359
  ulvia repository start
296
- ulvia repository login https://repo.ulvia.fr --identity official
297
- ulvia release /path/to/official-contract
298
- ulvia push contract ulvia.official/example.contract@1.0.0
299
360
  ```
300
361
 
301
- Run the first claim before opening public access. A separate signing machine can
302
- reach the loopback listener through an SSH tunnel instead. There is no reserved
303
- namespace bootstrap or operator token. After the first claim, existing ownership
304
- survives restarts, upgrades, rotations and terminal revocation. Tests use temporary local
305
- repositories; they never contact or publish to `repo.ulvia.fr`.
306
-
307
- Client settings and identities live in `$XDG_CONFIG_HOME/ulvia` or
308
- `~/.config/ulvia`, overridable with `ULVIA_CONFIG_DIR`. `config.json` contains
309
- public keys, key-file references and the active connection; private PEM files
310
- live in `keys/`. Files are private (0600), directories 0700. Preserve secure
311
- backups of keys. Setting only `ULVIA_DATA_DIR` isolates client settings beneath
312
- `<data>/config`, useful for tests or separate installations.
313
-
314
- Deployment configuration lives in `<data>/repository-service/config.json`;
315
- `service.json` records the last applied image and configuration; `data/` holds
316
- Repository identity, namespace history, releases and upload/replay state.
317
- Managed TLS material lives in `proxy/`. Back up the complete stopped deployment
318
- and the matching signing identities. `reset --yes` affects the CMS installation
319
- and local release cache; it preserves independent Repository deployments and
320
- client identities. There is no compatibility path for previous Repository states, deployment names
321
- or token credentials.
322
-
323
- For a contributor's unpublished candidate, use the local Docker regression
324
- runner instead of `repository start`, which intentionally pulls a published
325
- registry image:
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
398
+
399
+ The standard procedure above uses managed ACME. The CLI also supports:
400
+
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 |
405
+
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.
411
+
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:
326
416
 
327
417
  ```bash
328
418
  bun run infra/images/build.ts build --version 0.1.0-repository.0 repository
329
- ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test infra/images/official-repository/tests
419
+ ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test ./tests/images/official-repository
330
420
  ```
331
-
332
- These tests launch loopback-only containers, exercise the CLI against their local
333
- endpoints and remove their temporary data. They publish nothing externally.
package/README.md CHANGED
@@ -38,7 +38,7 @@ bun run ulvia -- instance credentials preview
38
38
  bun run ulvia -- instance stop preview
39
39
  bun run ulvia -- instance delete preview --yes
40
40
  bun run ulvia -- services stop
41
- bun run ulvia -- upgrade kernel --version 0.0.1-beta
41
+ bun run ulvia -- upgrade edge --version 0.0.1-beta
42
42
  bun run ulvia -- upgrade provider --version 0.0.1-beta
43
43
  bun run ulvia -- upgrade repository --version 0.0.1-beta
44
44
  bun run ulvia -- reset --yes
@@ -64,7 +64,7 @@ data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
64
64
  `ULVIA_DATA_DIR` remains an explicit isolation override for tests and CI. The
65
65
  CLI stores authored releases in `<data>/repository`. Shared Provider, Repository,
66
66
  MongoDB, proxy, files, secrets and logs live below `<data>/services`; each
67
- stateless Kernel has independent state and logs below `<data>/instances/<name>`.
67
+ stateless Edge has independent state and logs below `<data>/instances/<name>`.
68
68
  The CLI never starts application servers, supervises their PIDs, or builds
69
69
  software images. It pulls only the canonical public images under
70
70
  `docker.io/cyaxis`, validates their Ulvia component and stack-API labels, and
@@ -87,7 +87,7 @@ ulvia instance create website --domain example.com
87
87
  The configuration is persisted under `<data>/services/installation.json` and
88
88
  is not a per-start mode. ACME requires `0.0.0.0` and every instance in an ACME
89
89
  installation requires an explicit DNS domain. Network configuration is locked
90
- after the first instance because its canonical Kernel URL is part of Provider
90
+ after the first instance because its canonical Edge URL is part of Provider
91
91
  provisioning. Repository and Provider management ports remain loopback-only.
92
92
 
93
93
  `services start` starts only the shared proxy, MongoDB, Repository and Provider.
@@ -96,8 +96,8 @@ an explicit `services start --version <version>` override. Later starts reuse
96
96
  the persisted digests and reject a conflicting `--version`; component changes
97
97
  must go through `upgrade`.
98
98
  `instance create` provisions one isolated Provider tenant and immediately starts
99
- its dedicated Kernel. `instance start` restarts only an already-provisioned
100
- instance's Kernel. All Kernels use the shared proxy port: an instance named
99
+ its dedicated Edge. `instance start` restarts only an already-provisioned
100
+ instance's Edge. All Edges use the shared proxy port: an instance named
101
101
  `default` is available at `http://localhost:5100`, while any other instance such
102
102
  as `preview` uses `http://preview.localhost:5100`.
103
103
  `ULVIA_HTTP_PORT`, `ULVIA_REPOSITORY_PORT`, and `ULVIA_PROVIDER_PORT` provide
@@ -114,7 +114,7 @@ Independent Repository deployments use `ulvia repository start`, `status`, `stop
114
114
  and `upgrade --version <exact-version>`. Their default volume and image pin live
115
115
  below `<data>/repository-service`. No deployment name or `global`/`community`
116
116
  qualifier is required. The command does not start
117
- shared services or a Kernel.
117
+ shared services or a Edge.
118
118
 
119
119
  `ulvia repository login <url>` verifies and saves the remote identity and creates
120
120
  a default local signing identity if none exists. `ulvia identity create`, `import`,
@@ -135,12 +135,12 @@ persists across restarts and cannot be reset through deployment configuration.
135
135
  See the [installation guide](../../../docs/installation/README.md#9-standalone-repository)
136
136
  and [Repository architecture](../../../docs/architecture/community-repository.md).
137
137
 
138
- | Command | Provider tenant | Kernel container |
138
+ | Command | Provider tenant | Edge container |
139
139
  | --- | --- | --- |
140
140
  | `services start` | Does not create one | Does not start one |
141
- | `instance create <name>` | Provisions one durable tenant | Creates and starts its Kernel |
142
- | `instance start <name>` | Reuses the existing tenant | Starts only that Kernel |
143
- | `start` | Never provisions | Starts every existing Kernel after shared services |
141
+ | `instance create <name>` | Provisions one durable tenant | Creates and starts its Edge |
142
+ | `instance start <name>` | Reuses the existing tenant | Starts only that Edge |
143
+ | `start` | Never provisions | Starts every existing Edge after shared services |
144
144
 
145
145
  `instance credentials <name>` prints only that administrator's email and
146
146
  password. Provider operator and instance bearer tokens remain in
@@ -155,6 +155,22 @@ releases. It preserves independent Repository deployments and signing identities
155
155
  `collection`, `contract`, or `provider-manifest`. It validates and stores one
156
156
  immutable release. A provider manifest must reference exact contract releases
157
157
  already in the local repository. Release does not connect to or test a provider.
158
+ `release <directory> --recursive` discovers authored resource roots below a
159
+ folder, stopping before nested Bloc definitions. It orders contracts by
160
+ inheritance and capability requirements, then prepares providers and collections.
161
+ Existing local dependencies are reused. Source admission happens
162
+ before any resource is stored; each resource is committed separately, so a
163
+ storage or publication conflict can leave a partial batch. Retrying identical
164
+ releases is idempotent. Duplicate coordinates and symbolic links are rejected.
165
+ Discovery is bounded to 256 resources, 4096 directories and 32 directory levels;
166
+ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
167
+ explicit separate command.
168
+
169
+ ```bash
170
+ ulvia release packages/official-repository/contracts --recursive
171
+ ulvia release packages/official-repository --recursive
172
+ ```
173
+
158
174
  Contract fixture assets declared in `definition.json` are read from
159
175
  `fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
160
176
  different content fails. The local Repository serves stored resources
@@ -175,19 +191,28 @@ sorts capabilities and mocks by their declared IDs, so paths never affect the
175
191
  immutable digest. `definition.json` cannot contain an inline `capabilities`
176
192
  array: the recursive source tree is the only authored contract format.
177
193
 
178
- An optional conformance companion uses `conformance/definition.json`, recursive
179
- `conformance/scenarios/**/*.json` scenario objects and recursive
180
- `conformance/exemptions/**/*.json` coverage-exemption objects. Optional suite
181
- fixture bytes live below `conformance/fixtures/<asset-id>`. The release command
182
- assembles and admits a present suite, including exact locally released
183
- dependencies, before storing the contract. Conformance publication and live
184
- execution are separate Gateway/repository APIs; the CLI does not yet orchestrate
185
- a disposable provider environment.
186
-
187
- `push` publishes one exact local coordinate, and `pull` downloads and re-admits
188
- one exact remote coordinate before storing it locally. Both support
189
- `collection`, `contract`, and `provider`; dependencies must be transferred
190
- first. `repository login` saves the default endpoint; `--repository` and
194
+ `push <publisher/id@version>` infers the kind from local cached releases. If the
195
+ same coordinate exists in several catalogues, specify `push contract`,
196
+ `push collection` or `push provider` to resolve the ambiguity. `pull` still takes
197
+ an explicit kind and downloads and re-admits one exact coordinate locally.
198
+
199
+ `push all` publishes every non-yanked release in the local cache, independently
200
+ of the working directory. It orders contract inheritance and requirements,
201
+ then providers and known local collection dependencies. All artifacts and every
202
+ namespace's local owner key are checked before the first upload. No namespace
203
+ is implicitly claimed and releases without an owner key are not silently skipped.
204
+ A remote refusal or transfer failure stops the batch; already completed
205
+ publications remain visible. Repeating the command reconciles identical releases
206
+ and resumes the remainder. The receiving Repository still validates dependency
207
+ availability and every immutable artifact. For single pushes, transfer required
208
+ dependencies first.
209
+
210
+ ```bash
211
+ ulvia push ulvia.official/ulvia.cms.emailer@1.0.0
212
+ ulvia push all
213
+ ```
214
+
215
+ `repository login` saves the default endpoint; `--repository` and
191
216
  `ULVIA_REPOSITORY_URL` remain explicit overrides. Owner signatures bind Repository
192
217
  identity, namespace revision, action, content digest, timestamp and nonce.
193
218
  The server rejects stale or replayed
@@ -269,5 +294,14 @@ Publication, provider profile transitions, collection upgrades and container
269
294
  image replacement remain separate actions.
270
295
 
271
296
  `instance create` provisions the named instance through the Provider operator
272
- API, then starts its Kernel. Connection review validates the runtime report and
273
- exact manifest claims; it does not yet execute a live conformance suite.
297
+ API, then starts its Edge. Connection review validates the runtime report and
298
+ exact manifest claims. Provider behavior is covered by implementation-owned tests.
299
+
300
+ ## Collection examples
301
+
302
+ `ulvia preview <collection-directory> --output <new-directory> [--dependency <directory>] [--locale <locale>] [--theme-mode <light|dark>] [--no-screenshots] [--serve]`
303
+ exports collection example frames, generated PNGs, an interactive local explorer and a
304
+ provenance manifest. Screenshots require the Playwright Chromium browser
305
+ (`bunx playwright@1.63.0 install chromium`). Dependencies and required contracts are
306
+ resolved explicitly from local sources/cache; preview never publishes. See
307
+ [collection examples](../../../docs/blocs/examples.md) for source and release formats.
@@ -1,5 +1,5 @@
1
1
  services:
2
- kernel:
2
+ edge:
3
3
  environment:
4
4
  ACME_HOST: ${ULVIA_INSTANCE_HOSTNAME}
5
5
  LETSENCRYPT_HOST: ${ULVIA_INSTANCE_HOSTNAME}
@@ -1,26 +1,22 @@
1
1
  services:
2
- kernel:
3
- image: ${KERNEL_IMAGE}
2
+ edge:
3
+ image: ${EDGE_IMAGE}
4
4
  restart: unless-stopped
5
5
  init: true
6
6
  user: "${ULVIA_UID}:${ULVIA_GID}"
7
7
  environment:
8
8
  MODE: PROD
9
9
  NODE_ENV: production
10
- KERNEL_HOST: 0.0.0.0
11
- KERNEL_PORT: "3000"
12
- KERNEL_PUBLIC_URL: ${ULVIA_INSTANCE_URL}
10
+ CMS_HOST: 0.0.0.0
11
+ CMS_PORT: "3000"
12
+ CMS_PUBLIC_URL: ${ULVIA_INSTANCE_URL}
13
13
  CMS_INSTALLATIONS_PROVIDER_URL: http://ulvia-provider:5103
14
14
  CMS_INSTALLATIONS_PROVIDER_TOKEN: ${CMS_INSTALLATIONS_PROVIDER_TOKEN}
15
- ULVIA_LOG_FILE: /var/log/ulvia/kernel.ndjson
16
15
  VIRTUAL_HOST: ${ULVIA_INSTANCE_HOSTNAME}
17
16
  VIRTUAL_PORT: "3000"
18
- volumes:
19
- - type: bind
20
- source: ${ULVIA_LOGS_DIR}
21
- target: /var/log/ulvia
22
17
  networks:
23
- - instances
18
+ instances:
19
+ aliases: ["${ULVIA_EDGE_NETWORK_ALIAS}"]
24
20
  read_only: true
25
21
  tmpfs:
26
22
  - /tmp:rw,nosuid,nodev,noexec,size=256m
@@ -60,7 +60,6 @@ services:
60
60
  REPOSITORY_HOST: 0.0.0.0
61
61
  REPOSITORY_PORT: "3000"
62
62
  REPOSITORY_PUBLIC_URL: http://127.0.0.1:${ULVIA_REPOSITORY_PORT}
63
- ULVIA_LOG_FILE: /var/log/ulvia/repository.ndjson
64
63
  ULVIA_REPOSITORY_DIR: /var/lib/ulvia-repository
65
64
  ULVIA_REPOSITORY_SEED_DIR: /opt/ulvia-repository-seed
66
65
  stop_grace_period: 30s
@@ -68,9 +67,6 @@ services:
68
67
  - type: bind
69
68
  source: ${ULVIA_REPOSITORY_DIR}
70
69
  target: /var/lib/ulvia-repository
71
- - type: bind
72
- source: ${ULVIA_LOGS_DIR}
73
- target: /var/log/ulvia
74
70
  ports:
75
71
  - "127.0.0.1:${ULVIA_REPOSITORY_PORT}:3000"
76
72
  networks:
@@ -125,12 +121,11 @@ services:
125
121
  MODE: PROD
126
122
  NODE_ENV: production
127
123
  CMS_FILES_DIR: /var/lib/cms/files
128
- CMS_REPOSITORY_URL: http://repository:3000
129
- CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "true"
124
+ CMS_REPOSITORY_URL: ${CMS_REPOSITORY_URL:-https://repo.ulvia.fr}
125
+ CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "${CMS_REPOSITORY_ALLOW_INSECURE_HTTP:-false}"
130
126
  CMS_SESSION_SECRET: ${ULVIA_PROVIDER_SESSION_SECRET}
131
127
  CMS_KEK_HEX: ${ULVIA_PROVIDER_KEK_HEX}
132
128
  MONGO_URL: mongodb://${ULVIA_MONGO_PROVIDER_USERNAME}:${ULVIA_MONGO_PROVIDER_PASSWORD}@mongo:27017/ulvia_provider_control?authSource=admin&retryWrites=false
133
- ULVIA_LOG_FILE: /var/log/ulvia/provider.ndjson
134
129
  ULVIA_PROVIDER_HOST: 0.0.0.0
135
130
  ULVIA_PROVIDER_PORT: "5103"
136
131
  ULVIA_PROVIDER_PUBLIC_URL: http://ulvia-provider:5103
@@ -139,9 +134,6 @@ services:
139
134
  - type: bind
140
135
  source: ${ULVIA_FILES_DIR}
141
136
  target: /var/lib/cms/files
142
- - type: bind
143
- source: ${ULVIA_LOGS_DIR}
144
- target: /var/log/ulvia
145
137
  ports:
146
138
  - "127.0.0.1:${ULVIA_PROVIDER_PORT}:5103"
147
139
  networks: