@cyaxis/ulvia 0.1.0-beta → 0.1.0-beta.1
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 +160 -96
- package/README.md +39 -4
- package/dist/index.js +760 -293
- package/package.json +1 -1
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
|
|
|
@@ -204,130 +206,192 @@ the [development and validation guide](../development/README.md).
|
|
|
204
206
|
|
|
205
207
|
## 9. Standalone Repository
|
|
206
208
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
must be published before they can be installed or pulled from a registry.
|
|
209
|
+
This is the standard installation on a dedicated Ubuntu server. The CLI owns
|
|
210
|
+
one Repository deployment and its HTTPS proxy. No CMS instance, Provider or
|
|
211
|
+
database is required.
|
|
211
212
|
|
|
212
|
-
|
|
213
|
+
### Prepare The Server
|
|
214
|
+
|
|
215
|
+
Complete the Docker Engine, Compose and Bun prerequisites in section 1. The
|
|
216
|
+
account running Ulvia must be able to execute `docker version` and
|
|
217
|
+
`docker compose version` without `sudo`.
|
|
218
|
+
|
|
219
|
+
Before enabling HTTPS:
|
|
220
|
+
|
|
221
|
+
- Point the domain's DNS A record to the server's public IPv4 address.
|
|
222
|
+
- Make inbound TCP ports 80 and 443 reachable and available on the host.
|
|
223
|
+
- Choose a real email address for certificate registration and renewal notices.
|
|
224
|
+
|
|
225
|
+
Replace `repository.example.com`, `ops@example.com` and the example namespace
|
|
226
|
+
`acme` below with your own values. Install the published CLI version:
|
|
213
227
|
|
|
214
228
|
```bash
|
|
215
|
-
|
|
216
|
-
ulvia
|
|
217
|
-
ulvia repository status
|
|
218
|
-
ulvia repository stop
|
|
219
|
-
ulvia repository start
|
|
220
|
-
ulvia repository upgrade --version 0.1.1
|
|
229
|
+
bun add --global @cyaxis/ulvia@0.1.0-beta
|
|
230
|
+
ulvia --version
|
|
221
231
|
```
|
|
222
232
|
|
|
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.
|
|
233
|
+
The CLI bundles `0.1.0-beta` as its initial stack version. No deployment name or
|
|
234
|
+
`global`/`community` qualifier is required.
|
|
228
235
|
|
|
229
|
-
|
|
236
|
+
### Start Locally And Claim The Publisher
|
|
230
237
|
|
|
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 |
|
|
238
|
+
Start the Repository before exposing it publicly:
|
|
236
239
|
|
|
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.
|
|
240
|
+
```bash
|
|
241
|
+
ulvia repository start
|
|
242
|
+
ulvia repository status
|
|
243
|
+
curl --fail http://127.0.0.1:5010/readyz
|
|
244
|
+
```
|
|
245
245
|
|
|
246
|
-
|
|
246
|
+
The endpoint initially binds only to `127.0.0.1:5010`. Create a local signing
|
|
247
|
+
identity and claim the publisher namespace while the server is still private:
|
|
247
248
|
|
|
248
249
|
```bash
|
|
249
|
-
ulvia
|
|
250
|
-
ulvia identity
|
|
250
|
+
ulvia identity create owner
|
|
251
|
+
ulvia repository login http://127.0.0.1:5010 --identity owner
|
|
251
252
|
ulvia namespace claim acme
|
|
252
253
|
ulvia namespace status acme
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Save a secure backup of the signing identity before continuing. By default its
|
|
257
|
+
private key is `~/.config/ulvia/keys/owner.pem`; preserve the matching client
|
|
258
|
+
configuration too. There is no operator recovery after losing every key copy.
|
|
259
|
+
|
|
260
|
+
Every namespace follows public first claim, including `ulvia.official`. For an
|
|
261
|
+
official Repository, claim that namespace instead of `acme` before public access.
|
|
262
|
+
There is no reserved-name bootstrap or operator publication token.
|
|
263
|
+
|
|
264
|
+
### Enable Public HTTPS
|
|
265
|
+
|
|
266
|
+
Persist the domain and certificate configuration, then apply it:
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
ulvia repository configure \
|
|
270
|
+
--tls acme \
|
|
271
|
+
--public-url https://repository.example.com \
|
|
272
|
+
--acme-email ops@example.com
|
|
273
|
+
|
|
274
|
+
ulvia repository start
|
|
275
|
+
ulvia repository status
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
This starts the Repository, a dedicated Nginx proxy and its ACME companion.
|
|
279
|
+
Only the proxy publishes ports 80/443; the Repository's host endpoint stays on
|
|
280
|
+
loopback. Certificates and renewal state persist with the deployment. Issuance
|
|
281
|
+
requires working public DNS and HTTP access to port 80. Container readiness does
|
|
282
|
+
not by itself confirm that the public certificate has been issued.
|
|
283
|
+
|
|
284
|
+
After issuance, verify public access and save the HTTPS connection:
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
curl --fail https://repository.example.com/readyz
|
|
288
|
+
curl --fail https://repository.example.com/v1/repository
|
|
289
|
+
ulvia repository login https://repository.example.com --identity owner
|
|
290
|
+
ulvia namespace status acme
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
The Repository identity and namespace ownership must match the local endpoint.
|
|
294
|
+
Public catalogue reads need no credentials; writes require the namespace owner's
|
|
295
|
+
signature. Login saves the endpoint and verifies the Repository identity. It
|
|
296
|
+
does not create a bearer-token session; private keys stay on the signing host.
|
|
297
|
+
|
|
298
|
+
### Publish Resources
|
|
299
|
+
|
|
300
|
+
On a signing machine with the owner identity, release an authored resource and
|
|
301
|
+
push its exact coordinate:
|
|
302
|
+
|
|
303
|
+
```bash
|
|
253
304
|
ulvia release /path/to/authored-resource
|
|
254
305
|
ulvia push contract acme/example.contract@1.0.0
|
|
255
|
-
ulvia pull contract acme/example.contract@1.0.0
|
|
256
306
|
```
|
|
257
307
|
|
|
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:
|
|
308
|
+
The development CLI adds recursive release, inferred push kinds and `push all`:
|
|
267
309
|
|
|
268
310
|
```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
|
|
311
|
+
ulvia release /path/to/resources --recursive
|
|
312
|
+
ulvia push acme/example.contract@1.0.0
|
|
313
|
+
ulvia push all
|
|
278
314
|
```
|
|
279
315
|
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
316
|
+
Recursive release prepares sources locally. `push all` publishes every
|
|
317
|
+
non-yanked release in the local cache to the saved Repository, respecting local
|
|
318
|
+
dependency order. It verifies all artifacts and namespace owner keys before
|
|
319
|
+
uploading. A failed batch can leave completed publications; rerun it to resume
|
|
320
|
+
idempotently. A type is required only when a coordinate matches several local
|
|
321
|
+
resource kinds. The published `0.1.0-beta` CLI does not yet include these additions.
|
|
322
|
+
|
|
323
|
+
The resource's `publisherId` must match the owned namespace. Dependencies must
|
|
324
|
+
be released and pushed first. Collections and provider manifests use
|
|
325
|
+
`push collection` and `push provider`. Publishing does not install a collection
|
|
326
|
+
on a CMS site.
|
|
327
|
+
|
|
328
|
+
Other authors use `repository login` and `namespace claim` with their own local
|
|
329
|
+
identities and namespace names. No environment exports are needed.
|
|
284
330
|
|
|
285
|
-
|
|
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:
|
|
331
|
+
### Daily Operations And Upgrades
|
|
288
332
|
|
|
289
333
|
```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
|
|
334
|
+
ulvia repository status
|
|
335
|
+
ulvia repository stop
|
|
295
336
|
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
337
|
```
|
|
300
338
|
|
|
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
|
-
|
|
339
|
+
Stopping preserves data, identities and certificates. Starts reuse the installed
|
|
340
|
+
image digest. To upgrade, use `ulvia repository upgrade --version VERSION`,
|
|
341
|
+
replacing `VERSION` with an exact published version. The CLI pulls the tag,
|
|
342
|
+
checks the image labels and pins its immutable digest. A failed activation
|
|
343
|
+
attempts to restart the previous image; it does not reverse data migrations.
|
|
344
|
+
Back up the stopped deployment and signing identities before upgrading.
|
|
345
|
+
|
|
346
|
+
`identity import NAME --key-file PATH` copies an existing private key into a
|
|
347
|
+
managed local identity. Rotation uses `namespace rotate NAMESPACE
|
|
348
|
+
--replacement-identity NAME` and requires both owner and replacement keys.
|
|
349
|
+
Revocation uses `namespace revoke NAMESPACE --yes` and is permanent.
|
|
350
|
+
`repository logout` removes the connection while preserving local keys.
|
|
351
|
+
|
|
352
|
+
### Configuration And Storage
|
|
353
|
+
|
|
354
|
+
Client configuration lives in `$XDG_CONFIG_HOME/ulvia` or `~/.config/ulvia`,
|
|
355
|
+
overridable with `ULVIA_CONFIG_DIR`. `config.json` contains public keys, private
|
|
356
|
+
key-file references and the active connection; PEM files live in `keys/`.
|
|
357
|
+
Files use mode 0600 and directories 0700. Setting only `ULVIA_DATA_DIR` isolates
|
|
358
|
+
client settings below `<data>/config`.
|
|
359
|
+
|
|
360
|
+
Deployment data defaults to `$XDG_DATA_HOME/ulvia/repository-service` or
|
|
361
|
+
`~/.local/share/ulvia/repository-service`, overridable through `ULVIA_DATA_DIR`:
|
|
362
|
+
|
|
363
|
+
| Path | Content |
|
|
364
|
+
| --- | --- |
|
|
365
|
+
| `config.json` | Desired network configuration |
|
|
366
|
+
| `service.json` | Installed image digest and last applied configuration |
|
|
367
|
+
| `data/` | Repository identity, namespace history, releases and upload/replay state |
|
|
368
|
+
| `proxy/` | Certificates, virtual hosts, HTTP challenges and ACME renewal state |
|
|
369
|
+
|
|
370
|
+
A complete backup includes the stopped deployment and matching signing
|
|
371
|
+
identities. `reset --yes` affects the CMS installation and local release cache;
|
|
372
|
+
it preserves the independent Repository deployment and client identities.
|
|
373
|
+
|
|
374
|
+
### Other Network Modes
|
|
375
|
+
|
|
376
|
+
The standard procedure above uses managed ACME. The CLI also supports:
|
|
377
|
+
|
|
378
|
+
| Mode | Command | Exposure |
|
|
379
|
+
| --- | --- | --- |
|
|
380
|
+
| Local | `repository configure --tls local --port 5010` | Loopback HTTP only |
|
|
381
|
+
| External proxy | `repository configure --tls external --public-url https://repository.example.com` | Loopback backend; the operator supplies and connects the HTTPS proxy |
|
|
382
|
+
|
|
383
|
+
Run `repository start` after configuration changes. An external proxy must
|
|
384
|
+
forward to the backend, allow 100 MiB assets plus protocol overhead and preserve
|
|
385
|
+
request bodies. The CLI's external mode does not configure the operator's proxy
|
|
386
|
+
or join its Docker network. The public origin controls resource links; forwarded
|
|
387
|
+
headers do not override it.
|
|
388
|
+
|
|
389
|
+
Local regression tests validate deployment configuration and publication using
|
|
390
|
+
temporary repositories. They do not issue public certificates or contact the
|
|
391
|
+
official Repository. Contributor-only image builds and Docker regression tests
|
|
392
|
+
are separate from the installation procedure:
|
|
326
393
|
|
|
327
394
|
```bash
|
|
328
395
|
bun run infra/images/build.ts build --version 0.1.0-repository.0 repository
|
|
329
396
|
ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test infra/images/official-repository/tests
|
|
330
397
|
```
|
|
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
|
@@ -155,6 +155,23 @@ 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 or conformance definitions. It orders
|
|
160
|
+
contracts by inheritance and capability requirements, validates conformance
|
|
161
|
+
against the complete planned contract set, then prepares providers and
|
|
162
|
+
collections. Existing local dependencies are reused. Source admission happens
|
|
163
|
+
before any resource is stored; each resource is committed separately, so a
|
|
164
|
+
storage or publication conflict can leave a partial batch. Retrying identical
|
|
165
|
+
releases is idempotent. Duplicate coordinates and symbolic links are rejected.
|
|
166
|
+
Discovery is bounded to 256 resources, 4096 directories and 32 directory levels;
|
|
167
|
+
prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
|
|
168
|
+
explicit separate command.
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
ulvia release packages/official-repository/contracts --recursive
|
|
172
|
+
ulvia release packages/official-repository --recursive
|
|
173
|
+
```
|
|
174
|
+
|
|
158
175
|
Contract fixture assets declared in `definition.json` are read from
|
|
159
176
|
`fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
|
|
160
177
|
different content fails. The local Repository serves stored resources
|
|
@@ -184,10 +201,28 @@ dependencies, before storing the contract. Conformance publication and live
|
|
|
184
201
|
execution are separate Gateway/repository APIs; the CLI does not yet orchestrate
|
|
185
202
|
a disposable provider environment.
|
|
186
203
|
|
|
187
|
-
`push
|
|
188
|
-
|
|
189
|
-
`collection
|
|
190
|
-
|
|
204
|
+
`push <publisher/id@version>` infers the kind from local cached releases. If the
|
|
205
|
+
same coordinate exists in several catalogues, specify `push contract`,
|
|
206
|
+
`push collection` or `push provider` to resolve the ambiguity. `pull` still takes
|
|
207
|
+
an explicit kind and downloads and re-admits one exact coordinate locally.
|
|
208
|
+
|
|
209
|
+
`push all` publishes every non-yanked release in the local cache, independently
|
|
210
|
+
of the working directory. It orders contract inheritance and requirements,
|
|
211
|
+
then providers and known local collection dependencies. All artifacts and every
|
|
212
|
+
namespace's local owner key are checked before the first upload. No namespace
|
|
213
|
+
is implicitly claimed and releases without an owner key are not silently skipped.
|
|
214
|
+
A remote refusal or transfer failure stops the batch; already completed
|
|
215
|
+
publications remain visible. Repeating the command reconciles identical releases
|
|
216
|
+
and resumes the remainder. The receiving Repository still validates dependency
|
|
217
|
+
availability and every immutable artifact. For single pushes, transfer required
|
|
218
|
+
dependencies first.
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
ulvia push ulvia.official/ulvia.cms.emailer@1.0.0
|
|
222
|
+
ulvia push all
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
`repository login` saves the default endpoint; `--repository` and
|
|
191
226
|
`ULVIA_REPOSITORY_URL` remain explicit overrides. Owner signatures bind Repository
|
|
192
227
|
identity, namespace revision, action, content digest, timestamp and nonce.
|
|
193
228
|
The server rejects stale or replayed
|