@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 +109 -177
- package/README.md +75 -65
- package/dist/definitions/services.yml +2 -37
- package/dist/index.js +38758 -26895
- package/package.json +3 -3
- package/dist/definitions/repository-tls.yml +0 -38
- package/dist/definitions/repository.yml +0 -32
package/INSTALLATION.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Install Ulvia
|
|
2
2
|
|
|
3
|
-
This guide installs the Ulvia CLI and runs
|
|
4
|
-
Repository
|
|
5
|
-
|
|
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.
|
|
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@
|
|
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
|
|
62
|
-
`ulvia services start --version
|
|
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
|
|
70
|
-
|
|
71
|
-
|
|
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
|
|
88
|
-
|
|
89
|
-
|
|
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
|
|
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
|
|
140
|
-
ulvia upgrade provider --version
|
|
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.
|
|
150
|
-
|
|
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
|
-
|
|
182
|
-
shared proxy
|
|
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.
|
|
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
|
-
|
|
245
|
-
|
|
246
|
-
|
|
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
|
-
|
|
249
|
-
`acme` below with your own values. Install the published CLI version:
|
|
248
|
+
For a local installation:
|
|
250
249
|
|
|
251
250
|
```bash
|
|
252
|
-
|
|
253
|
-
ulvia --
|
|
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
|
|
257
|
-
`
|
|
258
|
-
|
|
259
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
270
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
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
|
-
|
|
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
|
-
|
|
311
|
-
|
|
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
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
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
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
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
|
-
|
|
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
|
|
358
|
-
ulvia
|
|
359
|
-
ulvia
|
|
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
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
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
|
-
|
|
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
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
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
|
-
|
|
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
|
-
|
|
413
|
-
|
|
414
|
-
|
|
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
|
|
419
|
-
|
|
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
|
```
|