docs: plan HTTPS peers and source install

docs/source-installation.md

@@ -0,0 +1,89 @@
+# SSH Source Installation Plan
+
+## Status
+
+Planned. The current Go installer can upload a binary or deploy an immutable
+Docker image over SSH. It does not yet install build prerequisites, download Go,
+clone the public repository, or build remotely. Existing tests are unit tests;
+there is no live OpenSSH-container installation test.
+
+## Initial Platform Scope
+
+The first source installer supports Linux and is validated on Alpine, Ubuntu,
+and Arch Linux containers. CentOS-family support follows after its package and
+service differences are implemented. Windows and macOS remain later platform
+work despite the worker being written in Go.
+
+Use `reg.rsxx.ru` image mirrors where available. Tests must not depend on Docker
+Hub when a local mirror exists.
+
+## Source Install Flow
+
+The Go CLI connects through `golang.org/x/crypto/ssh` using existing key,
+passphrase, password, sudo-password, known-hosts, and pinned-fingerprint support.
+It then:
+
+1. detects supported OS, architecture, package manager, init system, and
+   privilege path;
+2. installs only required packages (`git`, CA certificates, download/archive
+   tools); it does not install `build-essential` or a C compiler unless a
+   detected dependency requires CGO;
+3. downloads the pinned Go 1.26 toolchain for the detected architecture and
+   verifies the published SHA-256;
+4. clones `https://rocketgit.ru/rsmon/worker.git` or updates an existing clone;
+5. checks out branch `main` and records the resolved commit;
+6. builds a reproducible worker binary with the repository build flags;
+7. atomically installs the binary, validated environment, data directory, and
+   service definition;
+8. starts the service and verifies process status and `/healthz`.
+
+Repository, branch, Go version, checksum source, build directory, and Go module
+proxy may be configurable, but production output records their resolved values.
+The default repository is publicly readable and requires no source credential.
+
+## Docker OpenSSH Test Harness
+
+Adapt the real-network pattern from `/data/_swap/sshkeymanager`: start an
+OpenSSH container, wait for SSH readiness, connect with the Go installer, and
+tear the environment down reliably. Do not mock SSH command execution in the
+acceptance test.
+
+Provide images/fixtures for:
+
+- Ubuntu with apt and systemd-compatible service testing where practical;
+- Alpine with apk/OpenRC or a clearly separated no-service build/install gate;
+- Arch with pacman and its service behavior.
+
+Each clean target begins without Go or the worker source. The test asserts
+package installation, verified Go version, clone branch/resolved commit, build,
+atomic config permissions, running service where supported, and HTTP liveness.
+
+## Idempotency And Security
+
+- A second run updates/fetches safely and leaves one active service.
+- Wrong host fingerprints fail before remote mutation.
+- Tokens/passwords come from files or stdin-safe channels and never appear in
+  command arguments, logs, source checkout, or shell history.
+- Remote temporary files are removed on success and failure.
+- Failed builds do not replace a working binary or service definition.
+- Package-manager and download failures return bounded actionable errors.
+- The installer verifies Go tarball checksum before extraction.
+
+## Implementation Work Packages
+
+1. Add reusable Docker/OpenSSH harness and distro fixtures.
+2. Add pure distro/toolchain/source-install script planning and unit tests.
+3. Execute source installation through the existing SSH transport.
+4. Add atomic build/install, idempotency, and failure rollback.
+5. Add Alpine, Ubuntu, and Arch network E2E tests to CI.
+6. Add CentOS-family support.
+7. Plan native Windows service and macOS launchd installers separately.
+
+## Acceptance Gates
+
+- All three initial Linux images install from a clean state through OpenSSH.
+- The built worker reports the expected version/commit and serves `/healthz`.
+- Re-running the installer succeeds without duplicate services or leaked files.
+- Host-key, checksum, clone, build, and service-start failure tests preserve the
+  previous installation.
+- CI uses approved registry mirrors and cleans every test container/network.