@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 +192 -105
- package/README.md +59 -25
- package/dist/definitions/{kernel-tls.yml → edge-tls.yml} +1 -1
- package/dist/definitions/{kernel.yml → edge.yml} +7 -11
- package/dist/definitions/services.yml +2 -10
- package/dist/index.js +26407 -22123
- package/package.json +3 -2
package/INSTALLATION.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Install Ulvia
|
|
2
2
|
|
|
3
|
-
This guide installs the Ulvia CLI and
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
-
|
|
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
|
-
|
|
216
|
-
ulvia
|
|
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
|
|
224
|
-
|
|
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
|
-
|
|
259
|
+
### Start Locally And Claim The Publisher
|
|
230
260
|
|
|
231
|
-
|
|
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
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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
|
-
|
|
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
|
|
250
|
-
ulvia identity
|
|
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
|
-
|
|
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
|
|
270
|
-
ulvia
|
|
271
|
-
ulvia
|
|
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
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
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
|
-
|
|
286
|
-
|
|
287
|
-
|
|
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
|
|
291
|
-
ulvia
|
|
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
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
and the
|
|
319
|
-
|
|
320
|
-
client
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
100
|
-
instance's
|
|
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
|
|
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 |
|
|
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
|
|
142
|
-
| `instance start <name>` | Reuses the existing tenant | Starts only that
|
|
143
|
-
| `start` | Never provisions | Starts every existing
|
|
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
|
-
|
|
179
|
-
|
|
180
|
-
`
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
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
|
|
273
|
-
exact manifest claims
|
|
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,26 +1,22 @@
|
|
|
1
1
|
services:
|
|
2
|
-
|
|
3
|
-
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
|
|
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:
|
|
129
|
-
CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "
|
|
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:
|