@cyaxis/ulvia 1.0.8 → 1.0.18

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
@@ -1,27 +1,20 @@
1
1
  # Install Ulvia
2
2
 
3
- This guide installs the Ulvia CLI and runs CMS instances on Ubuntu, including
4
- a Repository application. For a dedicated Repository host, use the same shared
5
- services and follow section 9.
6
- It is for operators and site owners; workspace contributors should use the
7
- [development guide](../development/README.md).
3
+ This guide describes the shared-hosting implementation in this checkout. Use a
4
+ CLI release paired with Provider and Edge images supporting hosting API v1;
5
+ older images using the per-site Edge model are incompatible. See
6
+ [shared-hosting verification](SHARED-HOSTING.md) for the current
7
+ integration coverage and deployment limits.
8
8
 
9
- > **Prerelease availability:** `@cyaxis/ulvia` is the official release package.
10
- > Prereleases use the npm `next` tag; stable releases use `latest`.
9
+ ## 1. Prepare the server
11
10
 
12
- ## 1. Prerequisites On Ubuntu
11
+ Install Docker Engine, its Compose plugin and Bun. The workspace toolchain uses
12
+ Bun 1.4.4. Docker must run and be accessible to the account launching Ulvia.
13
13
 
14
- Ulvia requires a supported Ubuntu host, Docker Engine with the Docker Compose
15
- plugin, and Bun. Follow the upstream instructions rather than copying an
16
- unversioned third-party installation script:
17
-
18
- - [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
19
- - [Install the Docker Compose plugin on Linux](https://docs.docker.com/compose/install/linux/)
20
- - [Run Docker without `sudo` and configure startup](https://docs.docker.com/engine/install/linux-postinstall/)
21
- - [Install Bun on Linux](https://bun.com/docs/installation)
22
-
23
- Docker's Ubuntu packages include the Compose plugin when
24
- `docker-compose-plugin` is installed. Verify the complete toolchain:
14
+ - [Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
15
+ - [Docker Compose plugin](https://docs.docker.com/compose/install/linux/)
16
+ - [Docker Linux post-installation](https://docs.docker.com/engine/install/linux-postinstall/)
17
+ - [Bun installation](https://bun.com/docs/installation)
25
18
 
26
19
  ```bash
27
20
  docker version
@@ -29,324 +22,186 @@ docker compose version
29
22
  bun --version
30
23
  ```
31
24
 
32
- The current release toolchain targets Bun 1.4.4 or newer. Docker must be running
33
- and accessible to the account that executes `ulvia`.
25
+ Install the chosen compatible CLI release with
26
+ `bun add --global @cyaxis/ulvia@CLI_VERSION`, replacing `CLI_VERSION` with its
27
+ exact version. Workspace contributors can use `bun run ulvia --` instead;
28
+ see [development](https://github.com/matthias-bernouy/CMS/blob/e5bd135c8e692867eb6fc298ff6c36be0c4ad6cc/docs/development/README.md).
34
29
 
35
- ## 2. Install The CLI
36
-
37
- Install the current stable CLI globally from the public npm registry:
30
+ ## 2. Start a local installation
38
31
 
39
32
  ```bash
40
- bun add --global @cyaxis/ulvia@latest
41
- ulvia --help
33
+ ulvia configure --domain control.localhost --edges 1
34
+ ulvia apply
35
+ ulvia status
42
36
  ```
43
37
 
44
- If `ulvia` is not found, reopen the terminal and check that `~/.bun/bin` is in
45
- `PATH`, as described by the Bun installation guide.
46
-
47
- Use an exact version, for example `@cyaxis/ulvia@1.0.7`, when reproducing an
48
- installation. The `next` tag is reserved for explicitly tested prereleases.
38
+ A packaged CLI contains its exact initial stack version. Workspace source needs
39
+ `ulvia apply --version STACK_VERSION`, with an exact version of locally built or
40
+ published compatible images. First apply reuses valid cached images and pulls
41
+ missing images. It checks component, stack API, hosting API, version and immutable
42
+ repository digest. The applied snapshot keeps both image pins, the pinned
43
+ Caddy/MongoDB definitions and their configuration. `start` only starts existing
44
+ containers from that snapshot. Missing containers require `apply`.
49
45
 
50
- ## 3. Create A Local Site
46
+ One Compose project contains Provider, MongoDB, Caddy and the shared Edge pool.
47
+ The Provider creates Control automatically. Its default address is
48
+ `http://control.localhost:5100/.cms/setup`. The CLI announces a private file
49
+ containing the initial administrator email and password:
51
50
 
52
- Start the shared infrastructure, then create one named instance:
53
-
54
- ```bash
55
- ulvia services start
56
- ulvia instance create my-site --label "My site"
57
- ulvia instance credentials my-site
51
+ ```text
52
+ <data>/services/credentials/control-administrator.json
58
53
  ```
59
54
 
60
- The first start uses the exact software version bundled into the installed CLI.
61
- To select an exact initial version explicitly, use
62
- `ulvia services start --version 1.0.7`. This option never upgrades an
63
- existing installation.
64
-
65
- First startup reuses locally cached exact-version images after checking their
66
- component, stack API, version and immutable digest. It downloads missing images.
67
- With the runtime and infrastructure images already present, initial provisioning
68
- can run without Internet access. Explicit image upgrades still pull the requested tag.
55
+ Read that file locally to sign in. The CLI prints only its path. Credentials use
56
+ mode 0600 in a private directory. A ready restart does not recreate a removed
57
+ bootstrap file or reset the account. Preserve infrastructure keys separately
58
+ from this one-time administrator bootstrap input.
69
59
 
70
- The site is available at `http://my-site.localhost:5100`. The credentials
71
- command prints the initial administrator email and password. It never prints
72
- the Provider, Repository, encryption, or instance service secrets.
60
+ ## 3. Configure Control and create sites
73
61
 
74
- The Provider uses `https://repo.ulvia.fr` by default for resource discovery
75
- and connected-account publications. The shared stack contains the proxy, MongoDB and Provider. Repository hosting
76
- is selected explicitly on a named CMS instance.
62
+ Open Control's `/.cms/setup`, authenticate and choose a Repository. Native setup
63
+ supports a custom Repository, the official Repository, or creating a new Registry
64
+ on Control. Then explicitly choose an empty site or a published collection recipe.
65
+ No console collection, starter, Page or administration application is bundled.
66
+ An empty completed site legitimately returns 404 at `/`.
77
67
 
78
- When initializing a node, select another Repository by setting
79
- `CMS_REPOSITORY_URL` on the first configuration or startup command. For an
80
- isolated local installation:
68
+ Create sites through Control's admitted `ulvia/cms.hosting` capabilities. The
69
+ HTTP binding for `instances.create` is:
81
70
 
82
- ```bash
83
- CMS_REPOSITORY_URL=http://repository:3000 \
84
- CMS_REPOSITORY_ALLOW_INSECURE_HTTP=true ulvia services start
71
+ ```text
72
+ POST /.cms/call/ulvia/cms.hosting/hosting/instances.create
85
73
  ```
86
74
 
87
- Here `repository:3000` is a Repository CMS Edge address reachable from the
88
- Provider containers. Initial provisioning uses the bundled application profile
89
- before the remote catalogue is available.
90
-
91
- The selected connection is persisted as `repository.url` and
92
- `repository.allowInsecureHttp` in
93
- `~/.local/share/ulvia/services/installation.json`. Later environment changes
94
- do not replace an existing connection. To change it, update those fields and
95
- run `ulvia services start`. The Provider bundles admitted resources needed for initial provisioning; it
96
- does not need to contact this Repository to bootstrap its shipped profiles.
97
- Remote discovery and publication still require the configured Repository. An
98
- origin remains required in configuration even when it is unavailable at bootstrap.
99
- Creating a Repository instance neither changes that connection nor publishes the
100
- image-owned bootstrap artifacts into its public catalogue.
101
-
102
- Ulvia deliberately separates shared services from sites:
103
-
104
- | Command | Responsibility |
105
- | --- | --- |
106
- | `ulvia services start` | Starts the proxy, MongoDB and Provider. |
107
- | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Edge. |
108
- | `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
109
- | `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
110
-
111
- List and inspect the installation at any time:
112
-
113
- ```bash
114
- ulvia services status
115
- ulvia instance list
116
- ulvia instance status my-site
75
+ ```json
76
+ {
77
+ "requestId": "10000000-0000-4000-8000-000000000001",
78
+ "label": "Example site",
79
+ "origin": "http://example.localhost:5100",
80
+ "administrator": {
81
+ "email": "owner@example.test",
82
+ "password": "replace-with-a-private-password"
83
+ }
84
+ }
117
85
  ```
118
86
 
119
- Persistent data lives below `$XDG_DATA_HOME/ulvia` or
120
- `~/.local/share/ulvia`. Commands can be run from any working directory.
87
+ Use an authenticated current Control administrator and the site's ordinary
88
+ Origin/session protections. Each new creation needs its own UUID; an exact retry
89
+ with the same UUID recovers that operation. Check `instance.status`: provisioning
90
+ acceptance alone is not readiness. The contract also exposes bounded listing,
91
+ state inspection, disable and domain administration through HTTP/MCP bindings.
92
+ An ordinary site's administrator cannot manage hosting.
121
93
 
122
- ## 4. Daily Operations
94
+ All logical sites use the shared pool. Their creation launches no additional
95
+ process. Sites use native setup with their own accounts and Repository settings.
96
+ A collection selected later grants no hosting authority.
97
+
98
+ ## 4. Operate and resize the infrastructure
123
99
 
124
100
  ```bash
101
+ ulvia status
102
+ ulvia logs --filter component=provider
103
+ ulvia logs --filter service=edge-1 --follow
104
+ ulvia logs --filter component=proxy
105
+ ulvia stop
125
106
  ulvia start
126
- ulvia instance stop my-site
127
- ulvia instance start my-site
128
- ulvia services logs all --level warn
129
- ulvia instance logs my-site edge
130
- ulvia services stop
107
+ ulvia configure --edges 2
108
+ ulvia apply
131
109
  ```
132
110
 
133
- Stopping containers preserves persistent data. `services stop` also makes every
134
- site unavailable because Edges depend on the shared Provider and proxy.
135
-
136
- ## 5. Upgrade Ulvia
111
+ Stopping services retains data and makes all sites unavailable. Resizing changes
112
+ shared Edge processes independently of the number of sites; reducing the count
113
+ removes obsolete Edge containers. Domain and instance disable operations belong
114
+ to Control's contracts, not container lifecycle commands.
137
115
 
138
- Upgrade the host CLI through Bun. Naming `latest` explicitly also replaces an
139
- installation that was originally attached to the `next` channel:
116
+ Persistent data defaults to `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`.
117
+ `ULVIA_DATA_DIR` explicitly isolates an installation. The CLI keeps hosting/network
118
+ configuration, launch intent, exact image pins, database, file storage and private
119
+ keys below that directory. Infrastructure mutations share a native process lock.
140
120
 
141
- ```bash
142
- bun add --global @cyaxis/ulvia@latest
143
- hash -r
144
- ulvia --version
145
- ```
121
+ ## 5. Configure a public domain and HTTPS
146
122
 
147
- Upgrade deployable components independently with exact versions:
123
+ Before first launch:
148
124
 
149
125
  ```bash
150
- ulvia upgrade edge --version 1.0.7
151
- ulvia upgrade provider --version 1.0.7
126
+ ulvia configure --bind 0.0.0.0 --http-port 80 --tls acme --https-port 443 --acme-email ops@example.com
127
+ ulvia configure --domain control.example.com --public-addresses 203.0.113.10
128
+ ulvia apply
152
129
  ```
153
130
 
154
- Ulvia resolves each official Docker Hub tag to an immutable digest and reuses
155
- that digest on subsequent starts. Registry channels such as `next` or `latest`
156
- may identify releases for humans, but an installation never persists or
157
- silently follows those mutable tags.
131
+ Replace the example domain and address with your deployment values. Point all
132
+ A/AAAA records at the configured entrypoints and permit inbound TCP 80/443.
133
+ Provider operator access stays on loopback; MongoDB publishes no host port.
158
134
 
159
- `upgrade edge` visits every local Edge instance in sequence. A Provider
160
- upgrade affects shared services; Repository instances use those same Provider
161
- and Edge images. A failed activation attempts
162
- to restart the previous image, but this does not restore changed database or
163
- file contents and is not an atomic rollback across all instances.
164
- Take a complete backup before an upgrade involving persisted data. Internal
165
- schema migrations and interrupted-upgrade/restore drills remain
166
- [open platform work](../TODO.md#internal-persistence-migrations).
135
+ The domain is registered during Control bootstrap, before certificate readiness.
136
+ Caddy asks the admitted TLS permission binding for authorization. Unknown,
137
+ unverified or disabled domains cannot obtain permission. Its certificate store
138
+ persists independently of containers. Instance provisioning, DNS/domain readiness,
139
+ HTTPS readiness and backend health are distinct; startup reports pending access.
167
140
 
168
- ## 6. Public Domain And HTTPS
141
+ `configure` records desired settings without contacting Docker. `apply` deploys
142
+ them; `status` reports pending changes. Interactive `configure` requires a terminal,
143
+ while `configure --show` prints desired settings. Network settings and Control
144
+ origin lock after the first deployment.
145
+ The public-address allowlist can be updated with `configure`, then
146
+ `apply`. Explicitly configure operator-owned suffixes with `--managed-suffixes`
147
+ only for DNS space controlled by this installation. Other customer domains require
148
+ the ownership proof supplied through Control's domain capabilities.
169
149
 
170
- Configure public networking before creating the first instance because the
171
- public Edge URLs become part of Provider provisioning. The CLI separately configures
172
- a private Gateway callback URL and a unique Docker alias for each instance:
150
+ ## 6. Update, back up or remove
173
151
 
174
152
  ```bash
175
- ulvia configure network \
176
- --bind 0.0.0.0 \
177
- --http-port 80 \
178
- --tls acme \
179
- --https-port 443 \
180
- --acme-email ops@example.com
181
-
182
- ulvia services start
183
- ulvia instance create website --domain example.com
184
- ulvia instance credentials website
153
+ ulvia upgrade --version STACK_VERSION
185
154
  ```
186
155
 
187
- Before starting, point the domain's DNS records to the host and allow inbound
188
- TCP traffic on ports 80 and 443. Review Docker's documented firewall behavior:
189
- published container ports can bypass some `ufw` and `firewalld` rules unless
190
- the host policy uses Docker's supported chains.
191
-
192
- The Provider operator endpoint remains bound to loopback. A Repository is a
193
- named CMS instance exposed through its Edge and the same shared proxy; it has
194
- no separate management listener.
195
-
196
- ## 7. Backup, Reset, And Removal
197
-
198
- Stop the installation before taking a filesystem-level backup of the Ulvia data
199
- directory. Preserve the complete directory, including MongoDB, files,
200
- credentials, encryption material, Repository state, and instance definitions.
201
- Do not restore only selected secret or database files from different snapshots.
156
+ Replace `STACK_VERSION` with an exact published distribution version. `upgrade`
157
+ without a version uses the release embedded in the CLI. The versioned CLI npm
158
+ archive contains `dist/stack-release.json`: the complete Compose definitions and
159
+ pinned Caddy/MongoDB images. Explicit other versions are fetched from the official
160
+ `@cyaxis/ulvia` npm archive, bounded and verified against its registry SHA-512
161
+ integrity. Provider and Edge image labels, compatibility and immutable repository
162
+ digests are checked before activation. Publish the CLI and both images with the
163
+ same version before offering a release.
202
164
 
203
- The CLI has no general backup/restore command. Stop each Edge with
204
- `ulvia instance stop <name>`, then stop shared services before copying their
205
- data. Restore and verify a complete backup in an isolated installation before
206
- treating it as a recovery guarantee; do not rely on image fallback to recover
207
- data. See [operational recovery](../TODO.md#backup-and-operational-recovery).
165
+ Apply pending configuration before upgrading. Upgrades check Provider retained
166
+ execution support, update the Provider, replace Edges in sequence and apply the
167
+ proxy. MongoDB major changes and downgrades require an explicit migration. A
168
+ failed operation retains its target and the previous successful snapshot;
169
+ `status` reports actual service/image state and `upgrade` resumes the exact target.
170
+ `start` refuses an unfinished operation. Recovery does not restore database or
171
+ file contents. Contract and collection upgrades remain separate domain operations.
208
172
 
209
- `reset` permanently removes Ulvia-owned local state:
173
+ Stop all shared services before a filesystem backup. Preserve the complete
174
+ matching data directory, including MongoDB, file storage and encryption material.
175
+ Validate restores in isolation. Missing mandatory settings or keys over existing
176
+ state refuse startup; no silent historical import or key regeneration occurs.
210
177
 
211
178
  ```bash
212
179
  ulvia reset --yes
213
- ```
214
-
215
- Remove the CLI separately after stopping or resetting the installation:
216
-
217
- ```bash
218
180
  bun remove --global @cyaxis/ulvia
219
181
  ```
220
182
 
221
- Removing the CLI alone does not delete persistent CMS data or Docker resources.
222
-
223
- ## 8. Troubleshooting
224
-
225
- - **Docker permission denied:** complete Docker's Linux post-installation steps,
226
- then start a new login session.
227
- - **`docker compose` is unknown:** install the official Compose plugin rather
228
- than the retired standalone `docker-compose` package.
229
- - **Port 5100, 80, or 443 is occupied:** inspect the owner before changing the
230
- persisted network configuration.
231
- - **An image cannot be pulled:** verify network access and that the requested
232
- exact Cyaxis image version has been published.
233
- - **An instance returns 503:** check `ulvia services status`, then the Provider
234
- and instance Edge logs.
235
- - **Stored encrypted data cannot be opened:** do not generate replacement keys
236
- over an existing data directory; restore the matching complete backup.
237
-
238
- For implementation diagnostics and contributor-only environment overrides, see
239
- the [development and validation guide](../development/README.md).
240
-
241
-
242
- ## 9. Repository CMS Instance
243
-
244
- A Repository uses the normal Edge, official Provider and MongoDB deployment.
245
- It has its own CMS accounts, namespace ownership, uploads and catalogue. No
246
- separate Repository image or signing-key configuration is required.
247
-
248
- For a local installation:
249
-
250
- ```bash
251
- ulvia services start
252
- ulvia instance create registry --profile repository@1.0.0
253
- ulvia instance status registry
254
- ulvia instance credentials registry
255
- ```
256
-
257
- The Registry API is available below
258
- `http://registry.localhost:5100/.cms/call/ulvia/repository`. Its public identity
259
- endpoint is `GET /v1/info` relative to that prefix. Ordinary CMS instances do not
260
- expose this contract. The profile creates ordinary CMS Pages for the public
261
- catalogue, search, resource details, registration/login and personal namespaces,
262
- publications and PAT management. These Pages use the `ulvia/repository` collection
263
- and shared `ulvia/mossa` resources.
264
-
265
- For public hosting, configure network exposure and ACME as described in section 6
266
- before creating instances, then create the application on its public domain:
267
-
268
- ```bash
269
- ulvia instance create registry --domain repository.example.com --profile repository@1.0.0
270
- ```
271
-
272
- Replace the example domain with a domain routed to this host. The same shared
273
- proxy handles its HTTPS certificate. Provider management remains on loopback.
274
-
275
- ### Publisher Accounts And Credentials
183
+ Reset permanently deletes Ulvia-owned installation data and the local release
184
+ cache. Removing the CLI alone does not delete data or Docker resources.
276
185
 
277
- Registration, password login and PAT management use the normal Access bindings
278
- under `/.cms/call/ulvia/cms.access`. Registration follows the instance policy.
279
- An ordinary account can claim and publish; it does not need CMS administrator
280
- privileges. The protected publisher operations use a shared CMS PAT.
186
+ ## 7. Publish to a Repository
281
187
 
282
- The current API flow is:
188
+ Any logical site can explicitly activate Registry during native setup. It uses
189
+ the same Provider, shared Edges and proxy, with its own CMS accounts, catalogue
190
+ and namespace ownership. It has no separate Repository image or signing setup.
283
191
 
284
- 1. `POST /signup` with `email` and `password`.
285
- 2. `POST /login-password` with the same credentials; retain its session cookies.
286
- 3. `POST /personal-access-tokens` with the session cookies and a token `name`.
287
- An optional `expiresAt` bounds its lifetime. The plaintext token is returned
288
- only at creation.
289
- 4. Supply that token to the CLI using bounded stdin or `ULVIA_REPOSITORY_TOKEN`.
290
-
291
- Browser/session mutations use the instance's normal Origin and cookie
292
- protections. Tokens can be listed with `GET /personal-access-tokens` and revoked
293
- with `DELETE /personal-access-tokens/:id` by their owning account.
192
+ Ordinary Repository accounts can register/login through `ulvia/cms.access` and
193
+ create a personal access token. Supply that token through bounded stdin:
294
194
 
295
195
  ```bash
296
196
  ulvia repository login https://repository.example.com --token-stdin
297
- ulvia namespace claim acme
298
- ulvia namespace status acme
197
+ ulvia namespace claim example
299
198
  ulvia release /path/to/resources --recursive
300
199
  ulvia push all
200
+ ulvia repository logout
301
201
  ```
302
202
 
303
- Each published resource's `publisherId` must match a namespace owned by the
304
- account. Contract, Provider manifest and collection dependencies must be present
305
- before dependent publication; `push all` orders locally available releases.
306
- Publication never installs a collection on a site.
307
-
308
- Namespace claims are atomic and limited to 32 owned names per account. Transfer
309
- uses an explicit target account and expected revision. Suspension retains the
310
- name; account deletion is refused while it owns namespaces. Startup does not
311
- reserve or reclaim names, including `ulvia`.
312
-
313
- ### Restart And Updates
314
-
315
- ```bash
316
- ulvia instance stop registry
317
- ulvia instance start registry
318
- ulvia services status
319
- ulvia instance status registry
320
- ulvia upgrade provider --version VERSION
321
- ulvia upgrade edge --version VERSION
322
- ```
323
-
324
- Replace `VERSION` with an exact available image version. The CLI pins image
325
- digests, checks Provider retention before replacing it, and attempts to restore
326
- the previous image if activation fails. Accounts, ownership, releases, Pages and
327
- credentials remain in the normal CMS storage.
328
-
329
- A profile change is separate from an image replacement:
330
- `ulvia instance upgrade-profile registry ID@VERSION`. The target must be a
331
- supported explicit transition shipped by the Provider and retain the
332
- `ulvia/repository` application ID. The CLI saves the exact new reference only
333
- after the Provider acknowledges it. Restart never selects a different profile.
334
-
335
- Back up the Provider database, file storage, matching encryption credentials and
336
- private instance configuration together, following section 7. The Repository is
337
- part of this installation: `reset --yes` deletes its data with the other CMS
338
- instances. Client `repository logout` removes its saved PAT connection without
339
- revoking the token remotely.
340
-
341
- ### Contributor Verification
342
-
343
- Build Edge and Provider together. The Repository tests create an instance on an
344
- internal Docker network and use ordinary account PATs; they do not publish
345
- images or contact the public Repository.
346
-
347
- ```bash
348
- bun run images:build --version 0.1.0-integration all
349
- ULVIA_MCP_EDGE_DOCKER_IMAGE=docker.io/cyaxis/ulvia-edge:0.1.0-integration \
350
- ULVIA_MCP_PROVIDER_DOCKER_IMAGE=docker.io/cyaxis/ulvia-provider:0.1.0-integration \
351
- bun test ./tests/images/repository
352
- ```
203
+ Login pins the Repository origin and identity. Publication refuses cross-origin
204
+ credential forwarding and redirects, validates namespace ownership and dependencies,
205
+ and does not install resources into any site. Logout removes the saved connection
206
+ without revoking its remote PAT. Site Repository settings and CLI publisher
207
+ connections are independent.