# Linux Platform Guide

Linux keeps the current Go application with Web UI by default and TUI/CLI
modes available. Release targets support amd64 and arm64 without imposing a
WebKit/GTK runtime dependency.

## Build

```bash
make build-linux-amd64
make build-linux-arm64
# or both
make build-linux
```

Outputs:

- `dist/mpv-manager-linux-amd64`
- `dist/mpv-manager-linux-arm64`

Release builds are CGO-free. Verify identity with:

```bash
./dist/mpv-manager-linux-amd64 --version --json
```

## Run modes

```bash
./mpv-manager
./mpv-manager tui
./mpv-manager cli --method mpv-binary
./mpv-manager --debug
```

The Web host listens on `127.0.0.1:6787` by default. Only validated loopback
addresses are accepted.

## Distribution support

The installer has package-manager paths for Debian/Ubuntu (`apt`), Fedora/RHEL
(`dnf`), Arch (`pacman`), and openSUSE (`zypper`), plus Flatpak methods where
applicable. Package probes run with `LC_ALL=C` so parsing does not depend on the
desktop locale.

Common diagnostic commands:

```bash
cat /etc/os-release
command -v apt dnf pacman zypper flatpak
./mpv-manager --debug
```

Do not let the raw self-updater overwrite a distro-owned executable. Package
recipes must link with `SelfUpdateDisabled=true`; the UI then displays update
availability without offering in-place replacement.

The Makefile's `build-aur` target applies this policy for the Arch package
artifact.

## Paths and permissions

Configuration follows the application's resolved MPV config directory,
honoring a supported custom configuration/install path. Use user-writable
portable locations for self-updating binaries. System locations such as
`/usr/bin` or `/opt` require package ownership or explicit privilege and are
not safe implicit self-update targets.

Sudo credentials are stored through the freedesktop Secret Service login or
default collection. A functioning desktop secret service/keyring is required
for secure persistence; no weak file fallback is used.

GPU discovery uses available platform tools and produces conservative fallback
chains when exact hardware cannot be identified. Use `--debug` and record the
reported adapter/model when adding GPU database coverage.

## v1.3 native update gate

Test amd64 and arm64 where available:

- N-2 and N-1 portable updates;
- user-writable and unwritable destinations;
- wrong/truncated/oversized downloads and identity mismatches;
- interrupted swap, rollback, and stale-file cleanup;
- concurrent update attempts and process handoff;
- Web restart notice and graceful exit 0;
- TUI relaunch and failure retry;
- `apt`, `dnf`, `pacman`, `zypper`, and other packaged builds refusing raw
  self-update.

As of 2026-08-30, the development-only synthetic-version qualifier passes
commit, forced partial rollback, lock contention, healthy relaunch, and failed
health-check rollback on CachyOS Linux amd64. Historical releases, arm64,
unwritable destinations, package-owner policy, and the Web lifecycle remain
open release gates.

AppImage is not a documented release artifact in the current pipeline. Do not
claim AppImage-aware update support until a packaged artifact and native gate
exist.

---

See also: [Build and Deployment](../BUILD_DEPLOYMENT.md) · [Testing](../TESTING.md) · [Troubleshooting](../TROUBLESHOOTING.md)