@cyaxis/ulvia 1.0.7 → 1.0.12
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 +32 -64
- package/README.md +56 -36
- package/dist/definitions/services.yml +0 -2
- package/dist/index.js +20144 -15048
- package/package.json +1 -1
package/INSTALLATION.md
CHANGED
|
@@ -71,53 +71,24 @@ The site is available at `http://my-site.localhost:5100`. The credentials
|
|
|
71
71
|
command prints the initial administrator email and password. It never prints
|
|
72
72
|
the Provider, Repository, encryption, or instance service secrets.
|
|
73
73
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
`repository.allowInsecureHttp` in
|
|
93
|
-
`~/.local/share/ulvia/services/installation.json`. Later environment changes
|
|
94
|
-
do not replace an existing connection. To change it, update those fields and
|
|
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.
|
|
101
|
-
|
|
102
|
-
Ulvia deliberately separates shared services from sites:
|
|
103
|
-
|
|
104
|
-
| Command | Responsibility |
|
|
105
|
-
| --- | --- |
|
|
106
|
-
| `ulvia services start` | Starts the proxy, MongoDB and Provider. |
|
|
107
|
-
| `ulvia instance create <name>` | Provisions one Provider tenant and starts its Edge. |
|
|
108
|
-
| `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
|
|
109
|
-
| `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
|
|
110
|
-
|
|
111
|
-
List and inspect the installation at any time:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
ulvia services status
|
|
115
|
-
ulvia instance list
|
|
116
|
-
ulvia instance status my-site
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
Persistent data lives below `$XDG_DATA_HOME/ulvia` or
|
|
120
|
-
`~/.local/share/ulvia`. Commands can be run from any working directory.
|
|
74
|
+
Open `http://my-site.localhost:5100/.cms/setup` and use those credentials. Fresh
|
|
75
|
+
instances create zero collections and Pages. Choose an empty site or explicitly
|
|
76
|
+
review a recipe from a published collection; no starter or administration site
|
|
77
|
+
is bundled. Empty completion leaves `/` returning 404 until a Page is published.
|
|
78
|
+
See [first published Page](../product/first-published-page.md) for the current API flow.
|
|
79
|
+
|
|
80
|
+
Setup first offers **A Repository address**, **The official Repository**
|
|
81
|
+
(`https://repo.ulvia.fr`), or **A new Repository** on this instance. Then choose
|
|
82
|
+
an empty site or review a published collection recipe. The URL is stored per
|
|
83
|
+
instance; there is no global Repository environment variable or service setting.
|
|
84
|
+
The address must be reachable from the Provider. HTTP origins are an explicit
|
|
85
|
+
choice; credentials, queries and fragments are forbidden in settings URLs.
|
|
86
|
+
|
|
87
|
+
A new Repository installs Registry from the system resources already in the
|
|
88
|
+
image and selects this site’s public Edge origin. Its catalogue starts empty.
|
|
89
|
+
Self-origin calls use the known private Edge transport; no remote catalogue is
|
|
90
|
+
needed for creation or empty completion. Changing a Repository URL affects future
|
|
91
|
+
discovery/imports, preserving installed resources and Pages.
|
|
121
92
|
|
|
122
93
|
## 4. Daily Operations
|
|
123
94
|
|
|
@@ -162,8 +133,8 @@ and Edge images. A failed activation attempts
|
|
|
162
133
|
to restart the previous image, but this does not restore changed database or
|
|
163
134
|
file contents and is not an atomic rollback across all instances.
|
|
164
135
|
Take a complete backup before an upgrade involving persisted data. Internal
|
|
165
|
-
schema migrations and interrupted-upgrade/restore drills
|
|
166
|
-
|
|
136
|
+
schema migrations and interrupted-upgrade/restore drills require explicit
|
|
137
|
+
implementation and deployment-level verification.
|
|
167
138
|
|
|
168
139
|
## 6. Public Domain And HTTPS
|
|
169
140
|
|
|
@@ -204,7 +175,7 @@ The CLI has no general backup/restore command. Stop each Edge with
|
|
|
204
175
|
`ulvia instance stop <name>`, then stop shared services before copying their
|
|
205
176
|
data. Restore and verify a complete backup in an isolated installation before
|
|
206
177
|
treating it as a recovery guarantee; do not rely on image fallback to recover
|
|
207
|
-
data.
|
|
178
|
+
data.
|
|
208
179
|
|
|
209
180
|
`reset` permanently removes Ulvia-owned local state:
|
|
210
181
|
|
|
@@ -249,24 +220,24 @@ For a local installation:
|
|
|
249
220
|
|
|
250
221
|
```bash
|
|
251
222
|
ulvia services start
|
|
252
|
-
ulvia instance create registry
|
|
223
|
+
ulvia instance create registry
|
|
253
224
|
ulvia instance status registry
|
|
254
225
|
ulvia instance credentials registry
|
|
255
226
|
```
|
|
256
227
|
|
|
257
228
|
The Registry API is available below
|
|
258
|
-
`http://registry.localhost:5100/.cms/call/ulvia
|
|
229
|
+
`http://registry.localhost:5100/.cms/call/ulvia/repository`. Its public identity
|
|
259
230
|
endpoint is `GET /v1/info` relative to that prefix. Ordinary CMS instances do not
|
|
260
|
-
expose this contract.
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
231
|
+
expose this contract. Open `/.cms/setup`, sign in and choose **A new Repository**
|
|
232
|
+
to activate it. Creation starts with an administrator and system APIs,
|
|
233
|
+
without any collection or Page. Publish resources through the CLI/API and install
|
|
234
|
+
a website explicitly if needed.
|
|
264
235
|
|
|
265
236
|
For public hosting, configure network exposure and ACME as described in section 6
|
|
266
237
|
before creating instances, then create the application on its public domain:
|
|
267
238
|
|
|
268
239
|
```bash
|
|
269
|
-
ulvia instance create registry --domain repository.example.com
|
|
240
|
+
ulvia instance create registry --domain repository.example.com
|
|
270
241
|
```
|
|
271
242
|
|
|
272
243
|
Replace the example domain with a domain routed to this host. The same shared
|
|
@@ -275,7 +246,7 @@ proxy handles its HTTPS certificate. Provider management remains on loopback.
|
|
|
275
246
|
### Publisher Accounts And Credentials
|
|
276
247
|
|
|
277
248
|
Registration, password login and PAT management use the normal Access bindings
|
|
278
|
-
under `/.cms/call/ulvia
|
|
249
|
+
under `/.cms/call/ulvia/cms.access`. Registration follows the instance policy.
|
|
279
250
|
An ordinary account can claim and publish; it does not need CMS administrator
|
|
280
251
|
privileges. The protected publisher operations use a shared CMS PAT.
|
|
281
252
|
|
|
@@ -308,7 +279,7 @@ Publication never installs a collection on a site.
|
|
|
308
279
|
Namespace claims are atomic and limited to 32 owned names per account. Transfer
|
|
309
280
|
uses an explicit target account and expected revision. Suspension retains the
|
|
310
281
|
name; account deletion is refused while it owns namespaces. Startup does not
|
|
311
|
-
reserve or reclaim names, including `ulvia
|
|
282
|
+
reserve or reclaim names, including `ulvia`.
|
|
312
283
|
|
|
313
284
|
### Restart And Updates
|
|
314
285
|
|
|
@@ -326,11 +297,8 @@ digests, checks Provider retention before replacing it, and attempts to restore
|
|
|
326
297
|
the previous image if activation fails. Accounts, ownership, releases, Pages and
|
|
327
298
|
credentials remain in the normal CMS storage.
|
|
328
299
|
|
|
329
|
-
|
|
330
|
-
|
|
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.
|
|
300
|
+
Installed contract and collection upgrades are separate from image replacement.
|
|
301
|
+
They use explicit admitted Installations workflows; restart never selects new pins.
|
|
334
302
|
|
|
335
303
|
Back up the Provider database, file storage, matching encryption credentials and
|
|
336
304
|
private instance configuration together, following section 7. The Repository is
|
package/README.md
CHANGED
|
@@ -41,16 +41,19 @@ bun run ulvia -- services stop
|
|
|
41
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 -- reset --yes
|
|
44
|
-
bun run ulvia -- release
|
|
44
|
+
bun run ulvia -- release ./my-collection
|
|
45
45
|
bun run ulvia -- release /path/to/contract-directory
|
|
46
46
|
bun run ulvia -- release /path/to/provider-directory
|
|
47
|
-
bun run ulvia -- push contract ulvia
|
|
48
|
-
bun run ulvia -- pull collection
|
|
49
|
-
bun run ulvia -- yank collection
|
|
50
|
-
bun run ulvia -- restore collection
|
|
47
|
+
bun run ulvia -- push contract ulvia/cms.installations@1.3.0 --repository https://repository.example
|
|
48
|
+
bun run ulvia -- pull collection example/ui@1.0.0 --repository https://repository.example
|
|
49
|
+
bun run ulvia -- yank collection example/ui@1.0.0 --repository https://repository.example --reason "Superseded"
|
|
50
|
+
bun run ulvia -- restore collection example/ui@1.0.0 --repository https://repository.example
|
|
51
51
|
bun run ulvia -- prune
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
+
`example/ui` is a hypothetical collection to be authored and published explicitly;
|
|
55
|
+
no official starter collection is bundled.
|
|
56
|
+
|
|
54
57
|
The stack version above is an example of an exact published image tag. Workspace
|
|
55
58
|
source has no embedded initial stack version: its first `services start`
|
|
56
59
|
requires `--version`. Packaged releases embed that default at build time. Later
|
|
@@ -110,22 +113,26 @@ previously created local instance; it never creates an implicit instance.
|
|
|
110
113
|
|
|
111
114
|
The lifecycle boundary is deliberate:
|
|
112
115
|
|
|
113
|
-
A Repository is an ordinary named CMS instance
|
|
114
|
-
profile:
|
|
116
|
+
A Repository is an ordinary named CMS instance:
|
|
115
117
|
|
|
116
118
|
```bash
|
|
117
119
|
ulvia services start
|
|
118
|
-
ulvia instance create registry
|
|
120
|
+
ulvia instance create registry
|
|
119
121
|
ulvia instance status registry
|
|
122
|
+
ulvia instance credentials registry
|
|
120
123
|
```
|
|
121
124
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
125
|
+
Open its `/.cms/setup`, sign in and choose **A new Repository**. The other
|
|
126
|
+
buttons accept a Repository address or select `https://repo.ulvia.fr`.
|
|
127
|
+
Creation installs system APIs and the administrator, with zero collections and
|
|
128
|
+
Pages. Repository settings belong to this instance; there is no `--profile`,
|
|
129
|
+
`upgrade-profile`, or shared Repository environment setting. Changing sources
|
|
130
|
+
preserves installed pins. An empty site can finish setup offline.
|
|
131
|
+
|
|
132
|
+
`upgrade provider --version VERSION` replaces the shared image with retention
|
|
133
|
+
checks and rollback on activation failure. Installed resources and credentials
|
|
134
|
+
remain in Provider storage; explicit contract/collection upgrades use their
|
|
135
|
+
admitted workflows. Registry needs no separate image, service or port.
|
|
129
136
|
|
|
130
137
|
`repository login URL` verifies the Repository identity and saves a shared CMS
|
|
131
138
|
PAT supplied through `ULVIA_REPOSITORY_TOKEN` or `--token-stdin`. Ordinary
|
|
@@ -163,13 +170,14 @@ removes shared Compose projects, instances, shared state and local repository
|
|
|
163
170
|
releases, including accounts hosted by this local Provider. Independently deployed
|
|
164
171
|
Repositories and the CLI's saved Repository connection are preserved. It does not
|
|
165
172
|
inspect or modify the current working directory.
|
|
166
|
-
`release <resource-directory>`
|
|
173
|
+
`release <resource-directory>` accepts a trusted local `ulvia.release.ts` entry
|
|
174
|
+
or reads `definition.json` and routes by `kind`:
|
|
167
175
|
`collection`, `contract`, or `provider-manifest`. It validates and stores one
|
|
168
176
|
immutable release. A provider manifest must reference exact contract releases
|
|
169
177
|
already in the local repository. Release does not connect to or test a provider.
|
|
170
178
|
`release <directory> --recursive` discovers authored resource roots below a
|
|
171
179
|
folder, stopping before nested Bloc definitions. It orders contracts by
|
|
172
|
-
inheritance
|
|
180
|
+
inheritance, then prepares Provider manifests and collection dependencies.
|
|
173
181
|
Existing local dependencies are reused. Source admission happens
|
|
174
182
|
before any resource is stored; each resource is committed separately, so a
|
|
175
183
|
storage or publication conflict can leave a partial batch. Retrying identical
|
|
@@ -179,16 +187,23 @@ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
|
|
|
179
187
|
explicit separate command.
|
|
180
188
|
|
|
181
189
|
```bash
|
|
182
|
-
ulvia release
|
|
183
|
-
|
|
190
|
+
ulvia release infra/releases
|
|
191
|
+
bun run release:official
|
|
192
|
+
# Equivalent SDK source entry:
|
|
193
|
+
ulvia release infra/releases
|
|
184
194
|
```
|
|
185
195
|
|
|
196
|
+
The official build uses a trusted local `ulvia.release.ts` entry so all SDK
|
|
197
|
+
features, manifest claims and the bootstrap share the same inventory and compiler. See the
|
|
198
|
+
[SDK workflow](../../../docs/development/sdk-releases.md) for explicit versions,
|
|
199
|
+
source-module rules and generated runtime attachment.
|
|
200
|
+
|
|
186
201
|
Contract fixture assets declared in `definition.json` are read from
|
|
187
202
|
`fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
|
|
188
203
|
different content fails. Local release storage is a private CLI cache, not an
|
|
189
204
|
HTTP server. `push` publishes it to the configured CMS Repository; its public
|
|
190
|
-
catalogue and downloads use admitted `ulvia
|
|
191
|
-
`/.cms/call/ulvia
|
|
205
|
+
catalogue and downloads use admitted `ulvia/repository` bindings under
|
|
206
|
+
`/.cms/call/ulvia/repository`. CMS installation and Provider administration
|
|
192
207
|
consume those public sources. `prune` empties the local cache without deleting
|
|
193
208
|
service or instance data.
|
|
194
209
|
|
|
@@ -198,7 +213,8 @@ object. Optional `mocks/**/*.json` fragments contain one mock plus its explicit
|
|
|
198
213
|
`capabilityId`; mocks embedded in capability fragments reject. The compiler
|
|
199
214
|
sorts capabilities and mocks by their declared IDs, so paths never affect the
|
|
200
215
|
immutable digest. `definition.json` cannot contain an inline `capabilities`
|
|
201
|
-
array
|
|
216
|
+
array in this JSON source format. SDK features instead use `defineFeature` and
|
|
217
|
+
explicit capabilities/mocks, producing the same admitted release format.
|
|
202
218
|
|
|
203
219
|
`push <publisher/id@version>` infers the kind from local cached releases. If the
|
|
204
220
|
same coordinate exists in several catalogues, specify `push contract`,
|
|
@@ -206,7 +222,7 @@ same coordinate exists in several catalogues, specify `push contract`,
|
|
|
206
222
|
an explicit kind and downloads and re-admits one exact coordinate locally.
|
|
207
223
|
|
|
208
224
|
`push all` publishes every non-yanked release in the local cache, independently
|
|
209
|
-
of the working directory. It orders contract inheritance
|
|
225
|
+
of the working directory. It orders contract inheritance,
|
|
210
226
|
then providers and known local collection dependencies. All artifacts and every
|
|
211
227
|
namespace's account ownership are checked before the first upload. No namespace
|
|
212
228
|
is implicitly claimed and releases without usable account credentials are not silently skipped.
|
|
@@ -217,7 +233,7 @@ availability and every immutable artifact. For single pushes, transfer required
|
|
|
217
233
|
dependencies first.
|
|
218
234
|
|
|
219
235
|
```bash
|
|
220
|
-
ulvia push ulvia
|
|
236
|
+
ulvia push ulvia/cms.emailer@1.0.0
|
|
221
237
|
ulvia push all
|
|
222
238
|
```
|
|
223
239
|
|
|
@@ -230,7 +246,7 @@ lengths and SHA-256 digests, and makes the artifact visible last. Exact retries
|
|
|
230
246
|
are idempotent; different bytes at an existing coordinate reject.
|
|
231
247
|
|
|
232
248
|
The protocol and exact-coordinate client live in
|
|
233
|
-
`@bernouy/
|
|
249
|
+
`@bernouy/repository/repository/publication`. The CLI and CMS authoring
|
|
234
250
|
implementation share those clients. The official Provider composes the domain
|
|
235
251
|
service and persistence for explicitly enabled Repository instances; Edge
|
|
236
252
|
exposes the selected admitted contract. The Repository uses ordinary CMS capabilities and account PATs.
|
|
@@ -280,31 +296,35 @@ ID, and discovery stops there so `settings/definition.json` is never mistaken
|
|
|
280
296
|
for a nested Bloc. Intermediate grouping directories contain only directories
|
|
281
297
|
and do not affect release identity.
|
|
282
298
|
|
|
283
|
-
The Provider image bundles admitted contracts,
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
from the
|
|
299
|
+
The production Provider image bundles admitted system contracts, documentation
|
|
300
|
+
and the Provider manifest, without authored collections or starter assets. An
|
|
301
|
+
incomplete snapshot fails explicitly; bootstrap does not fall back to the network.
|
|
302
|
+
Restart preserves existing accounts, namespace ownership and edited Pages and
|
|
303
|
+
reopens ready instances from their persisted execution. Generate the API-only
|
|
304
|
+
snapshot from the SDK feature inventory with:
|
|
289
305
|
|
|
290
306
|
```bash
|
|
291
307
|
bun run generate:official-bootstrap
|
|
292
308
|
```
|
|
293
309
|
|
|
294
310
|
That command neither publishes to a running repository nor upgrades an existing
|
|
295
|
-
instance.
|
|
296
|
-
|
|
297
|
-
|
|
311
|
+
instance. Collections are built and published only from explicitly supplied
|
|
312
|
+
sources; no starter collection is included in this command.
|
|
313
|
+
For individual manual releases, use `release` in dependency order:
|
|
314
|
+
exact parent contracts before specializations, then Provider manifests and collection dependencies.
|
|
315
|
+
Publication, system installation transitions, collection upgrades and container
|
|
298
316
|
image replacement remain separate actions.
|
|
299
317
|
|
|
300
318
|
`instance create` provisions the named instance through the Provider operator
|
|
301
319
|
API, then starts its Edge. Connection review validates the runtime report and
|
|
302
320
|
exact manifest claims. Provider behavior is covered by implementation-owned tests.
|
|
303
321
|
|
|
304
|
-
|
|
322
|
+
Official releases evolve independently: the current installations contract and
|
|
323
|
+
Provider manifest use `1.3.0`; local formats remain `v1`. Collections are supplied
|
|
324
|
+
and versioned by their authors.
|
|
305
325
|
Each named instance uses `<name>.localhost` unless an explicit domain is supplied;
|
|
306
326
|
`default` is an ordinary name. Repository hosting uses a CMS instance with the
|
|
307
|
-
|
|
327
|
+
explicit Registry installation. Client PAT connections and local release caches
|
|
308
328
|
are separate from the shared services and instance lifecycle.
|
|
309
329
|
|
|
310
330
|
## Collection examples
|
|
@@ -87,8 +87,6 @@ services:
|
|
|
87
87
|
MODE: PROD
|
|
88
88
|
NODE_ENV: production
|
|
89
89
|
CMS_FILES_DIR: /var/lib/cms/files
|
|
90
|
-
CMS_REPOSITORY_URL: ${CMS_REPOSITORY_URL:-https://repo.ulvia.fr}
|
|
91
|
-
CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "${CMS_REPOSITORY_ALLOW_INSECURE_HTTP:-false}"
|
|
92
90
|
CMS_SESSION_SECRET: ${ULVIA_PROVIDER_SESSION_SECRET}
|
|
93
91
|
CMS_KEK_ACTIVE_ID: ${ULVIA_PROVIDER_KEK_ACTIVE_ID}
|
|
94
92
|
CMS_KEK_RING_JSON: ${ULVIA_PROVIDER_KEK_RING_JSON}
|