@cyaxis/ulvia 1.0.12 → 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,292 +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`.
34
-
35
- ## 2. Install The CLI
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).
36
29
 
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.
49
-
50
- ## 3. Create A Local Site
51
-
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
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`.
45
+
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:
50
+
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.
69
-
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.
73
-
74
- Open `http://my-site.localhost:5100/.cms/setup` and use those credentials. Fresh
75
- instances create zero collections and Pages. Choose an empty site or explicitly
76
- review a recipe from a published collection; no starter or administration site
77
- is bundled. Empty completion leaves `/` returning 404 until a Page is published.
78
- See [first published Page](../product/first-published-page.md) for the current API flow.
79
-
80
- Setup first offers **A Repository address**, **The official Repository**
81
- (`https://repo.ulvia.fr`), or **A new Repository** on this instance. Then choose
82
- an empty site or review a published collection recipe. The URL is stored per
83
- instance; there is no global Repository environment variable or service setting.
84
- The address must be reachable from the Provider. HTTP origins are an explicit
85
- choice; credentials, queries and fragments are forbidden in settings URLs.
86
-
87
- A new Repository installs Registry from the system resources already in the
88
- image and selects this site’s public Edge origin. Its catalogue starts empty.
89
- Self-origin calls use the known private Edge transport; no remote catalogue is
90
- needed for creation or empty completion. Changing a Repository URL affects future
91
- discovery/imports, preserving installed resources and Pages.
92
-
93
- ## 4. Daily Operations
94
-
95
- ```bash
96
- ulvia start
97
- ulvia instance stop my-site
98
- ulvia instance start my-site
99
- ulvia services logs all --level warn
100
- ulvia instance logs my-site edge
101
- ulvia services stop
102
- ```
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.
103
59
 
104
- Stopping containers preserves persistent data. `services stop` also makes every
105
- site unavailable because Edges depend on the shared Provider and proxy.
60
+ ## 3. Configure Control and create sites
106
61
 
107
- ## 5. Upgrade Ulvia
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 `/`.
108
67
 
109
- Upgrade the host CLI through Bun. Naming `latest` explicitly also replaces an
110
- installation that was originally attached to the `next` channel:
68
+ Create sites through Control's admitted `ulvia/cms.hosting` capabilities. The
69
+ HTTP binding for `instances.create` is:
111
70
 
112
- ```bash
113
- bun add --global @cyaxis/ulvia@latest
114
- hash -r
115
- ulvia --version
71
+ ```text
72
+ POST /.cms/call/ulvia/cms.hosting/hosting/instances.create
116
73
  ```
117
74
 
118
- Upgrade deployable components independently with exact versions:
119
-
120
- ```bash
121
- ulvia upgrade edge --version 1.0.7
122
- ulvia upgrade provider --version 1.0.7
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
+ }
123
85
  ```
124
86
 
125
- Ulvia resolves each official Docker Hub tag to an immutable digest and reuses
126
- that digest on subsequent starts. Registry channels such as `next` or `latest`
127
- may identify releases for humans, but an installation never persists or
128
- silently follows those mutable tags.
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.
129
93
 
130
- `upgrade edge` visits every local Edge instance in sequence. A Provider
131
- upgrade affects shared services; Repository instances use those same Provider
132
- and Edge images. A failed activation attempts
133
- to restart the previous image, but this does not restore changed database or
134
- file contents and is not an atomic rollback across all instances.
135
- Take a complete backup before an upgrade involving persisted data. Internal
136
- schema migrations and interrupted-upgrade/restore drills require explicit
137
- implementation and deployment-level verification.
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.
138
97
 
139
- ## 6. Public Domain And HTTPS
140
-
141
- Configure public networking before creating the first instance because the
142
- public Edge URLs become part of Provider provisioning. The CLI separately configures
143
- a private Gateway callback URL and a unique Docker alias for each instance:
98
+ ## 4. Operate and resize the infrastructure
144
99
 
145
100
  ```bash
146
- ulvia configure network \
147
- --bind 0.0.0.0 \
148
- --http-port 80 \
149
- --tls acme \
150
- --https-port 443 \
151
- --acme-email ops@example.com
152
-
153
- ulvia services start
154
- ulvia instance create website --domain example.com
155
- ulvia instance credentials website
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
106
+ ulvia start
107
+ ulvia configure --edges 2
108
+ ulvia apply
156
109
  ```
157
110
 
158
- Before starting, point the domain's DNS records to the host and allow inbound
159
- TCP traffic on ports 80 and 443. Review Docker's documented firewall behavior:
160
- published container ports can bypass some `ufw` and `firewalld` rules unless
161
- the host policy uses Docker's supported chains.
162
-
163
- The Provider operator endpoint remains bound to loopback. A Repository is a
164
- named CMS instance exposed through its Edge and the same shared proxy; it has
165
- no separate management listener.
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.
166
115
 
167
- ## 7. Backup, Reset, And Removal
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.
168
120
 
169
- Stop the installation before taking a filesystem-level backup of the Ulvia data
170
- directory. Preserve the complete directory, including MongoDB, files,
171
- credentials, encryption material, Repository state, and instance definitions.
172
- Do not restore only selected secret or database files from different snapshots.
121
+ ## 5. Configure a public domain and HTTPS
173
122
 
174
- The CLI has no general backup/restore command. Stop each Edge with
175
- `ulvia instance stop <name>`, then stop shared services before copying their
176
- data. Restore and verify a complete backup in an isolated installation before
177
- treating it as a recovery guarantee; do not rely on image fallback to recover
178
- data.
179
-
180
- `reset` permanently removes Ulvia-owned local state:
123
+ Before first launch:
181
124
 
182
125
  ```bash
183
- ulvia reset --yes
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
184
129
  ```
185
130
 
186
- Remove the CLI separately after stopping or resetting the installation:
187
-
188
- ```bash
189
- bun remove --global @cyaxis/ulvia
190
- ```
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.
191
134
 
192
- Removing the CLI alone does not delete persistent CMS data or Docker resources.
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.
193
140
 
194
- ## 8. Troubleshooting
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.
195
149
 
196
- - **Docker permission denied:** complete Docker's Linux post-installation steps,
197
- then start a new login session.
198
- - **`docker compose` is unknown:** install the official Compose plugin rather
199
- than the retired standalone `docker-compose` package.
200
- - **Port 5100, 80, or 443 is occupied:** inspect the owner before changing the
201
- persisted network configuration.
202
- - **An image cannot be pulled:** verify network access and that the requested
203
- exact Cyaxis image version has been published.
204
- - **An instance returns 503:** check `ulvia services status`, then the Provider
205
- and instance Edge logs.
206
- - **Stored encrypted data cannot be opened:** do not generate replacement keys
207
- over an existing data directory; restore the matching complete backup.
208
-
209
- For implementation diagnostics and contributor-only environment overrides, see
210
- the [development and validation guide](../development/README.md).
211
-
212
-
213
- ## 9. Repository CMS Instance
214
-
215
- A Repository uses the normal Edge, official Provider and MongoDB deployment.
216
- It has its own CMS accounts, namespace ownership, uploads and catalogue. No
217
- separate Repository image or signing-key configuration is required.
218
-
219
- For a local installation:
150
+ ## 6. Update, back up or remove
220
151
 
221
152
  ```bash
222
- ulvia services start
223
- ulvia instance create registry
224
- ulvia instance status registry
225
- ulvia instance credentials registry
153
+ ulvia upgrade --version STACK_VERSION
226
154
  ```
227
155
 
228
- The Registry API is available below
229
- `http://registry.localhost:5100/.cms/call/ulvia/repository`. Its public identity
230
- endpoint is `GET /v1/info` relative to that prefix. Ordinary CMS instances do not
231
- expose this contract. Open `/.cms/setup`, sign in and choose **A new Repository**
232
- to activate it. Creation starts with an administrator and system APIs,
233
- without any collection or Page. Publish resources through the CLI/API and install
234
- a website explicitly if needed.
235
-
236
- For public hosting, configure network exposure and ACME as described in section 6
237
- before creating instances, then create the application on its public domain:
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.
164
+
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.
172
+
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.
238
177
 
239
178
  ```bash
240
- ulvia instance create registry --domain repository.example.com
179
+ ulvia reset --yes
180
+ bun remove --global @cyaxis/ulvia
241
181
  ```
242
182
 
243
- Replace the example domain with a domain routed to this host. The same shared
244
- proxy handles its HTTPS certificate. Provider management remains on loopback.
245
-
246
- ### 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.
247
185
 
248
- Registration, password login and PAT management use the normal Access bindings
249
- under `/.cms/call/ulvia/cms.access`. Registration follows the instance policy.
250
- An ordinary account can claim and publish; it does not need CMS administrator
251
- privileges. The protected publisher operations use a shared CMS PAT.
186
+ ## 7. Publish to a Repository
252
187
 
253
- 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.
254
191
 
255
- 1. `POST /signup` with `email` and `password`.
256
- 2. `POST /login-password` with the same credentials; retain its session cookies.
257
- 3. `POST /personal-access-tokens` with the session cookies and a token `name`.
258
- An optional `expiresAt` bounds its lifetime. The plaintext token is returned
259
- only at creation.
260
- 4. Supply that token to the CLI using bounded stdin or `ULVIA_REPOSITORY_TOKEN`.
261
-
262
- Browser/session mutations use the instance's normal Origin and cookie
263
- protections. Tokens can be listed with `GET /personal-access-tokens` and revoked
264
- 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:
265
194
 
266
195
  ```bash
267
196
  ulvia repository login https://repository.example.com --token-stdin
268
- ulvia namespace claim acme
269
- ulvia namespace status acme
197
+ ulvia namespace claim example
270
198
  ulvia release /path/to/resources --recursive
271
199
  ulvia push all
200
+ ulvia repository logout
272
201
  ```
273
202
 
274
- Each published resource's `publisherId` must match a namespace owned by the
275
- account. Contract, Provider manifest and collection dependencies must be present
276
- before dependent publication; `push all` orders locally available releases.
277
- Publication never installs a collection on a site.
278
-
279
- Namespace claims are atomic and limited to 32 owned names per account. Transfer
280
- uses an explicit target account and expected revision. Suspension retains the
281
- name; account deletion is refused while it owns namespaces. Startup does not
282
- reserve or reclaim names, including `ulvia`.
283
-
284
- ### Restart And Updates
285
-
286
- ```bash
287
- ulvia instance stop registry
288
- ulvia instance start registry
289
- ulvia services status
290
- ulvia instance status registry
291
- ulvia upgrade provider --version VERSION
292
- ulvia upgrade edge --version VERSION
293
- ```
294
-
295
- Replace `VERSION` with an exact available image version. The CLI pins image
296
- digests, checks Provider retention before replacing it, and attempts to restore
297
- the previous image if activation fails. Accounts, ownership, releases, Pages and
298
- credentials remain in the normal CMS storage.
299
-
300
- Installed contract and collection upgrades are separate from image replacement.
301
- They use explicit admitted Installations workflows; restart never selects new pins.
302
-
303
- Back up the Provider database, file storage, matching encryption credentials and
304
- private instance configuration together, following section 7. The Repository is
305
- part of this installation: `reset --yes` deletes its data with the other CMS
306
- instances. Client `repository logout` removes its saved PAT connection without
307
- revoking the token remotely.
308
-
309
- ### Contributor Verification
310
-
311
- Build Edge and Provider together. The Repository tests create an instance on an
312
- internal Docker network and use ordinary account PATs; they do not publish
313
- images or contact the public Repository.
314
-
315
- ```bash
316
- bun run images:build --version 0.1.0-integration all
317
- ULVIA_MCP_EDGE_DOCKER_IMAGE=docker.io/cyaxis/ulvia-edge:0.1.0-integration \
318
- ULVIA_MCP_PROVIDER_DOCKER_IMAGE=docker.io/cyaxis/ulvia-provider:0.1.0-integration \
319
- bun test ./tests/images/repository
320
- ```
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.