Merge pull request #4039 from telepresenceio/thallgren/system-service-docs

Add installer documentation and changelog entries for v2.27.0

Author: thallgren

CHANGELOG.yml

@@ -24,6 +24,34 @@
 #
 # For older changes, see CHANGELOG.OLD.md
 items:
+  - version: 2.27.0
+    date: (TBD)
+    notes:
+      - type: feature
+        title: Add macOS package installer with root daemon as a system service
+        body: >-
+          A new macOS package installer (.pkg) is now available that installs Telepresence with the root daemon
+          configured as a launchd service. This eliminates the need for elevated privileges when using Telepresence,
+          as the daemon starts automatically at boot and runs in the background. Available for both Intel (amd64)
+          and Apple Silicon (arm64) Macs.
+        docs: install/client
+      - type: feature
+        title: Add Linux package installers with root daemon as a system service
+        body: >-
+          New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) are now available that
+          install Telepresence with the root daemon configured as a systemd service. This eliminates the need for
+          elevated privileges when using Telepresence, as the service is enabled and started automatically during
+          installation. Available for both amd64 and arm64 architectures.
+        docs: install/client
+      - type: feature
+        title: Add Windows installer with root daemon as a system service
+        body: >-
+          A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured
+          as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support,
+          adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates
+          the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only
+          due to dependency constraints.
+        docs: install/client
   - version: 2.26.0
     date: 2026-01-23
     notes:

CLAUDE.md

@@ -78,8 +78,13 @@ make generate
 
 # Regenerate protobuf files only
 make protoc
+
+# Regenerate documentation files (after changing CHANGELOG.yml)
+make docs-files
 ```
 
+**Important:** After modifying `CHANGELOG.yml`, always run `make docs-files` to regenerate the documentation files (`docs/release-notes.md`, `docs/release-notes.mdx`, `docs/variables.yml`).
+
 ## Architecture
 
 ### Main Components
@@ -207,3 +212,10 @@ Version formats:
 - `vX.Y.Z-test.N` - Test release (pre-release)
 - `vX.Y.Z-rc.N` - Release candidate (pre-release)
 - `vX.Y.Z` - GA release (marked as latest, triggers Homebrew update)
+
+### Changelog
+
+When adding entries to `CHANGELOG.yml` for an upcoming release:
+- Use `date: (TBD)` for unreleased versions
+- The `make prepare-release` command will set the actual date when `TELEPRESENCE_VERSION` is a GA version (e.g., `v2.27.0`)
+- After modifying `CHANGELOG.yml`, run `make docs-files` to regenerate documentation

docs/install/client.md

@@ -14,12 +14,22 @@ Install the Telepresence client on your workstation by running the commands belo
 <Platform.TabGroup>
 <Platform.MacOSTab>
 
-## Install with brew:
+## Install with brew (Recommended):
 ```shell
 brew install telepresenceio/telepresence/telepresence-oss
 ```
 
-## OR download the binary for your platform
+## OR install using the package installer
+
+The package installer includes the root daemon as a system service via launchd, eliminating the need for elevated privileges when using Telepresence.
+
+Download the appropriate installer for your architecture:
+- [telepresence-darwin-amd64.pkg](https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-amd64.pkg) (Intel Macs)
+- [telepresence-darwin-arm64.pkg](https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-darwin-arm64.pkg) (Apple Silicon Macs)
+
+Double-click the downloaded `.pkg` file and follow the installation prompts.
+
+## OR download the binary manually
 
 ### AMD (Intel) Macs
 
@@ -48,6 +58,38 @@ sudo chmod a+x /usr/local/bin/telepresence
 </Platform.MacOSTab>
 <Platform.GNULinuxTab>
 
+## Install using package manager (Recommended)
+
+The package installers include the root daemon as a systemd service, eliminating the need for elevated privileges when using Telepresence.
+
+### Debian/Ubuntu (.deb)
+
+```shell
+# Download the latest .deb package
+# AMD64
+curl -fLO https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-amd64.deb
+# ARM64
+curl -fLO https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-arm64.deb
+
+# Install the package
+sudo apt install ./telepresence-linux-*.deb
+```
+
+### Fedora/RHEL (.rpm)
+
+```shell
+# Download the latest .rpm package
+# AMD64
+curl -fLO https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-amd64.rpm
+# ARM64
+curl -fLO https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-linux-arm64.rpm
+
+# Install the package
+sudo dnf install ./telepresence-linux-*.rpm
+```
+
+## OR download the binary manually
+
 ```shell
 # 1. Download the latest binary (~95 MB):
 # AMD
@@ -63,6 +105,18 @@ sudo chmod a+x /usr/local/bin/telepresence
 </Platform.GNULinuxTab>
 <Platform.WindowsTab>
 
+## Install using the setup installer (Recommended)
+
+The setup installer includes the root daemon as a Windows service, eliminating the need for elevated privileges when using Telepresence. It also bundles WinFSP and SSHFS-Win for volume mount support.
+
+Download and run the installer:
+- [telepresence-windows-amd64-setup.exe](https://github.com/telepresenceio/telepresence/releases/latest/download/telepresence-windows-amd64-setup.exe)
+
+> [!NOTE]
+> The Windows installer is currently only available for AMD64. For ARM64, use the manual installation method below.
+
+## OR install manually using PowerShell
+
 We've developed a Powershell script to simplify the process of installing telepresence. Here are the commands you can execute:
 
 ### Windows AMD64

docs/reference/cli/telepresence_genyaml_config.md

@@ -17,7 +17,7 @@ Generate YAML for the agent's entry in the telepresence-agents configmap. See ge
 
 ### Flags:
 ```
-      --agent-image string         The qualified name of the agent image (default "ghcr.io/telepresenceio/tel2:2.26.1")
+      --agent-image string         The qualified name of the agent image (default "ghcr.io/telepresenceio/tel2:2.27.0")
       --agent-port uint16          The port number you wish the agent to listen on. (default 9900)
   -h, --help                       help for config
   -i, --input string               Path to the yaml containing the workload definition (i.e. Deployment, StatefulSet, etc). Pass '-' for stdin.. Mutually exclusive to --workload

docs/release-notes.md

@@ -1,6 +1,25 @@
 
 [comment]: # (Code generated by relnotesgen. DO NOT EDIT.)
 # <img src="images/logo.png" height="64px"/> Telepresence Release Notes
+## Version 2.27.0
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Add macOS package installer with root daemon as a system service](install/client)</div></div>
+<div style="margin-left: 15px">
+
+A new macOS package installer (.pkg) is now available that installs Telepresence with the root daemon configured as a launchd service. This eliminates the need for elevated privileges when using Telepresence, as the daemon starts automatically at boot and runs in the background. Available for both Intel (amd64) and Apple Silicon (arm64) Macs.
+</div>
+
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Add Linux package installers with root daemon as a system service](install/client)</div></div>
+<div style="margin-left: 15px">
+
+New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) are now available that install Telepresence with the root daemon configured as a systemd service. This eliminates the need for elevated privileges when using Telepresence, as the service is enabled and started automatically during installation. Available for both amd64 and arm64 architectures.
+</div>
+
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Add Windows installer with root daemon as a system service](install/client)</div></div>
+<div style="margin-left: 15px">
+
+A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support, adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only due to dependency constraints.
+</div>
+
 ## Version 2.26.0 <span style="font-size: 16px;">(January 23)</span>
 ## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Add ability for cluster admins to revoke other users' intercepts.](reference/engagements/conflicts)</div></div>
 <div style="margin-left: 15px">

docs/release-notes.mdx

@@ -7,6 +7,25 @@ import { Note, Title, Body } from '@site/src/components/ReleaseNotes'
 [comment]: # (Code generated by relnotesgen. DO NOT EDIT.)
 
 # Telepresence Release Notes
+## Version 2.27.0
+<Note>
+	<Title type="feature" docs="install/client">Add macOS package installer with root daemon as a system service</Title>
+	<Body>
+A new macOS package installer (.pkg) is now available that installs Telepresence with the root daemon configured as a launchd service. This eliminates the need for elevated privileges when using Telepresence, as the daemon starts automatically at boot and runs in the background. Available for both Intel (amd64) and Apple Silicon (arm64) Macs.
+  </Body>
+</Note>
+<Note>
+	<Title type="feature" docs="install/client">Add Linux package installers with root daemon as a system service</Title>
+	<Body>
+New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) are now available that install Telepresence with the root daemon configured as a systemd service. This eliminates the need for elevated privileges when using Telepresence, as the service is enabled and started automatically during installation. Available for both amd64 and arm64 architectures.
+  </Body>
+</Note>
+<Note>
+	<Title type="feature" docs="install/client">Add Windows installer with root daemon as a system service</Title>
+	<Body>
+A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support, adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only due to dependency constraints.
+  </Body>
+</Note>
 ## Version 2.26.0 <span style={{fontSize:'16px'}}>(January 23)</span>
 <Note>
 	<Title type="feature" docs="reference/engagements/conflicts">Add ability for cluster admins to revoke other users' intercepts.</Title>

docs/variables.yml

@@ -1,2 +1,2 @@
-version: "2.26.0"
-dlVersion: "v2.26.0"
+version: "2.27.0"
+dlVersion: "v2.27.0"