mirror of
https://github.com/UNITRONIX/BetterDesk.git
synced 2026-09-10 09:35:39 +00:00
UNITRONIX
6677cd6132
Refs #371 Thanks: INSOLVE (Honorary); Marco Jakobs (@jacotec); MyNameisStitch (@MyNameisStitch); Redspin (@playerumpknow)
102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
# BetterDesk installer contract
|
|
|
|
This document defines the supported lifecycle contract for BetterDesk
|
|
installation paths. The contract is intentionally platform-neutral; each
|
|
installer may use native service tooling, but must provide the same observable
|
|
result.
|
|
|
|
## Supported entry points
|
|
|
|
| Path | Runtime | Scope |
|
|
|---|---|---|
|
|
| `install.sh` | Linux | Docker quick install, native bootstrap, Docker rescue/uninstall |
|
|
| `betterdesk.sh` | Linux | Native server and console lifecycle manager |
|
|
| `betterdesk.ps1` | Windows | Native server and console lifecycle manager |
|
|
| `betterdesk-docker.sh` | Linux + Docker | Compose lifecycle, rescue, migration and diagnostics |
|
|
| `betterdesk-agent/install/install.sh` | Linux | Native agent install/uninstall |
|
|
| `betterdesk-agent/install/install.ps1` | Windows | Native agent install/uninstall |
|
|
| `betterdesk-support-agent/install.go` | Linux, Windows, macOS | Support-agent self-install/uninstall |
|
|
| `scripts/installer-protocol-check.js` | Linux, Windows, Docker | Shared HTTP/HTTPS, redirect, SAN and TCP verification |
|
|
|
|
`install.sh` embeds `BETTERDESK_INSTALLER_CHANNEL` so a one-line install from
|
|
`.../dev/install.sh` clones `dev` and `.../main/install.sh` clones `main`.
|
|
When releasing this file onto `main`, set that channel to `main` (operators can
|
|
still override with `--branch` / `BETTERDESK_BRANCH`).
|
|
|
|
The `build-betterdesk.*` wrappers and `betterdesk-server/deploy.sh` are
|
|
development or migration tools. They must not silently replace the official
|
|
installer lifecycle or be presented as the primary production installation
|
|
path.
|
|
|
|
## Lifecycle guarantees
|
|
|
|
Every official installer must implement or explicitly reject these operations
|
|
with a clear message and non-zero exit code:
|
|
|
|
1. **Preflight** — verify platform, privilege, dependencies, writable paths,
|
|
available disk space, required ports, network access and compatible version.
|
|
2. **Fresh install** — create only the required directories and services,
|
|
preserve operator-supplied secrets, initialize the selected database and
|
|
finish with a health check.
|
|
3. **Update** — download a complete, validated source/image, preserve runtime
|
|
state, apply migrations, deploy writable binaries atomically, restart
|
|
affected services and write the commit/version marker only after
|
|
verification. Root-owned Linux systemd units and Go binaries require the
|
|
documented root maintenance/deploy step; the panel must not sudo mutable
|
|
repository scripts.
|
|
4. **Repair** — restore missing binaries, dependencies, permissions, service
|
|
definitions and TLS material without requiring legacy RustDesk artifacts for
|
|
the Go deployment.
|
|
5. **Validate/diagnose** — report actionable errors and warnings without
|
|
changing data in read-only diagnostic mode.
|
|
6. **Backup and restore** — include the database, keys, `.env` and other
|
|
runtime credentials; restore must validate the backup manifest before
|
|
writing files.
|
|
7. **Uninstall** — stop and remove all service variants created by the
|
|
installer. Default uninstall preserves data; an explicit purge may remove
|
|
data, volumes and generated firewall rules.
|
|
8. **Reinstall** — be safe after a non-purge uninstall and preserve state when
|
|
the operator chooses to keep it.
|
|
|
|
## Completion criteria
|
|
|
|
An operation is successful only when all of the following are true:
|
|
|
|
- the process exits with code `0`;
|
|
- the installed product version and update SHA describe the deployed code;
|
|
- required services are running under the intended account;
|
|
- configured HTTP/API/TLS health checks pass;
|
|
- database, key material and operator configuration remain usable;
|
|
- a repeated invocation does not duplicate services, rules, files or data;
|
|
- failures leave the previous binary/configuration usable or provide a
|
|
verified rollback path.
|
|
|
|
An update must not advance `.update_sha`, `.agent_source_sha` or clear a
|
|
previous failure marker while a critical source, binary, migration or service
|
|
step is incomplete.
|
|
|
|
## Platform-specific endpoints
|
|
|
|
- Native Linux and Windows: panel health on the configured HTTP/HTTPS port,
|
|
Go API on `21114`, client API on `21121`, and signal/relay listeners as
|
|
configured.
|
|
- Docker single layout: Go/client API on `21121` and console on `5000`.
|
|
- Docker split layout: Go API on `21114` and console on `5000`.
|
|
|
|
The protocol verification must distinguish a successful TCP listener from a
|
|
successful HTTP response and, for HTTPS, a valid certificate/SAN and TLS
|
|
handshake.
|
|
|
|
## Safety rules
|
|
|
|
- Never overwrite existing `.env` secrets with template values.
|
|
- Never remove database, keys, volumes or firewall rules without explicit
|
|
confirmation or a purge flag.
|
|
- Never require `hbbs`, `hbbr` or `hbbs-patch-v2` to repair a Go
|
|
`betterdesk-server` installation.
|
|
- Never grant sudoers permission to execute a mutable repository script as
|
|
root. Linux panel restarts use only the fixed root-owned
|
|
`betterdesk-privileged-update.js` broker with an allowlisted action set.
|
|
- Never report success after a partial update merely because the process
|
|
restarted.
|