@cyaxis/ulvia 0.1.0-beta.1 → 1.0.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 CHANGED
@@ -66,12 +66,34 @@ The site is available at `http://my-site.localhost:5100`. The credentials
66
66
  command prints the initial administrator email and password. It never prints
67
67
  the Provider, Repository, encryption, or instance service secrets.
68
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
+
69
91
  Ulvia deliberately separates shared services from sites:
70
92
 
71
93
  | Command | Responsibility |
72
94
  | --- | --- |
73
95
  | `ulvia services start` | Starts the proxy, MongoDB, Official Repository, and Provider. |
74
- | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Kernel. |
96
+ | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Edge. |
75
97
  | `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
76
98
  | `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
77
99
 
@@ -93,12 +115,12 @@ ulvia start
93
115
  ulvia instance stop my-site
94
116
  ulvia instance start my-site
95
117
  ulvia services logs all --level warn
96
- ulvia instance logs my-site kernel
118
+ ulvia instance logs my-site edge
97
119
  ulvia services stop
98
120
  ```
99
121
 
100
122
  Stopping containers preserves persistent data. `services stop` also makes every
101
- site unavailable because Kernels depend on the shared Provider and proxy.
123
+ site unavailable because Edges depend on the shared Provider and proxy.
102
124
 
103
125
  ## 5. Upgrade Ulvia
104
126
 
@@ -114,7 +136,7 @@ ulvia --version
114
136
  Upgrade deployable components independently with exact versions:
115
137
 
116
138
  ```bash
117
- ulvia upgrade kernel --version 0.0.1-beta
139
+ ulvia upgrade edge --version 0.0.1-beta
118
140
  ulvia upgrade provider --version 0.0.1-beta
119
141
  ulvia upgrade repository --version 0.0.1-beta
120
142
  ```
@@ -124,7 +146,7 @@ that digest on subsequent starts. Registry channels such as `next` or `latest`
124
146
  may identify releases for humans, but an installation never persists or
125
147
  silently follows those mutable tags.
126
148
 
127
- `upgrade kernel` visits every local Kernel instance in sequence. Upgrades of
149
+ `upgrade edge` visits every local Edge instance in sequence. Upgrades of
128
150
  Provider and Repository affect shared services. A failed activation attempts
129
151
  to restart the previous image, but this does not restore changed database or
130
152
  file contents and is not an atomic rollback across all instances.
@@ -135,7 +157,8 @@ schema migrations and interrupted-upgrade/restore drills remain
135
157
  ## 6. Public Domain And HTTPS
136
158
 
137
159
  Configure public networking before creating the first instance because the
138
- canonical Kernel URLs become part of Provider provisioning:
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:
139
162
 
140
163
  ```bash
141
164
  ulvia configure network \
@@ -165,7 +188,7 @@ directory. Preserve the complete directory, including MongoDB, files,
165
188
  credentials, encryption material, Repository state, and instance definitions.
166
189
  Do not restore only selected secret or database files from different snapshots.
167
190
 
168
- The CLI has no general backup/restore command. Stop each Kernel with
191
+ The CLI has no general backup/restore command. Stop each Edge with
169
192
  `ulvia instance stop <name>`, then stop shared services before copying their
170
193
  data. Restore and verify a complete backup in an isolated installation before
171
194
  treating it as a recovery guarantee; do not rely on image fallback to recover
@@ -196,7 +219,7 @@ Removing the CLI alone does not delete persistent CMS data or Docker resources.
196
219
  - **An image cannot be pulled:** verify network access and that the requested
197
220
  exact Cyaxis image version has been published.
198
221
  - **An instance returns 503:** check `ulvia services status`, then the Provider
199
- and instance Kernel logs.
222
+ and instance Edge logs.
200
223
  - **Stored encrypted data cannot be opened:** do not generate replacement keys
201
224
  over an existing data directory; restore the matching complete backup.
202
225
 
@@ -393,5 +416,5 @@ are separate from the installation procedure:
393
416
 
394
417
  ```bash
395
418
  bun run infra/images/build.ts build --version 0.1.0-repository.0 repository
396
- ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test infra/images/official-repository/tests
419
+ ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test ./tests/images/official-repository
397
420
  ```
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 kernel --version 0.0.1-beta
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 Kernel has independent state and logs below `<data>/instances/<name>`.
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 Kernel URL is part of Provider
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 Kernel. `instance start` restarts only an already-provisioned
100
- instance's Kernel. All Kernels use the shared proxy port: an instance named
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 Kernel.
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 | Kernel container |
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 Kernel |
142
- | `instance start <name>` | Reuses the existing tenant | Starts only that Kernel |
143
- | `start` | Never provisions | Starts every existing Kernel after shared services |
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
@@ -156,10 +156,9 @@ releases. It preserves independent Repository deployments and signing identities
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
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
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
163
162
  before any resource is stored; each resource is committed separately, so a
164
163
  storage or publication conflict can leave a partial batch. Retrying identical
165
164
  releases is idempotent. Duplicate coordinates and symbolic links are rejected.
@@ -192,15 +191,6 @@ sorts capabilities and mocks by their declared IDs, so paths never affect the
192
191
  immutable digest. `definition.json` cannot contain an inline `capabilities`
193
192
  array: the recursive source tree is the only authored contract format.
194
193
 
195
- An optional conformance companion uses `conformance/definition.json`, recursive
196
- `conformance/scenarios/**/*.json` scenario objects and recursive
197
- `conformance/exemptions/**/*.json` coverage-exemption objects. Optional suite
198
- fixture bytes live below `conformance/fixtures/<asset-id>`. The release command
199
- assembles and admits a present suite, including exact locally released
200
- dependencies, before storing the contract. Conformance publication and live
201
- execution are separate Gateway/repository APIs; the CLI does not yet orchestrate
202
- a disposable provider environment.
203
-
204
194
  `push <publisher/id@version>` infers the kind from local cached releases. If the
205
195
  same coordinate exists in several catalogues, specify `push contract`,
206
196
  `push collection` or `push provider` to resolve the ambiguity. `pull` still takes
@@ -304,5 +294,14 @@ Publication, provider profile transitions, collection upgrades and container
304
294
  image replacement remain separate actions.
305
295
 
306
296
  `instance create` provisions the named instance through the Provider operator
307
- API, then starts its Kernel. Connection review validates the runtime report and
308
- exact manifest claims; it does not yet execute a live conformance suite.
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,5 +1,5 @@
1
1
  services:
2
- kernel:
2
+ edge:
3
3
  environment:
4
4
  ACME_HOST: ${ULVIA_INSTANCE_HOSTNAME}
5
5
  LETSENCRYPT_HOST: ${ULVIA_INSTANCE_HOSTNAME}
@@ -1,26 +1,22 @@
1
1
  services:
2
- kernel:
3
- image: ${KERNEL_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
- KERNEL_HOST: 0.0.0.0
11
- KERNEL_PORT: "3000"
12
- KERNEL_PUBLIC_URL: ${ULVIA_INSTANCE_URL}
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
- - instances
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: http://repository:3000
129
- CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "true"
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: