# 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.