feat: add Linux server operational delivery assets
This commit is contained in:
+4
-2
@@ -9,8 +9,8 @@ Read the documents in this order:
|
||||
script transfer, heartbeat, and failure containment.
|
||||
3. [Control plane](control-plane.md) — `rvc`, Unix-socket gRPC, JSON-RPC, and
|
||||
query/foreground semantics.
|
||||
4. [Platform and operations](platform-and-operations.md) — Unix/Windows
|
||||
contracts, recovery, storage safety, telemetry, and defaults.
|
||||
4. [Platform and operations](platform-and-operations.md) — Windows contract,
|
||||
recovery, storage safety, telemetry, and defaults.
|
||||
5. [Configuration contract](configuration.md) — strict TOML loading, shell
|
||||
resolution, cross-field validation, and annotated server/client examples.
|
||||
6. [Go implementation plan](implementation-plan.v1.md) — phased build order,
|
||||
@@ -22,6 +22,8 @@ Read the documents in this order:
|
||||
procedure, and known limitations.
|
||||
9. [Interactive VM access](../test/rdp-access/README.md) — temporary,
|
||||
self-signed HTTPS browser gateway for the rare manual UAC recovery step.
|
||||
10. [Linux-server operations runbook](operations-runbook.md) — deployment,
|
||||
backup/restore, upgrade, and incident response.
|
||||
|
||||
The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1):
|
||||
`common.proto` contains shared data types, `agent.proto` contains the
|
||||
|
||||
@@ -11,12 +11,10 @@ binaries:
|
||||
spool, and reconnect/reconciliation owner.
|
||||
- `rvc`: local CLI over the server's Unix-domain gRPC socket.
|
||||
|
||||
The first supported client target is Windows connecting to a Linux server;
|
||||
Linux client support remains part of complete v1 but is explicitly deferred
|
||||
from the current implementation effort. Implement the Linux server and native
|
||||
Windows client first; do not begin Unix-like client code now. Build shared
|
||||
client runtime code behind OS interfaces without prematurely implementing the
|
||||
Unix supervisor. Windows v1 requires Windows 10 or newer, or Windows Server 2016
|
||||
The v1 product boundary is a Linux server and a native Windows client. A
|
||||
Unix-like client is outside v1 and must not be started as part of this plan.
|
||||
Build shared client runtime code behind OS interfaces without prematurely
|
||||
implementing the Unix supervisor. Windows v1 requires Windows 10 or newer, or Windows Server 2016
|
||||
or newer. Desktop Experience is required only for the tray and active-session
|
||||
command contexts; the service and Session 0 execution contexts support headless
|
||||
Server Core.
|
||||
@@ -2326,7 +2324,7 @@ version. Assert no Task Scheduler object is created or required.
|
||||
loss/restart, execute up to capacity at most once, preserve/replay bounded
|
||||
history, manage complete Job trees, and satisfy tray/elevation/autostart behavior
|
||||
on Windows CI, including all execution-hierarchy rows. Reaching this gate does
|
||||
not automatically start the deferred Unix-client work; that requires an explicit
|
||||
not automatically start future post-v1 Unix-client work; that requires an explicit
|
||||
later implementation decision.
|
||||
|
||||
## 8. End-to-end agent protocol (Phase 5)
|
||||
@@ -2383,7 +2381,7 @@ the visible CLI result. Include these cross-cutting cases:
|
||||
server demonstrates a complete background command, history/follow behavior,
|
||||
stdin interaction, signal, reconnect, and restart recovery through nginx WSS.
|
||||
This is the first supported-client milestone. It satisfies a prerequisite for
|
||||
the deferred Linux supervisor work but does not automatically authorize it.
|
||||
future Linux-supervisor work but does not automatically authorize it.
|
||||
|
||||
## 9. Server control plane and `rvc` (Phase 6)
|
||||
|
||||
@@ -2534,14 +2532,14 @@ stack; the Unix socket has mode `0600`; JSON-RPC behavior matches gRPC unary
|
||||
semantics and is off unless explicitly enabled; the control integration suite
|
||||
can be interrupted, resumed, and reset through the shared run ID.
|
||||
|
||||
## 10. Deferred Linux client implementation (Phase 7; still required for full v1)
|
||||
## 10. Future Unix-like client work (outside v1)
|
||||
|
||||
This phase is design-only in the current effort. Do not implement it now. Retain
|
||||
these tasks so the later Unix-client work completes the already defined v1
|
||||
contract without weakening the shipped Windows behavior.
|
||||
This work is outside the v1 product boundary. Do not implement it now. Retain
|
||||
these tasks as the starting point for a later Unix-client scope without
|
||||
weakening the shipped Windows behavior.
|
||||
|
||||
Begin this phase only after both an explicit later implementation decision and
|
||||
the Windows Phase 4/5 release gates. Keep Unix code in platform-specific files/
|
||||
Begin this work only after an explicit later implementation decision and the
|
||||
Windows release gates. Keep Unix code in platform-specific files/
|
||||
build tags and reuse the proven runtime/store/protocol contracts without
|
||||
changing their wire semantics to suit Linux.
|
||||
|
||||
@@ -2602,9 +2600,9 @@ reconnect/replay, truncation, scripts, tombstones, queue limits, `/proc`
|
||||
absence, profile failure, and shutdown interruption. Add explicit tests for
|
||||
pidfd/`clone3` availability fallbacks and deliberate `setsid` escape behavior.
|
||||
|
||||
**Exit criteria:** the Linux client passes the same protocol/durability suite as
|
||||
Windows, plus cgroup/process-group tests, without weakening the already shipped
|
||||
Windows behavior or changing the v1 wire contract.
|
||||
**Future exit criteria:** the Linux client passes the same protocol/durability
|
||||
suite as Windows, plus cgroup/process-group tests, without weakening the
|
||||
already shipped Windows behavior or changing the established wire contract.
|
||||
|
||||
## 11. Reliability, observability, and operational delivery (Phase 8)
|
||||
|
||||
@@ -2691,9 +2689,8 @@ The currently authorized merge order is deliberately vertical:
|
||||
8. The Windows-applicable Phase 8 operational, packaging, stress, and release
|
||||
gates needed for the Linux-server/Windows-client milestone.
|
||||
|
||||
Stop there for the current effort. When Unix-client implementation is explicitly
|
||||
started later, continue with Phase 7 (Linux supervisor/cgroup and client parity),
|
||||
then the remaining Phase 8 Unix operational/release gates to complete v1.
|
||||
Stop there for v1. Any Unix-client implementation is a separately authorized
|
||||
post-v1 effort and does not change this milestone's completion criteria.
|
||||
|
||||
Do not merge a later vertical slice by stubbing a durability/safety invariant.
|
||||
For example: foreground mode may wait on a durable background command, but must
|
||||
@@ -2701,12 +2698,9 @@ not bypass persistence; client output may be truncated under the documented
|
||||
caps, but must never block a child pipe; and a reconnection may replay work,
|
||||
but may never re-execute an already accepted UUID.
|
||||
|
||||
The current Windows-client milestone is releasable only after Phases 0–6 plus its
|
||||
applicable Phase 8 packaging/security gates pass on native Windows and a clean
|
||||
Linux server environment. Windows support cannot be marked optional or replaced
|
||||
by cross-compilation-only checks. Stop the current implementation effort at that
|
||||
milestone; Phase 7 remains deferred until explicitly started later. Full v1 is
|
||||
ready only after that later Linux client also passes the common protocol/
|
||||
durability suite and Linux-specific cgroup/process tests. Every release must
|
||||
The Linux-server/Windows-client v1 milestone is releasable only after Phases 0–6
|
||||
plus its applicable Phase 8 packaging/security gates pass on native Windows and
|
||||
a clean Linux server environment. Windows support cannot be marked optional or
|
||||
replaced by cross-compilation-only checks. Every release must
|
||||
conspicuously document self-reported identity, the elevated Windows execution
|
||||
authority, and unauthenticated optional JSON-RPC.
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# RVBox Linux-server operations runbook
|
||||
|
||||
This runbook covers the v1 Linux server and native Windows clients. It does not
|
||||
describe a Unix-like client, which is outside v1.
|
||||
|
||||
## Deploy and verify
|
||||
|
||||
Use either the checked-in Compose deployment or the systemd unit, never both
|
||||
for the same server data directory. Start from the annotated
|
||||
[`server.toml`](examples/server.toml) and retain `json_rpc.enabled = false`
|
||||
unless performing loopback-only debugging.
|
||||
|
||||
For Compose, follow the setup in
|
||||
[`deploy/production/README.md`](../deploy/production/README.md), set a pinned
|
||||
`RVBOX_SERVER_IMAGE`, `RVBOX_TLS_CERT`, and `RVBOX_TLS_KEY`, then run:
|
||||
|
||||
```sh
|
||||
docker compose -f deploy/production/compose.yaml config
|
||||
docker compose -f deploy/production/compose.yaml up -d
|
||||
docker compose -f deploy/production/compose.yaml ps
|
||||
```
|
||||
|
||||
The first command must succeed before any containers start. `/livez` shows that
|
||||
the process is up; `/readyz` becomes successful only after durable recovery.
|
||||
The public endpoint accepts only `wss://HOST/v1/agent`. Do not publish port
|
||||
6900 or add a proxy route for JSON-RPC.
|
||||
|
||||
For systemd, create the `rvbox` service account, install the binary and
|
||||
`deploy/systemd/rvbox-server.service`, place a root:`rvbox` owned `0640`
|
||||
`/etc/rvbox/server.toml`, then run `systemctl daemon-reload` and
|
||||
`systemctl enable --now rvbox-server`. The unit performs `--check-config`
|
||||
before every start.
|
||||
|
||||
## Backup and restore
|
||||
|
||||
Stop dispatch before copying data: stop the server gracefully, confirm it is
|
||||
down, then copy the entire configured `server.data_dir` tree. That tree contains
|
||||
SQLite, WAL/SHM state, retained command segments, audit segments, and incidents;
|
||||
backing up SQLite alone is incomplete.
|
||||
|
||||
To restore, keep the server stopped, move the failed directory aside without
|
||||
deleting it, restore the complete backup with ownership restricted to the
|
||||
server account, and run `rvbox-server --check-config` followed by a normal
|
||||
start. Keep readiness under observation. A failed recovery leaves readiness
|
||||
false and records an incident; do not delete segments to force readiness.
|
||||
|
||||
## Upgrade and rollback
|
||||
|
||||
1. Record the running image/binary digest and `rvc stat` output.
|
||||
2. Stop the server gracefully so no new dispatch is accepted.
|
||||
3. Take a full data-directory backup as above.
|
||||
4. Install the new image/binary without changing configuration, and run
|
||||
`--check-config` before starting it.
|
||||
5. Start, wait for `/readyz`, and verify `rvc stat` plus one known client
|
||||
reconnect.
|
||||
6. If readiness or storage recovery fails, stop, restore the prior binary/image
|
||||
and full data directory, then start the known-good version. Preserve logs
|
||||
and the failed copy for diagnosis.
|
||||
|
||||
## Common incidents
|
||||
|
||||
- **No client / stale session:** verify nginx has WebSocket `101` entries for
|
||||
`/v1/agent`, server readiness is true, and the Windows service is running.
|
||||
Use `rvc stat CLIENT_ID`; do not restart the client merely to clear history.
|
||||
- **Spool or storage full:** `CAPACITY_EXHAUSTED` is intentional admission
|
||||
protection. Inspect command retention and free space, allow terminal-age or
|
||||
quota rotation to reclaim eligible data, or enlarge the owned filesystem.
|
||||
Never manually remove live SQLite/WAL/segment files.
|
||||
- **Output truncated:** query command status and output history for its explicit
|
||||
loss/truncation markers. The command may still have completed correctly.
|
||||
- **Server restart / dirty health:** wait for readiness and inspect the
|
||||
incident record. Use the documented repair/acknowledgement controls only
|
||||
after preserving evidence; a late client report is authoritative and is not
|
||||
rewritten to match an earlier provisional state.
|
||||
@@ -4,9 +4,9 @@ Daemon configuration uses strict TOML as specified in
|
||||
[`configuration.md`](configuration.md); the annotated examples contain every
|
||||
v1 knob and default.
|
||||
|
||||
The current implementation scope is the Linux server plus Windows client. The
|
||||
Unix-like client remains part of complete v1 but is deferred and must not be
|
||||
implemented yet. Its section below preserves the agreed future v1 contract; the
|
||||
The v1 implementation scope is the Linux server plus Windows client. A
|
||||
Unix-like client is post-v1 work and must not be implemented as part of this
|
||||
milestone. Its section below is retained only as future design material; the
|
||||
document order does not authorize or reprioritize that work.
|
||||
|
||||
## Unix-like clients
|
||||
|
||||
@@ -99,6 +99,8 @@ respective durability or wire boundary:
|
||||
```sh
|
||||
scripts/test-env doctor
|
||||
scripts/test-integration --suite sample --run-id my-sample
|
||||
scripts/test-integration --list
|
||||
scripts/test-integration --suite store --case '^TestStore' --run-id store-one-case
|
||||
scripts/test-env status --run-id my-sample
|
||||
scripts/test-env collect --run-id my-sample
|
||||
scripts/test-env reset --run-id my-sample
|
||||
@@ -120,6 +122,8 @@ scripts/test-env reset --run-id session-smoke
|
||||
scripts/test-env purge --run-id session-smoke
|
||||
|
||||
scripts/test-e2e --scenario smoke --run-id e2e-smoke
|
||||
scripts/test-e2e --list
|
||||
scripts/test-e2e --scenario smoke --case '^Test' --run-id e2e-one-case
|
||||
scripts/test-env status --run-id e2e-smoke
|
||||
scripts/test-env recover --run-id e2e-smoke
|
||||
scripts/test-e2e --scenario smoke --run-id e2e-smoke --resume
|
||||
|
||||
Reference in New Issue
Block a user