@cyaxis/ulvia 0.0.3 → 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 +220 -5
- package/README.md +95 -29
- package/dist/definitions/repository-tls.yml +38 -0
- package/dist/definitions/repository.yml +32 -0
- package/dist/definitions/services.yml +2 -1
- package/dist/index.js +24391 -23070
- 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
|
|
|
@@ -32,16 +34,19 @@ and accessible to the account that executes `ulvia`.
|
|
|
32
34
|
|
|
33
35
|
## 2. Install The CLI
|
|
34
36
|
|
|
35
|
-
Install the current
|
|
37
|
+
Install the current stable CLI globally from the public npm registry:
|
|
36
38
|
|
|
37
39
|
```bash
|
|
38
|
-
bun add --global @cyaxis/ulvia@
|
|
40
|
+
bun add --global @cyaxis/ulvia@latest
|
|
39
41
|
ulvia --help
|
|
40
42
|
```
|
|
41
43
|
|
|
42
44
|
If `ulvia` is not found, reopen the terminal and check that `~/.bun/bin` is in
|
|
43
45
|
`PATH`, as described by the Bun installation guide.
|
|
44
46
|
|
|
47
|
+
Use an exact version, for example `@cyaxis/ulvia@0.0.3`, when reproducing an
|
|
48
|
+
installation. The `next` tag is reserved for explicitly tested prereleases.
|
|
49
|
+
|
|
45
50
|
## 3. Create A Local Site
|
|
46
51
|
|
|
47
52
|
Start the shared infrastructure, then create one named instance:
|
|
@@ -97,10 +102,13 @@ site unavailable because Kernels depend on the shared Provider and proxy.
|
|
|
97
102
|
|
|
98
103
|
## 5. Upgrade Ulvia
|
|
99
104
|
|
|
100
|
-
Upgrade the host CLI through Bun
|
|
105
|
+
Upgrade the host CLI through Bun. Naming `latest` explicitly also replaces an
|
|
106
|
+
installation that was originally attached to the `next` channel:
|
|
101
107
|
|
|
102
108
|
```bash
|
|
103
|
-
bun
|
|
109
|
+
bun add --global @cyaxis/ulvia@latest
|
|
110
|
+
hash -r
|
|
111
|
+
ulvia --version
|
|
104
112
|
```
|
|
105
113
|
|
|
106
114
|
Upgrade deployable components independently with exact versions:
|
|
@@ -116,6 +124,14 @@ that digest on subsequent starts. Registry channels such as `next` or `latest`
|
|
|
116
124
|
may identify releases for humans, but an installation never persists or
|
|
117
125
|
silently follows those mutable tags.
|
|
118
126
|
|
|
127
|
+
`upgrade kernel` visits every local Kernel instance in sequence. Upgrades of
|
|
128
|
+
Provider and Repository affect shared services. A failed activation attempts
|
|
129
|
+
to restart the previous image, but this does not restore changed database or
|
|
130
|
+
file contents and is not an atomic rollback across all instances.
|
|
131
|
+
Take a complete backup before an upgrade involving persisted data. Internal
|
|
132
|
+
schema migrations and interrupted-upgrade/restore drills remain
|
|
133
|
+
[open platform work](../TODO.md#internal-persistence-migrations).
|
|
134
|
+
|
|
119
135
|
## 6. Public Domain And HTTPS
|
|
120
136
|
|
|
121
137
|
Configure public networking before creating the first instance because the
|
|
@@ -149,6 +165,12 @@ directory. Preserve the complete directory, including MongoDB, files,
|
|
|
149
165
|
credentials, encryption material, Repository state, and instance definitions.
|
|
150
166
|
Do not restore only selected secret or database files from different snapshots.
|
|
151
167
|
|
|
168
|
+
The CLI has no general backup/restore command. Stop each Kernel with
|
|
169
|
+
`ulvia instance stop <name>`, then stop shared services before copying their
|
|
170
|
+
data. Restore and verify a complete backup in an isolated installation before
|
|
171
|
+
treating it as a recovery guarantee; do not rely on image fallback to recover
|
|
172
|
+
data. See [operational recovery](../TODO.md#backup-and-operational-recovery).
|
|
173
|
+
|
|
152
174
|
`reset` permanently removes Ulvia-owned local state:
|
|
153
175
|
|
|
154
176
|
```bash
|
|
@@ -180,3 +202,196 @@ Removing the CLI alone does not delete persistent CMS data or Docker resources.
|
|
|
180
202
|
|
|
181
203
|
For implementation diagnostics and contributor-only environment overrides, see
|
|
182
204
|
the [development and validation guide](../development/README.md).
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
## 9. Standalone Repository
|
|
208
|
+
|
|
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.
|
|
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:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
bun add --global @cyaxis/ulvia@0.1.0-beta
|
|
230
|
+
ulvia --version
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
The CLI bundles `0.1.0-beta` as its initial stack version. No deployment name or
|
|
234
|
+
`global`/`community` qualifier is required.
|
|
235
|
+
|
|
236
|
+
### Start Locally And Claim The Publisher
|
|
237
|
+
|
|
238
|
+
Start the Repository before exposing it publicly:
|
|
239
|
+
|
|
240
|
+
```bash
|
|
241
|
+
ulvia repository start
|
|
242
|
+
ulvia repository status
|
|
243
|
+
curl --fail http://127.0.0.1:5010/readyz
|
|
244
|
+
```
|
|
245
|
+
|
|
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:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
ulvia identity create owner
|
|
251
|
+
ulvia repository login http://127.0.0.1:5010 --identity owner
|
|
252
|
+
ulvia namespace claim acme
|
|
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
|
|
304
|
+
ulvia release /path/to/authored-resource
|
|
305
|
+
ulvia push contract acme/example.contract@1.0.0
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
The development CLI adds recursive release, inferred push kinds and `push all`:
|
|
309
|
+
|
|
310
|
+
```bash
|
|
311
|
+
ulvia release /path/to/resources --recursive
|
|
312
|
+
ulvia push acme/example.contract@1.0.0
|
|
313
|
+
ulvia push all
|
|
314
|
+
```
|
|
315
|
+
|
|
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.
|
|
330
|
+
|
|
331
|
+
### Daily Operations And Upgrades
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
ulvia repository status
|
|
335
|
+
ulvia repository stop
|
|
336
|
+
ulvia repository start
|
|
337
|
+
```
|
|
338
|
+
|
|
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:
|
|
393
|
+
|
|
394
|
+
```bash
|
|
395
|
+
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
|
|
397
|
+
```
|
package/README.md
CHANGED
|
@@ -10,15 +10,15 @@ bundled without workspace dependencies and published publicly as
|
|
|
10
10
|
`@cyaxis/ulvia`:
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
|
-
bun add --global @cyaxis/ulvia@
|
|
13
|
+
bun add --global @cyaxis/ulvia@latest
|
|
14
14
|
ulvia --help
|
|
15
15
|
```
|
|
16
16
|
|
|
17
17
|
From the workspace, build and publish one exact release with:
|
|
18
18
|
|
|
19
19
|
```bash
|
|
20
|
-
bun run cli:build --version 0.0.
|
|
21
|
-
bun run cli:publish --version 0.0.
|
|
20
|
+
bun run cli:build --version 0.0.3 --stack-version 0.0.1-beta
|
|
21
|
+
bun run cli:publish --version 0.0.3
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
The build creates a checked npm archive and SHA-256 receipt below
|
|
@@ -29,8 +29,8 @@ accepts only the exact pair, targets the public npm registry, and uses the
|
|
|
29
29
|
credentials configured outside the repository.
|
|
30
30
|
|
|
31
31
|
```bash
|
|
32
|
-
bun run ulvia -- start
|
|
33
32
|
bun run ulvia -- configure network
|
|
33
|
+
bun run ulvia -- services start --version 0.0.1-beta
|
|
34
34
|
bun run ulvia -- services status
|
|
35
35
|
bun run ulvia -- instance create preview --label "Preview site"
|
|
36
36
|
bun run ulvia -- instance list
|
|
@@ -52,6 +52,12 @@ bun run ulvia -- restore collection ulvia.official/ulvia-official@1.0.0 --reposi
|
|
|
52
52
|
bun run ulvia -- prune
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
+
The stack version above is an example of an exact published image tag. Workspace
|
|
56
|
+
source has no embedded initial stack version: its first `services start`
|
|
57
|
+
requires `--version`. Packaged releases embed that default at build time. Later
|
|
58
|
+
starts reuse installed digests. Building workspace source does not replace
|
|
59
|
+
running images or upgrade installed collections.
|
|
60
|
+
|
|
55
61
|
The lifecycle commands manage the same Docker Compose projects for loopback and
|
|
56
62
|
public installations from any directory. Persistent
|
|
57
63
|
data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
|
|
@@ -104,6 +110,31 @@ previously created local instance; it never creates an implicit instance.
|
|
|
104
110
|
|
|
105
111
|
The lifecycle boundary is deliberate:
|
|
106
112
|
|
|
113
|
+
Independent Repository deployments use `ulvia repository start`, `status`, `stop`
|
|
114
|
+
and `upgrade --version <exact-version>`. Their default volume and image pin live
|
|
115
|
+
below `<data>/repository-service`. No deployment name or `global`/`community`
|
|
116
|
+
qualifier is required. The command does not start
|
|
117
|
+
shared services or a Kernel.
|
|
118
|
+
|
|
119
|
+
`ulvia repository login <url>` verifies and saves the remote identity and creates
|
|
120
|
+
a default local signing identity if none exists. `ulvia identity create`, `import`,
|
|
121
|
+
`use`, `list` and `public-key` manage reusable Ed25519 identities. Namespace
|
|
122
|
+
commands and publication use the saved connection and select an identity matching
|
|
123
|
+
the namespace's current owner. No environment exports are needed. `logout`
|
|
124
|
+
removes only the connection, preserving keys.
|
|
125
|
+
|
|
126
|
+
Client configuration lives in `$XDG_CONFIG_HOME/ulvia/config.json` or
|
|
127
|
+
`~/.config/ulvia/config.json`; private keys live in its `keys/` directory. Files
|
|
128
|
+
use mode 0600, directories 0700. `ULVIA_CONFIG_DIR` overrides that location;
|
|
129
|
+
`ULVIA_DATA_DIR` alone isolates client configuration under `<data>/config`.
|
|
130
|
+
Deployment configuration is separate: `<data>/repository-service/config.json`.
|
|
131
|
+
`repository configure` persists local, external HTTPS proxy or managed ACME
|
|
132
|
+
networking. All namespaces, including `ulvia.official`, use public first claim.
|
|
133
|
+
Claim platform-owned names locally before enabling public access. Ownership
|
|
134
|
+
persists across restarts and cannot be reset through deployment configuration.
|
|
135
|
+
See the [installation guide](../../../docs/installation/README.md#9-standalone-repository)
|
|
136
|
+
and [Repository architecture](../../../docs/architecture/community-repository.md).
|
|
137
|
+
|
|
107
138
|
| Command | Provider tenant | Kernel container |
|
|
108
139
|
| --- | --- | --- |
|
|
109
140
|
| `services start` | Does not create one | Does not start one |
|
|
@@ -112,18 +143,35 @@ The lifecycle boundary is deliberate:
|
|
|
112
143
|
| `start` | Never provisions | Starts every existing Kernel after shared services |
|
|
113
144
|
|
|
114
145
|
`instance credentials <name>` prints only that administrator's email and
|
|
115
|
-
password.
|
|
146
|
+
password. Provider operator and instance bearer tokens remain in
|
|
116
147
|
private runtime files. Shared services and every instance have independent
|
|
117
148
|
`stop`, `status`, and `logs` boundaries. Software upgrades are explicit and
|
|
118
149
|
component-scoped through `upgrade <component> --version <exact-version>`.
|
|
119
150
|
Normal starts always reuse the installed digest and never follow a newer tag.
|
|
120
151
|
`reset --yes`
|
|
121
|
-
removes
|
|
122
|
-
|
|
152
|
+
removes shared Compose projects, instances, shared state and local repository
|
|
153
|
+
releases. It preserves independent Repository deployments and signing identities. It does not inspect or modify the current working directory.
|
|
123
154
|
`release <resource-directory>` reads `definition.json` and routes by `kind`:
|
|
124
155
|
`collection`, `contract`, or `provider-manifest`. It validates and stores one
|
|
125
156
|
immutable release. A provider manifest must reference exact contract releases
|
|
126
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
|
+
|
|
127
175
|
Contract fixture assets declared in `definition.json` are read from
|
|
128
176
|
`fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
|
|
129
177
|
different content fails. The local Repository serves stored resources
|
|
@@ -153,13 +201,31 @@ dependencies, before storing the contract. Conformance publication and live
|
|
|
153
201
|
execution are separate Gateway/repository APIs; the CLI does not yet orchestrate
|
|
154
202
|
a disposable provider environment.
|
|
155
203
|
|
|
156
|
-
`push
|
|
157
|
-
|
|
158
|
-
`collection
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
|
226
|
+
`ULVIA_REPOSITORY_URL` remain explicit overrides. Owner signatures bind Repository
|
|
227
|
+
identity, namespace revision, action, content digest, timestamp and nonce.
|
|
228
|
+
The server rejects stale or replayed
|
|
163
229
|
requests, serializes writes across processes, re-runs admission and evolution
|
|
164
230
|
rules, and stages every declared asset as a separately signed raw stream. A final
|
|
165
231
|
idempotent commit makes the immutable artifact visible only after all byte lengths
|
|
@@ -168,9 +234,10 @@ release. An exact republish is idempotent; different bytes at an existing coordi
|
|
|
168
234
|
reject.
|
|
169
235
|
|
|
170
236
|
The protocol, exact-coordinate client and mutation endpoint live in
|
|
171
|
-
`@bernouy/cms-repository/repository/publication
|
|
172
|
-
|
|
173
|
-
|
|
237
|
+
`@bernouy/cms-repository/repository/publication`. The CLI uses the publication
|
|
238
|
+
client and local filesystem release storage; `official-repository-server`
|
|
239
|
+
composes the HTTP listener inside its container. The filesystem composition
|
|
240
|
+
persists upload sessions and replay claims below the repository root.
|
|
174
241
|
A production repository can replace those ports without depending on this
|
|
175
242
|
executable package.
|
|
176
243
|
|
|
@@ -178,9 +245,7 @@ executable package.
|
|
|
178
245
|
resolution without deleting its exact historical bytes. `restore` exposes it
|
|
179
246
|
again. Contract yanks block new dependent publications while previously
|
|
180
247
|
published provider manifests remain readable. The loopback Repository uses the
|
|
181
|
-
same
|
|
182
|
-
runtime directory. The removed integration repository/Supabase bridge is not
|
|
183
|
-
run.
|
|
248
|
+
same owner-signing protocol. Signing keys stay in local identities.
|
|
184
249
|
|
|
185
250
|
A collection keeps immutable administration copy in recursive locale
|
|
186
251
|
directories such as `translations/en/collection.json` and
|
|
@@ -224,19 +289,20 @@ and do not affect release identity.
|
|
|
224
289
|
|
|
225
290
|
The Official Repository image contains the admitted CMS contracts, provider
|
|
226
291
|
manifest, and administration collection. It installs that snapshot only into
|
|
227
|
-
empty persistent storage.
|
|
228
|
-
|
|
292
|
+
absent or empty persistent storage. A non-empty repository is never overlaid on
|
|
293
|
+
image upgrade. The workspace bootstrap command builds the admitted snapshot
|
|
294
|
+
used by the image:
|
|
229
295
|
|
|
230
296
|
```bash
|
|
231
|
-
bun run
|
|
232
|
-
bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.installations
|
|
233
|
-
bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.content
|
|
234
|
-
bun run ulvia -- release packages/official-repository/contracts/ulvia.cms.files
|
|
235
|
-
bun run ulvia -- release packages/official-repository/contracts/ulvia.provider.cms-instances
|
|
236
|
-
bun run ulvia -- release packages/official-repository/providers/ulvia.official
|
|
237
|
-
bun run ulvia -- start
|
|
297
|
+
bun run generate:official-bootstrap
|
|
238
298
|
```
|
|
239
299
|
|
|
300
|
+
That command neither publishes to a running repository nor upgrades an existing
|
|
301
|
+
instance. For individual manual releases, use `release` in dependency order:
|
|
302
|
+
exact contract dependencies before dependent contracts and provider manifests.
|
|
303
|
+
Publication, provider profile transitions, collection upgrades and container
|
|
304
|
+
image replacement remain separate actions.
|
|
305
|
+
|
|
240
306
|
`instance create` provisions the named instance through the Provider operator
|
|
241
307
|
API, then starts its Kernel. Connection review validates the runtime report and
|
|
242
308
|
exact manifest claims; it does not yet execute a live conformance suite.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
services:
|
|
2
|
+
repository:
|
|
3
|
+
environment:
|
|
4
|
+
VIRTUAL_HOST: ${ULVIA_REPOSITORY_DOMAIN}
|
|
5
|
+
VIRTUAL_PORT: "3000"
|
|
6
|
+
LETSENCRYPT_HOST: ${ULVIA_REPOSITORY_DOMAIN}
|
|
7
|
+
proxy:
|
|
8
|
+
image: nginxproxy/nginx-proxy:1.11.5@sha256:e06db5fb9586234e9c2bdef707c8b8d784caa4fb49fbe7285eb3730a501c3eaa
|
|
9
|
+
restart: unless-stopped
|
|
10
|
+
ports:
|
|
11
|
+
- "0.0.0.0:80:80"
|
|
12
|
+
- "0.0.0.0:443:443"
|
|
13
|
+
volumes:
|
|
14
|
+
- /var/run/docker.sock:/tmp/docker.sock:ro
|
|
15
|
+
- ./nginx/client_max_body.conf:/etc/nginx/conf.d/zzz_client_max_body.conf:ro
|
|
16
|
+
- ./nginx/query_safe_access_log.conf:/etc/nginx/conf.d/zzz_query_safe_access_log.conf:ro
|
|
17
|
+
- ${ULVIA_REPOSITORY_PROXY_DIR}/certificates:/etc/nginx/certs
|
|
18
|
+
- ${ULVIA_REPOSITORY_PROXY_DIR}/virtual-hosts:/etc/nginx/vhost.d
|
|
19
|
+
- ${ULVIA_REPOSITORY_PROXY_DIR}/challenge:/usr/share/nginx/html
|
|
20
|
+
healthcheck:
|
|
21
|
+
test: ["CMD", "nginx", "-t"]
|
|
22
|
+
interval: 30s
|
|
23
|
+
timeout: 5s
|
|
24
|
+
retries: 3
|
|
25
|
+
start_period: 5s
|
|
26
|
+
acme:
|
|
27
|
+
image: nginxproxy/acme-companion:2.8.1@sha256:ccfceb9798b9f6586d47eeeadbb8e185c8897b34e011a2739a9b82d5e92a8b6c
|
|
28
|
+
restart: unless-stopped
|
|
29
|
+
depends_on:
|
|
30
|
+
proxy:
|
|
31
|
+
condition: service_healthy
|
|
32
|
+
volumes_from:
|
|
33
|
+
- proxy
|
|
34
|
+
volumes:
|
|
35
|
+
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
36
|
+
- ${ULVIA_REPOSITORY_PROXY_DIR}/acme:/etc/acme.sh
|
|
37
|
+
environment:
|
|
38
|
+
DEFAULT_EMAIL: ${ULVIA_ACME_EMAIL}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
services:
|
|
2
|
+
repository:
|
|
3
|
+
image: ${OFFICIAL_REPOSITORY_IMAGE}
|
|
4
|
+
restart: unless-stopped
|
|
5
|
+
init: true
|
|
6
|
+
user: "${ULVIA_UID}:${ULVIA_GID}"
|
|
7
|
+
environment:
|
|
8
|
+
MODE: PROD
|
|
9
|
+
NODE_ENV: production
|
|
10
|
+
REPOSITORY_HOST: 0.0.0.0
|
|
11
|
+
REPOSITORY_PORT: "3000"
|
|
12
|
+
REPOSITORY_PUBLIC_URL: ${ULVIA_REPOSITORY_PUBLIC_URL}
|
|
13
|
+
ULVIA_REPOSITORY_DIR: /var/lib/ulvia-repository
|
|
14
|
+
ULVIA_REPOSITORY_SEED_DIR: ""
|
|
15
|
+
volumes:
|
|
16
|
+
- type: bind
|
|
17
|
+
source: ${ULVIA_REPOSITORY_DIR}
|
|
18
|
+
target: /var/lib/ulvia-repository
|
|
19
|
+
ports:
|
|
20
|
+
- "127.0.0.1:${ULVIA_REPOSITORY_PORT}:3000"
|
|
21
|
+
read_only: true
|
|
22
|
+
tmpfs:
|
|
23
|
+
- /tmp:rw,nosuid,nodev,noexec,size=64m
|
|
24
|
+
cap_drop: [ALL]
|
|
25
|
+
security_opt: [no-new-privileges:true]
|
|
26
|
+
stop_grace_period: 30s
|
|
27
|
+
healthcheck:
|
|
28
|
+
test: ["CMD", "bun", "-e", "const r=await fetch('http://127.0.0.1:3000/readyz'); if(!r.ok) process.exit(1); await r.body?.cancel()"]
|
|
29
|
+
interval: 30s
|
|
30
|
+
timeout: 5s
|
|
31
|
+
retries: 3
|
|
32
|
+
start_period: 5s
|
|
@@ -59,10 +59,11 @@ services:
|
|
|
59
59
|
NODE_ENV: production
|
|
60
60
|
REPOSITORY_HOST: 0.0.0.0
|
|
61
61
|
REPOSITORY_PORT: "3000"
|
|
62
|
+
REPOSITORY_PUBLIC_URL: http://127.0.0.1:${ULVIA_REPOSITORY_PORT}
|
|
62
63
|
ULVIA_LOG_FILE: /var/log/ulvia/repository.ndjson
|
|
63
64
|
ULVIA_REPOSITORY_DIR: /var/lib/ulvia-repository
|
|
64
65
|
ULVIA_REPOSITORY_SEED_DIR: /opt/ulvia-repository-seed
|
|
65
|
-
|
|
66
|
+
stop_grace_period: 30s
|
|
66
67
|
volumes:
|
|
67
68
|
- type: bind
|
|
68
69
|
source: ${ULVIA_REPOSITORY_DIR}
|