@cyaxis/ulvia 1.0.12 → 1.0.19
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 +146 -259
- package/README.md +137 -167
- package/SHARED-HOSTING.md +312 -0
- package/dist/definitions/services-tls.yml +0 -16
- package/dist/definitions/services.yml +30 -21
- package/dist/index.js +43498 -42582
- package/dist/stack-release.json +1 -0
- package/package.json +2 -1
- package/dist/definitions/edge-tls.yml +0 -5
- package/dist/definitions/edge.yml +0 -36
- package/dist/definitions/nginx/capability_cache.conf +0 -13
- package/dist/definitions/nginx/client_max_body.conf +0 -2
- package/dist/definitions/nginx/default_location +0 -8
- package/dist/definitions/nginx/query_safe_access_log.conf +0 -4
package/README.md
CHANGED
|
@@ -1,175 +1,131 @@
|
|
|
1
1
|
# Ulvia CLI
|
|
2
2
|
|
|
3
|
-
Ulvia installation and release CLI.
|
|
3
|
+
Ulvia installation and release CLI. The shared-hosting implementation requires
|
|
4
|
+
compatible Provider and Edge images labelled `io.ulvia.hosting-api=1`.
|
|
4
5
|
|
|
5
|
-
For the operator journey
|
|
6
|
-
|
|
6
|
+
For the operator journey, follow the
|
|
7
|
+
[installation guide](INSTALLATION.md). Architecture,
|
|
8
|
+
verification and deployment limits are documented in
|
|
9
|
+
[shared hosting](SHARED-HOSTING.md).
|
|
7
10
|
|
|
8
|
-
The workspace package
|
|
9
|
-
|
|
10
|
-
|
|
11
|
+
The workspace package is private source. Official distribution bundles workspace
|
|
12
|
+
dependencies into `@cyaxis/ulvia`; it does not publish this workspace package.
|
|
13
|
+
Workspace TypeScript declarations are emitted to `dist/types/`, separately from
|
|
14
|
+
the generated system snapshot in `dist/bootstrap/`. Regenerating that snapshot
|
|
15
|
+
must not remove compiler outputs or make incremental and clean builds differ.
|
|
16
|
+
Build one exact CLI release and its compatible default stack version with:
|
|
11
17
|
|
|
12
18
|
```bash
|
|
13
|
-
bun
|
|
14
|
-
ulvia --help
|
|
19
|
+
bun run build --version VERSION
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
Use the same exact distribution version for the CLI, Provider and Edge. This creates a checked
|
|
23
|
+
npm archive and one SHA-256 receipt below `artifacts/distributions/VERSION/cli/`. Publishing is a separate
|
|
24
|
+
explicit `bun run publish --version VERSION` operation. The versioned build seals
|
|
25
|
+
the CLI, images and official releases under `artifacts/distributions/VERSION/`;
|
|
26
|
+
publication selects that snapshot and verifies its bytes before any upload.
|
|
27
|
+
|
|
28
|
+
## Shared infrastructure
|
|
29
|
+
|
|
30
|
+
From workspace source, supply an exact initial image version:
|
|
18
31
|
|
|
19
32
|
```bash
|
|
20
|
-
bun run
|
|
21
|
-
bun run
|
|
33
|
+
bun run ulvia -- configure --domain control.localhost --edges 1
|
|
34
|
+
bun run ulvia -- apply --version STACK_VERSION
|
|
35
|
+
bun run ulvia -- status
|
|
36
|
+
bun run ulvia -- logs --filter component=provider
|
|
37
|
+
bun run ulvia -- logs --filter service=edge-1 --follow
|
|
38
|
+
bun run ulvia -- stop
|
|
39
|
+
bun run ulvia -- start
|
|
22
40
|
```
|
|
23
41
|
|
|
24
|
-
The
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
42
|
+
The CLI starts one Compose project with MongoDB, Provider, Caddy and a configured
|
|
43
|
+
pool of shared Edge processes. The Provider automatically creates empty Control.
|
|
44
|
+
The default public URL is `http://control.localhost:5100/.cms/setup`. Initial
|
|
45
|
+
administrator credentials are in the private file announced at startup, never
|
|
46
|
+
printed. Control uses native setup and can explicitly remain without collections
|
|
47
|
+
or Pages. Create other logical sites through its admitted `ulvia/cms.hosting`
|
|
48
|
+
HTTP/MCP capabilities; no CLI instance lifecycle commands remain.
|
|
49
|
+
|
|
50
|
+
`configure --edges 2` followed by `apply` scales the pool. Site creation
|
|
51
|
+
does not create containers. Reducing the configured count removes obsolete shared
|
|
52
|
+
Edge containers. Stopping infrastructure makes all its logical sites unavailable
|
|
53
|
+
while retaining their persistent data.
|
|
54
|
+
|
|
55
|
+
Persistent data lives below `$XDG_DATA_HOME/ulvia` or
|
|
56
|
+
`~/.local/share/ulvia`. `ULVIA_DATA_DIR` provides explicit installation isolation.
|
|
57
|
+
`services/installation.json` holds mandatory hosting and network configuration;
|
|
58
|
+
`services/stack.json` separates the last applied deployment from a resumable operation;
|
|
59
|
+
`services/deployments/<id>/` retains its exact private Compose/configuration snapshot;
|
|
60
|
+
`services/runtime.json` holds private infrastructure keys. MongoDB and CMS file
|
|
61
|
+
storage belong to the shared services. There is no per-site Edge runtime state.
|
|
62
|
+
The local release cache remains in `<data>/repository`.
|
|
63
|
+
|
|
64
|
+
The CLI reuses validated cached exact-version images and pulls missing ones.
|
|
65
|
+
It checks component, stack API, hosting API, version and repository digest. A
|
|
66
|
+
mismatched cached image refuses startup. Source builds require `--version` on
|
|
67
|
+
first apply; bundled releases carry an exact default. `start` only starts existing
|
|
68
|
+
containers using the applied snapshot. Explicit stack upgrades use:
|
|
30
69
|
|
|
31
70
|
```bash
|
|
32
|
-
|
|
33
|
-
bun run ulvia -- services start --version 0.0.1-beta
|
|
34
|
-
bun run ulvia -- services status
|
|
35
|
-
bun run ulvia -- instance create preview --label "Preview site"
|
|
36
|
-
bun run ulvia -- instance list
|
|
37
|
-
bun run ulvia -- instance credentials preview
|
|
38
|
-
bun run ulvia -- instance stop preview
|
|
39
|
-
bun run ulvia -- instance delete preview --yes
|
|
40
|
-
bun run ulvia -- services stop
|
|
41
|
-
bun run ulvia -- upgrade edge --version 0.0.1-beta
|
|
42
|
-
bun run ulvia -- upgrade provider --version 0.0.1-beta
|
|
43
|
-
bun run ulvia -- reset --yes
|
|
44
|
-
bun run ulvia -- release ./my-collection
|
|
45
|
-
bun run ulvia -- release /path/to/contract-directory
|
|
46
|
-
bun run ulvia -- release /path/to/provider-directory
|
|
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
|
-
bun run ulvia -- prune
|
|
71
|
+
ulvia upgrade --version STACK_VERSION
|
|
52
72
|
```
|
|
53
73
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
The lifecycle commands manage the same Docker Compose projects for loopback and
|
|
64
|
-
public installations from any directory. Persistent
|
|
65
|
-
data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
|
|
66
|
-
`ULVIA_DATA_DIR` remains an explicit isolation override for tests and CI. The
|
|
67
|
-
CLI stores authored releases in `<data>/repository`. Shared Provider,
|
|
68
|
-
MongoDB, proxy, files, secrets and logs live below `<data>/services`; each
|
|
69
|
-
stateless Edge has independent state and logs below `<data>/instances/<name>`.
|
|
70
|
-
The CLI never starts application servers, supervises their PIDs, or builds
|
|
71
|
-
software images. It pulls only the canonical public images under
|
|
72
|
-
`docker.io/cyaxis`, validates their Ulvia component and stack-API labels, and
|
|
73
|
-
stores the immutable repository digest selected for each component.
|
|
74
|
-
|
|
75
|
-
The first lifecycle command creates a safe installation configuration bound to
|
|
76
|
-
`127.0.0.1:5100`. Configure public exposure before creating an instance:
|
|
74
|
+
Provider replacement checks retained execution support first. Failed activation
|
|
75
|
+
retains a resumable target while the applied release stays unchanged. `status`
|
|
76
|
+
shows observed container/image state. Resume with `upgrade`; no data rollback occurs.
|
|
77
|
+
Contract and collection upgrades remain explicit admitted operations.
|
|
78
|
+
|
|
79
|
+
## Domains and initial access
|
|
80
|
+
|
|
81
|
+
Configure public listeners before first launch:
|
|
77
82
|
|
|
78
83
|
```bash
|
|
79
|
-
ulvia configure
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
--tls acme \
|
|
83
|
-
--https-port 443 \
|
|
84
|
-
--acme-email ops@example.com
|
|
85
|
-
ulvia start
|
|
86
|
-
ulvia instance create website --domain example.com
|
|
84
|
+
ulvia configure --bind 0.0.0.0 --http-port 80 --tls acme --https-port 443 --acme-email ops@example.com
|
|
85
|
+
ulvia configure --domain control.example.com --public-addresses 203.0.113.10
|
|
86
|
+
ulvia apply
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
`
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
89
|
+
Use the installation's real domain and addresses. Network settings and Control's
|
|
90
|
+
origin lock after the first launch. Hosting settings can change the shared Edge
|
|
91
|
+
count, operator-managed suffixes and public-address allowlist; apply them with
|
|
92
|
+
`apply`. Customer domain claims use Control's contracts and ownership validation.
|
|
93
|
+
Caddy uses the admitted TLS permission binding and persistent certificate storage.
|
|
94
|
+
DNS/TLS pending state is distinct from a provisioned instance and healthy backend.
|
|
95
|
+
The Provider operator listener remains on loopback.
|
|
96
|
+
|
|
97
|
+
Native setup offers a custom Repository, the official Repository, or creating a
|
|
98
|
+
Registry on that instance. Registry activation is explicit, through its exact
|
|
99
|
+
installed selection; it has no separate image, container, profile or service.
|
|
100
|
+
All sites begin without collections. Completing an empty site leaves `/` at 404.
|
|
101
|
+
|
|
102
|
+
Infrastructure mutations share a native process lock at the installation root.
|
|
103
|
+
Missing mandatory configuration or keys over existing state fail without repair;
|
|
104
|
+
startup never replaces an existing Control administrator. `reset --yes` deletes
|
|
105
|
+
Ulvia-owned installation data and the local release cache. Keep a complete matching
|
|
106
|
+
backup of database, files and credentials before destructive recovery.
|
|
107
|
+
|
|
108
|
+
## Repository account connections and releases
|
|
109
|
+
|
|
110
|
+
`repository login URL` prompts for a CMS PAT with terminal input hidden when
|
|
111
|
+
`ULVIA_REPOSITORY_TOKEN` is absent. Automation can use `--token-stdin` or
|
|
112
|
+
`ULVIA_REPOSITORY_TOKEN`. The saved PAT is pinned to the origin and Repository
|
|
113
|
+
identity. Ordinary Repository accounts can claim namespaces and publish. Logout removes the local
|
|
114
|
+
connection without revoking the remote token. Client configuration uses
|
|
115
|
+
`$XDG_CONFIG_HOME/ulvia`, `~/.config/ulvia` or explicit `ULVIA_CONFIG_DIR`;
|
|
116
|
+
`ULVIA_DATA_DIR` alone isolates it under `<data>/config`. Files are private.
|
|
117
117
|
|
|
118
118
|
```bash
|
|
119
|
-
ulvia
|
|
120
|
-
ulvia
|
|
121
|
-
ulvia
|
|
122
|
-
ulvia
|
|
119
|
+
ulvia repository login https://repository.example.com
|
|
120
|
+
ulvia namespace claim example
|
|
121
|
+
ulvia release /path/to/resources --recursive
|
|
122
|
+
ulvia push all
|
|
123
|
+
ulvia repository logout
|
|
123
124
|
```
|
|
124
125
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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.
|
|
136
|
-
|
|
137
|
-
`repository login URL` verifies the Repository identity and saves a shared CMS
|
|
138
|
-
PAT supplied through `ULVIA_REPOSITORY_TOKEN` or `--token-stdin`. Ordinary
|
|
139
|
-
Repository accounts can claim namespaces and publish without CMS administrator
|
|
140
|
-
privileges. Login pins both the origin and Repository identity; writes refuse
|
|
141
|
-
redirects and identity changes. Logout deletes the connection and saved PAT
|
|
142
|
-
without revoking the remote token.
|
|
143
|
-
|
|
144
|
-
Client configuration lives in `$XDG_CONFIG_HOME/ulvia/config.json` or
|
|
145
|
-
`~/.config/ulvia/config.json`. Files use mode 0600, directories 0700.
|
|
146
|
-
`ULVIA_CONFIG_DIR` overrides that location; `ULVIA_DATA_DIR` alone isolates
|
|
147
|
-
client configuration under `<data>/config`. Namespaces, accounts, uploads and
|
|
148
|
-
releases belong to their CMS instance's Provider storage. Startup never claims
|
|
149
|
-
or reassigns a namespace. See the
|
|
150
|
-
[installation guide](../../../docs/installation/README.md#9-repository-cms-instance)
|
|
151
|
-
and [Repository architecture](../../../docs/architecture/community-repository.md).
|
|
152
|
-
|
|
153
|
-
| Command | Provider tenant | Edge container |
|
|
154
|
-
| --- | --- | --- |
|
|
155
|
-
| `services start` | Does not create one | Does not start one |
|
|
156
|
-
| `instance create <name>` | Provisions one durable tenant | Creates and starts its Edge |
|
|
157
|
-
| `instance start <name>` | Reuses the existing tenant | Starts only that Edge |
|
|
158
|
-
| `start` | Never provisions | Starts every existing Edge after shared services |
|
|
159
|
-
|
|
160
|
-
`instance credentials <name>` prints only that administrator's email and
|
|
161
|
-
password. Provider operator and instance bearer tokens remain in
|
|
162
|
-
private runtime files. Shared services and every instance have independent
|
|
163
|
-
`stop`, `status`, and `logs` boundaries. Software upgrades are explicit and
|
|
164
|
-
component-scoped through `upgrade <component> --version <exact-version>`.
|
|
165
|
-
Normal starts always reuse the installed digest and never follow a newer tag.
|
|
166
|
-
First startup validates cached exact-version images and downloads only missing
|
|
167
|
-
images. Explicit upgrades still pull their requested tag.
|
|
168
|
-
`reset --yes`
|
|
169
|
-
removes shared Compose projects, instances, shared state and local repository
|
|
170
|
-
releases, including accounts hosted by this local Provider. Independently deployed
|
|
171
|
-
Repositories and the CLI's saved Repository connection are preserved. It does not
|
|
172
|
-
inspect or modify the current working directory.
|
|
126
|
+
Client connections and authored release caches are independent of site Repository
|
|
127
|
+
settings. Publication never installs resources into a site automatically.
|
|
128
|
+
|
|
173
129
|
`release <resource-directory>` accepts a trusted local `ulvia.release.ts` entry
|
|
174
130
|
or reads `definition.json` and routes by `kind`:
|
|
175
131
|
`collection`, `contract`, or `provider-manifest`. It validates and stores one
|
|
@@ -187,15 +143,16 @@ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
|
|
|
187
143
|
explicit separate command.
|
|
188
144
|
|
|
189
145
|
```bash
|
|
190
|
-
|
|
191
|
-
bun run
|
|
192
|
-
|
|
146
|
+
# Official distribution, without changing the personal release cache:
|
|
147
|
+
bun run build --version VERSION
|
|
148
|
+
bun run publish --version VERSION
|
|
149
|
+
# Generic manual preparation still writes to the personal release cache:
|
|
193
150
|
ulvia release infra/releases
|
|
194
151
|
```
|
|
195
152
|
|
|
196
|
-
The official build
|
|
197
|
-
|
|
198
|
-
[SDK workflow](
|
|
153
|
+
The official build and the trusted local `ulvia.release.ts` entry share the same
|
|
154
|
+
SDK inventory and compiler for feature contracts, manifest claims and bootstrap. See the
|
|
155
|
+
[SDK workflow](https://github.com/matthias-bernouy/CMS/blob/c4d018ad50e01e8250b43fbb04c26337027d77da/docs/development/sdk-releases.md) for explicit versions,
|
|
199
156
|
source-module rules and generated runtime attachment.
|
|
200
157
|
|
|
201
158
|
Contract fixture assets declared in `definition.json` are read from
|
|
@@ -304,7 +261,7 @@ reopens ready instances from their persisted execution. Generate the API-only
|
|
|
304
261
|
snapshot from the SDK feature inventory with:
|
|
305
262
|
|
|
306
263
|
```bash
|
|
307
|
-
bun run
|
|
264
|
+
bun run build
|
|
308
265
|
```
|
|
309
266
|
|
|
310
267
|
That command neither publishes to a running repository nor upgrades an existing
|
|
@@ -315,17 +272,9 @@ exact parent contracts before specializations, then Provider manifests and colle
|
|
|
315
272
|
Publication, system installation transitions, collection upgrades and container
|
|
316
273
|
image replacement remain separate actions.
|
|
317
274
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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.
|
|
325
|
-
Each named instance uses `<name>.localhost` unless an explicit domain is supplied;
|
|
326
|
-
`default` is an ordinary name. Repository hosting uses a CMS instance with the
|
|
327
|
-
explicit Registry installation. Client PAT connections and local release caches
|
|
328
|
-
are separate from the shared services and instance lifecycle.
|
|
275
|
+
Official releases evolve independently. Each feature owns its contract version;
|
|
276
|
+
the Provider manifest owns its version, and local state formats remain `v1`. This is source metadata, not evidence that a matching image
|
|
277
|
+
has been published. Collections are supplied and versioned by their authors.
|
|
329
278
|
|
|
330
279
|
## Collection examples
|
|
331
280
|
|
|
@@ -334,4 +283,25 @@ exports collection example frames, generated PNGs, an interactive local explorer
|
|
|
334
283
|
provenance manifest. Screenshots require the Playwright Chromium browser
|
|
335
284
|
(`bunx playwright@1.64.1 install chromium`). Dependencies and required contracts are
|
|
336
285
|
resolved explicitly from local sources/cache; preview never publishes. See
|
|
337
|
-
[collection examples](
|
|
286
|
+
[collection examples](https://github.com/matthias-bernouy/CMS/blob/c4d018ad50e01e8250b43fbb04c26337027d77da/docs/blocs/examples.md) for source and release formats.
|
|
287
|
+
|
|
288
|
+
### Editable collection publication
|
|
289
|
+
|
|
290
|
+
Collection `release` captures a bounded immutable source snapshot before building
|
|
291
|
+
it in the local Repository cache. It retains sources alongside the admitted
|
|
292
|
+
release before making it visible locally. This uses the same source build engine
|
|
293
|
+
as the remote Repository and works offline with the local contract catalogue;
|
|
294
|
+
it starts no additional Repository server.
|
|
295
|
+
|
|
296
|
+
Collection `push` uploads the retained source snapshot and its exact binary
|
|
297
|
+
assets, then follows the remote Repository's durable build operation. Editing the
|
|
298
|
+
working directory after `release` does not alter the pushed version. The server
|
|
299
|
+
must reproduce the reviewed release digest before publication; a compiler or
|
|
300
|
+
contract-catalogue difference refuses publication rather than silently changing
|
|
301
|
+
the release. Collection release modules must also supply `sourceJson`.
|
|
302
|
+
|
|
303
|
+
Pulled or older compiled-only cache entries remain readable, but can only be
|
|
304
|
+
replayed to a Repository already containing that exact release. Publishing one
|
|
305
|
+
to a new Repository requires its original editable sources and an explicit
|
|
306
|
+
release. No source reconstruction runs. Contract and Provider manifest flows
|
|
307
|
+
are unchanged.
|