@soln/cli 0.1.0 → 0.1.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/README.md +88 -0
- package/package.json +1 -1
- package/soln.mjs +85 -74
package/README.md
CHANGED
|
@@ -26,6 +26,94 @@ The current release supports:
|
|
|
26
26
|
npm install -g @soln/cli
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
+
## First Tenant Runtime deployment
|
|
30
|
+
|
|
31
|
+
`sl deployment` is the Control Plane bootstrap flow. It works before Tenant Runtime exists. Ordinary `sl login` is for an installed Runtime and cannot bootstrap a new one. Run `sl deployment guide --json` for the machine-readable sequence. This flow uses Control Plane member APIs; after installation, `sl system ...` commands execute through the Runtime command registry and tenant repositories.
|
|
32
|
+
|
|
33
|
+
Requirements: a Control Plane tenant member with `tenant.runtime.deployment.manage`, Node.js 22+, Docker with Compose and Buildx, Cosign, enough free disk space, and encrypted storage for this-computer installs. A published signed Runtime release and reachable private Registry must already exist. Install on the machine that will run the containers. Do not run the CLI as root unless that is your deliberate deployment account.
|
|
34
|
+
|
|
35
|
+
### 1. Authenticate to the Control Plane
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
sl deployment login --base-url https://api.solncn.com --tenant <tenant-subdomain> --email <member-email>
|
|
39
|
+
sl deployment status --json
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The default method prompts for the account password without echoing it. Add `--method email` to send and enter a verification code. Login validates the deployment permission and stores a separate Control Plane session in `~/.soln/deployment-session.json` with file mode `0600`. It does not require a running Runtime. The status command shows the registration and current release without printing an Agent secret.
|
|
43
|
+
|
|
44
|
+
If login reports `LOGIN_NEXT_STEP_REQUIRED`, finish the indicated account step in the Control Plane. For `DEPLOYMENT_PERMISSION_DENIED`, use a tenant member authorized to manage deployment. An expired session requires a fresh `sl deployment login`.
|
|
45
|
+
|
|
46
|
+
### 2. Register and save the Agent secret
|
|
47
|
+
|
|
48
|
+
For a this-computer install, use an HTTPS `*.localhost` address on port `8443`:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
sl deployment register --dir "$HOME/soln-tenant-runtime" \
|
|
52
|
+
--deployment-target local \
|
|
53
|
+
--runtime-origin https://soln-<tenant-subdomain>.localhost:8443
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
PowerShell:
|
|
57
|
+
|
|
58
|
+
```powershell
|
|
59
|
+
sl deployment register --dir "$HOME\soln-tenant-runtime" `
|
|
60
|
+
--deployment-target local `
|
|
61
|
+
--runtime-origin https://soln-<tenant-subdomain>.localhost:8443
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
For a server install, use `--deployment-target server` and the server's public HTTPS Runtime origin. Add `--deployment-mode externalServices` when PostgreSQL, Redis, Temporal, and object storage are managed outside the deployment. The default mode is `singleMachine`.
|
|
65
|
+
|
|
66
|
+
Registration saves `.soln-install-setup.json` inside the selected directory with mode `0600`; its Agent secret is never printed or put into a shell argument. Keep this file off shared drives and out of Git. The command refuses an existing registration by default: registering again replaces its Agent secret and can disconnect an installed Runtime. Use `--force` only when intentionally replacing that registration; then prepare and install with the new setup. If registration succeeded but saving the setup file failed, register again with `--force` because the first secret cannot be retrieved.
|
|
67
|
+
|
|
68
|
+
### 3. Generate the deployment files
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
sl deployment prepare --dir "$HOME/soln-tenant-runtime"
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
PowerShell:
|
|
75
|
+
|
|
76
|
+
```powershell
|
|
77
|
+
sl deployment prepare --dir "$HOME\soln-tenant-runtime"
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
This fetches the current registration and generates `docker-compose.yml`, `.env.example`, reverse proxy configuration, and supporting files from the Control Plane values. It checks that the saved setup belongs to the same tenant, Runtime ID, origin, Agent, and target. If files already exist, review them before using `--force`; an installed deployment must use `sl upgrade` instead. `prepare` can be retried without registering again.
|
|
81
|
+
|
|
82
|
+
For external services, edit `.env.example` with your service endpoints, credentials, storage settings, and TLS configuration before installation. Use the [server deployment guide](https://help.solncn.com/deployment-operations/server/install) for the required values. For a this-computer install, confirm FileVault, BitLocker, or LUKS is enabled; the CLI requires `--confirm-encrypted-storage`.
|
|
83
|
+
|
|
84
|
+
### 4. Install and verify
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
sl install --dir "$HOME/soln-tenant-runtime" \
|
|
88
|
+
--setup-file .soln-install-setup.json \
|
|
89
|
+
--confirm-encrypted-storage --yes
|
|
90
|
+
sl status --dir "$HOME/soln-tenant-runtime" --check --json
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
PowerShell:
|
|
94
|
+
|
|
95
|
+
```powershell
|
|
96
|
+
sl install --dir "$HOME\soln-tenant-runtime" `
|
|
97
|
+
--setup-file .soln-install-setup.json `
|
|
98
|
+
--confirm-encrypted-storage --yes
|
|
99
|
+
sl status --dir "$HOME\soln-tenant-runtime" --check --json
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Omit `--confirm-encrypted-storage` for server deployment. Install creates `.env` with protected secrets, checks the host and configuration, verifies signed release metadata and container images, obtains short-lived Registry credentials, runs migrations, starts the services, and waits for readiness. If it fails before completion, correct the reported problem and retry the same install command. Do not re-register merely because a local check failed. After a successful install, delete `.soln-install-setup.json`; the installed `.env` holds the Agent credential. Then run `sl deployment logout` to remove the bootstrap session.
|
|
103
|
+
|
|
104
|
+
For a manual preflight, create `.env` from `.env.example`, fill required external-service values if applicable, then run `sl doctor --dir <path> --json`. `sl install` also runs these checks. A `doctor` run directly after `prepare` without `.env` will report the missing environment file.
|
|
105
|
+
|
|
106
|
+
### 5. Operate the installed Runtime
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
sl status --dir <path> --check --json
|
|
110
|
+
sl upgrade --dir <path> --check --json
|
|
111
|
+
sl upgrade --dir <path> --yes
|
|
112
|
+
sl rollback --dir <path> --yes
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Use `sl login` after the Runtime is ready to execute tenant business commands. The deployment session and Runtime member session are separate. If the Agent secret must be replaced later, plan the Runtime reconnection before using `sl deployment register --force`.
|
|
116
|
+
|
|
29
117
|
## Login
|
|
30
118
|
|
|
31
119
|
The `sl` executable uses the same existing member login and local session as the legacy `soln` alias:
|