@sixb/deploy-ssh 0.2.5 → 0.2.7

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.
Files changed (64) hide show
  1. package/README.md +51 -42
  2. package/dist/check/index.d.ts +24 -0
  3. package/dist/check/index.d.ts.map +1 -0
  4. package/dist/check/judge.d.ts +23 -0
  5. package/dist/check/judge.d.ts.map +1 -0
  6. package/dist/index.js +599 -1102
  7. package/dist/index.js.map +10 -15
  8. package/dist/layout.d.ts +91 -18
  9. package/dist/layout.d.ts.map +1 -1
  10. package/dist/operations.d.ts +5 -2
  11. package/dist/operations.d.ts.map +1 -1
  12. package/dist/plan.d.ts +25 -0
  13. package/dist/plan.d.ts.map +1 -0
  14. package/dist/render.d.ts +20 -10
  15. package/dist/render.d.ts.map +1 -1
  16. package/dist/server/manifest.d.ts +15 -3
  17. package/dist/server/manifest.d.ts.map +1 -1
  18. package/dist/server/release-host.d.ts +4 -0
  19. package/dist/server/release-host.d.ts.map +1 -0
  20. package/dist/server/release.d.ts +46 -0
  21. package/dist/server/release.d.ts.map +1 -0
  22. package/dist/server/state.d.ts +2 -0
  23. package/dist/server/state.d.ts.map +1 -1
  24. package/dist/server/supervisor.d.ts +12 -4
  25. package/dist/server/supervisor.d.ts.map +1 -1
  26. package/dist/ssh-target.d.ts +3 -18
  27. package/dist/ssh-target.d.ts.map +1 -1
  28. package/dist/transport.d.ts.map +1 -1
  29. package/package.json +3 -3
  30. package/src/bootstrap.sh +93 -0
  31. package/src/check/index.ts +117 -0
  32. package/src/check/judge.ts +299 -0
  33. package/src/check/probe.sh +99 -0
  34. package/src/layout.ts +117 -34
  35. package/src/operations.ts +104 -61
  36. package/src/plan.ts +59 -0
  37. package/src/render.ts +128 -31
  38. package/src/server/cli.ts +26 -9
  39. package/src/server/manifest.ts +42 -4
  40. package/src/server/release-host.ts +81 -0
  41. package/src/server/release.ts +738 -0
  42. package/src/server/state.ts +3 -1
  43. package/src/server/supervisor.ts +127 -55
  44. package/src/sh.d.ts +4 -0
  45. package/src/ssh-target.ts +46 -227
  46. package/src/transport.ts +28 -12
  47. package/dist/access.d.ts +0 -11
  48. package/dist/access.d.ts.map +0 -1
  49. package/dist/check.d.ts +0 -31
  50. package/dist/check.d.ts.map +0 -1
  51. package/dist/ci.d.ts +0 -27
  52. package/dist/ci.d.ts.map +0 -1
  53. package/dist/keys.d.ts +0 -13
  54. package/dist/keys.d.ts.map +0 -1
  55. package/dist/scripts.d.ts +0 -38
  56. package/dist/scripts.d.ts.map +0 -1
  57. package/dist/setup.d.ts +0 -32
  58. package/dist/setup.d.ts.map +0 -1
  59. package/src/access.ts +0 -107
  60. package/src/check.ts +0 -231
  61. package/src/ci.ts +0 -88
  62. package/src/keys.ts +0 -57
  63. package/src/scripts.ts +0 -323
  64. package/src/setup.ts +0 -203
package/README.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # @sixb/deploy-ssh
2
2
 
3
- The SSH target for `sixb deploy`. It runs a Sixb project on a Linux server you reach over SSH, under
4
- an account without root access, with Caddy serving each domain over HTTPS.
3
+ The SSH target for `sixb deploy`. It runs a Sixb project on a Linux server you reach over SSH, as
4
+ the account `sixb` (or the one `user` names), with Caddy serving each domain over HTTPS, and ships each release beside
5
+ the live one.
5
6
 
6
7
  ```ts
7
8
  // sixb.deploy.ts
@@ -15,61 +16,69 @@ export default defineDeploy({
15
16
  })
16
17
  ```
17
18
 
18
- - [Deploy to a server](https://docs.sixb.ai/deployment/servers): the options, setup, and commands.
19
+ - [Deploy to a server](https://docs.sixb.ai/deployment/servers): the options and commands.
20
+ - [Host requirements](https://docs.sixb.ai/deployment/host-requirements): what a server provides.
19
21
  - [Deploy from GitHub Actions](https://docs.sixb.ai/deployment/github-actions).
20
- - [Server accounts and access](https://docs.sixb.ai/deployment/server-access): who can do what, and
21
- several projects on one server.
22
22
 
23
23
  ## How it works
24
24
 
25
- The rest of this file is for working on the package.
25
+ The rest of this file is for working on the package. The package never sets a server up: it checks
26
+ the host requirements (`src/check/`) and ships releases.
26
27
 
27
28
  ### On the server
28
29
 
29
- Each deployment lives in its deploy user's home:
30
-
31
30
  ```
32
- ~/<name>/code the deployed commit, with the project's .env
33
- ~/<name>/env-token the token a deploy pulls .env with, if the project has a source
34
- ~/<name>/deploy the lock, uploads, file list, release record, process manifest, and ctl
35
- ~/<name>/run process state and logs
36
- ~/.sixb/bun/<v> Bun, shared by the user's projects on the same version
31
+ ~/<name>/releases/<id> immutable releases: code, node_modules, .sixb/dist, .env
32
+ ~/<name>/current the live release; `code` points here too
33
+ ~/<name>/shared/.env the `.env` kept on the server, for a project without a source
34
+ ~/<name>/env-token the token a deploy pulls `.env` with, for a project with one
35
+ ~/<name>/deploy/ lock, uploads and run logs, release record, live slot, slot files, ctl
36
+ ~/<name>/run/<slot>/ each slot's supervisor state, control requests and logs
37
+ ~/.sixb/bun/<version> Bun, shared by releases on the same version
37
38
  ```
38
39
 
39
- - **Processes.** The user unit `~/.config/systemd/user/sixb-<name>.service` runs the supervisor
40
- (`src/server/`, this package's `sixb-deploy-ssh` bin) over `deploy/processes.json`. The
41
- supervisor restarts a process that exits, waiting `restartDelayMs` times its restart count up to
42
- a cap, restarts one past `maxMemory`, and rotates logs at 20 MB. Linger starts the unit at boot.
43
- `deploy/ctl` is what `status`, `logs`, and `restart` call.
44
- - **Routes.** Each deployment writes `/etc/caddy/sixb.d/<user>/<name>.caddy`. Caddy loads it through
45
- the root-owned `/etc/caddy/sixb.d/<user>.caddy`, which imports `/etc/caddy/sixb.d/<user>/*.caddy`,
46
- and the root Caddyfile imports `/etc/caddy/sixb.d/*.caddy`: Caddy allows one `*` per import
47
- pattern. A deploy runs `caddy validate` on the whole configuration before
48
- `sudo systemctl reload caddy`, the one command the `sixb-deploy` group may run as root, and puts
49
- the previous snippet back when Caddy rejects the new one. The app answers 502, 503, and
50
- 504 with the update page in `src/update-page.ts`. Caddy compresses the API's complete JSON
51
- responses (status 200) with zstd or gzip, which the API never does itself; the WebSocket and
52
- other responses pass through untouched, and the app's assets are already precompressed.
53
- - **The deploy.** `src/scripts.ts` renders one script that holds `deploy/lock` throughout and prints
54
- a marker around each step, which the CLI turns into progress. `code/` is updated like
55
- `git reset --hard`, using the previous deploy's `deploy/files.txt` to find removed files.
40
+ - **Slots.** A deployment runs in one of two slots, blue (ports 3001/3002) and green (3011/3012).
41
+ Each is an instance of the template unit `~/.config/systemd/user/sixb-<name>@.service`, whose
42
+ `ExecStart` is the slot's launcher, `deploy/<slot>`: its release's supervisor
43
+ (`src/server/supervisor.ts`) with that release's Bun, over `deploy/<slot>.json`. Lingering starts
44
+ the live slot at boot. Stopping a slot's service signals only the supervisor (`KillMode=mixed`),
45
+ which gives the API and workers up to five minutes to finish their work; the next deploy gives
46
+ a slot still draining ten seconds more before it takes the slot over.
47
+ - **The supervisor** restarts a process that exits, waiting `restartDelayMs` times its restart
48
+ count up to a cap, restarts one past `maxMemory`, and rotates logs at 20 MB. A manifest with
49
+ `holdExclusive` leaves the singletons and project scripts stopped until a deploy starts them.
50
+ - **Routes.** Each deployment writes `/etc/caddy/sixb.d/<account>/<name>.caddy`, which the root
51
+ Caddyfile imports. A deploy validates the whole configuration before
52
+ `sudo systemctl reload caddy`, and puts the previous routes back when Caddy rejects the new ones.
53
+ The app answers 502, 503 and 504 with the update page in `src/update-page.ts`. Caddy compresses
54
+ the API's complete JSON responses; it keeps WebSockets open through a reload with
55
+ `stream_close_delay`, so a retiring API can ask pages to reconnect.
56
+ - **`deploy/ctl`** runs the live release's server half (`src/server/cli.ts`); `status`, `logs`,
57
+ `restart`, `start`, `stop` and `run` go through it.
58
+
59
+ ### A deploy
56
60
 
57
- ### From your machine
61
+ 1. **Laptop** (`src/operations.ts`): `git archive` of the repository and each submodule, streamed
62
+ into `deploy/incoming/`, then the plan (`src/plan.ts`) and `src/bootstrap.sh` into
63
+ `deploy/runs/`. The bootstrap starts with `setsid`, detached from the SSH session, and the
64
+ laptop follows its log with `tail --pid` until the RFC 7464 event that carries its exit code.
65
+ 2. **Bootstrap** (`src/bootstrap.sh`): takes `deploy/lock`, unpacks the release, installs the
66
+ pinned Bun and the dependencies, then runs the release's own runner, which inherits the lock.
67
+ 3. **Runner** (`src/server/release.ts`): pulls `.env`, builds, runs `sixb check --migrate --lake`
68
+ (stopping the live release first when `sixb db migrate --check` finds migrations pending), starts
69
+ the idle slot, waits until it is healthy, moves the routes, moves the singletons, checks
70
+ again, then makes the slot live and stops the other one. Each step that changes what serves
71
+ records an undo; a failure runs them in reverse, which leaves the previous release serving. The
72
+ runner reaches systemd, Caddy and the supervisors through `ReleaseHost`, which the tests fake.
58
73
 
59
- - Each command uses one SSH connection, multiplexed, in batch mode: it never prompts.
60
- `src/transport.ts` rewords OpenSSH's own failures as what to do about them.
61
- - The source is a `git archive` of the repository and of each submodule at its recorded commit,
62
- streamed into `deploy/incoming/`.
63
- - `setup` runs `src/setup.ts`'s script as the admin login with a terminal attached, so `sudo` can
64
- ask for a password. `check` runs `src/check.ts`'s script as the deploy user; it prints one
65
- `__SIXB_CHECK__` line per check.
66
- - `access` rewrites `authorized_keys` through a rename, and refuses when the file changed since it
67
- was read. `ci` makes its key in `src/ci.ts`.
74
+ A server from before slots runs one unit, `sixb-<name>.service`. The first slot deploy adopts it as
75
+ the live slot, on the ports its manifest records, and retires it once the new slot serves.
68
76
 
69
77
  ### Testing
70
78
 
71
- `bun test deploy/ssh/tests` runs the unit tests. `tests/server.e2e.ts` deploys Northline to a
72
- server that `sixb deploy setup` prepared, and drives it through the CLI:
79
+ `bun test deploy/ssh/tests` runs the unit tests: the rollout against a fake server
80
+ (`release.test.ts`), the bootstrap with stand-in tools, the probe and its judge, the supervisor.
81
+ `tests/server.e2e.ts` deploys Northline to a real server and drives it through the CLI:
73
82
 
74
83
  ```bash
75
84
  SIXB_DEPLOY_TEST_HOST=203.0.113.10 SIXB_DEPLOY_TEST_DOMAIN=example.com \
@@ -0,0 +1,24 @@
1
+ import type { DeployCheck, DeployRelease } from "@sixb/core/deploy";
2
+ import type { RemoteShell } from "../transport";
3
+ import { type JudgeInput } from "./judge";
4
+ export { HOST_REQUIREMENTS } from "./judge";
5
+ /** Runs the read-only probe as the deploy account, and judges what it reports. */
6
+ export declare function checkHost(shell: RemoteShell, input: JudgeInput & {
7
+ readonly projectPath: string;
8
+ }): Promise<DeployCheck[]>;
9
+ /** The probe, with what it needs to know set above it. */
10
+ export declare function renderProbe(input: {
11
+ readonly name: string;
12
+ readonly projectPath: string;
13
+ readonly ports: readonly number[];
14
+ readonly chromium: boolean;
15
+ }): string;
16
+ /**
17
+ * Where each HTTP domain resolves, against the server's address. Reached over a tailnet or a
18
+ * private network, the server's public address is unknown here, so the check only says where
19
+ * each domain points.
20
+ */
21
+ export declare function checkDns(release: DeployRelease, hostname: string): Promise<DeployCheck[]>;
22
+ /** Private, carrier-grade NAT (Tailscale's 100.64.0.0/10) and unique-local addresses. */
23
+ export declare function isPrivateAddress(address: string): boolean;
24
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/check/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,SAAS,CAAA;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE3C,kFAAkF;AAClF,wBAAsB,SAAS,CAC7B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,UAAU,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,WAAW,EAAE,CAAC,CAQxB;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B,GAAG,MAAM,CAQT;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAqC/F;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAUzD"}
@@ -0,0 +1,23 @@
1
+ import type { DeployCheck } from "@sixb/core/deploy";
2
+ /** Where every remedy points: the list of what a server provides. */
3
+ export declare const HOST_REQUIREMENTS = "https://docs.sixb.ai/deployment/host-requirements";
4
+ /** What the probe reported, by key. */
5
+ export type HostFacts = ReadonlyMap<string, string>;
6
+ export interface JudgeInput {
7
+ /** The deployment's `name`: its folder in the account's home. */
8
+ readonly name: string;
9
+ /** The loopback ports the deployment's slots listen on. */
10
+ readonly ports: readonly number[];
11
+ /**
12
+ * Where the server's settings come from: the project's source, read with the env token or with
13
+ * the server's own identity, or the `.env` kept on the server.
14
+ */
15
+ readonly settings: "env-token" | "identity" | "env-file";
16
+ /** The project prints with Chromium, so the server needs Chromium's libraries. */
17
+ readonly chromium: boolean;
18
+ }
19
+ /** Reads the probe's `fact<TAB>key<TAB>value` lines. */
20
+ export declare function parseFacts(lines: readonly string[]): HostFacts;
21
+ /** What the facts mean for a deploy, one check per host requirement. */
22
+ export declare function judge(facts: HostFacts, input: JudgeInput): DeployCheck[];
23
+ //# sourceMappingURL=judge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/check/judge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,sDAAsD,CAAA;AAGpF,uCAAuC;AACvC,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAEnD,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAAA;IACxD,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAyBD,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAO9D;AAED,wEAAwE;AACxE,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,WAAW,EAAE,CAiBxE"}