Files
tsunagi/dist/arch/README.md
T
Aleksandr Bogomiakov 91227afbac Publish GitHub releases to the Arch package repository
After release assets have all uploaded, dispatch the exact repository and tag to
house-of-vanity/arch_repo using the ARCH_REPO_TOKEN Actions secret. Keep this in a
separate job so notification failures can be retried without rebuilding a release;
a missing token fails with an actionable message. Document repository setup,
installation, publication status and recovery.

Fix Arch version ordering discovered during integration: 0.1.0_rc.10 sorts above
0.1.0 in pacman. Attach prerelease suffixes directly and add epoch 1 so existing
installations can migrate and later upgrade to stable. Keep the epoch out of
filenames and align both GitHub and Gitea packaging filenames. Git tags and
application versions are unchanged. Add real packaging/vercmp checks.

Validation: Arch packaging and version-order checks passed in an Arch Linux
Docker container, including CLI and GUI packages. cargo fmt --all -- --check,
cargo clippy --locked --workspace --all-targets -- -D warnings and cargo test
--locked --workspace --all-targets passed on macOS (default ignored tests stayed
ignored). GitHub release workflow passed actionlint. Running GitHub actionlint
on the Gitea workflow only reported its deliberately retained v3 artifact actions,
which are supported by Gitea but retired on GitHub. git diff --check passed.
2026-11-16 14:40:12 +00:00

92 lines
3.4 KiB
Markdown

# Running tsunagi on Arch Linux
Install the package built for your architecture:
```sh
sudo pacman -U tsunagi-*-x86_64.pkg.tar.zst
```
It drops a static, dependency-free binary at `/usr/bin/tsng`, a systemd
service, and a polkit rule, and creates a dedicated system user `tsunagi` the
service runs as.
Start it:
```sh
sudo systemctl enable --now tsunagi
```
Control it with `sudo` (the agent's control socket is private to the service
user; `sudo` reaches it with no extra flags, because the CLI finds the running
service's socket at `/run/tsunagi/agent.sock`):
```sh
sudo tsng status
sudo tsng join -n <network-name> -s <tsn1…secret>
```
## How it runs
The service runs as the unprivileged `tsunagi` user with just two capabilities
(`CAP_NET_ADMIN`, `CAP_NET_BIND_SERVICE`) granted by systemd — no root. systemd
creates and owns its directories:
| what | path |
|---|---|
| state | `/var/lib/tsunagi` |
| cache | `/var/cache/tsunagi` |
| control socket | `/run/tsunagi/agent.sock` |
Installing the package enables and starts the service, and adds the user who ran
pacman to the `tsunagi` group (log out and in again for it to apply). The
control socket is open to that group, so members can run `tsng status`, the
CLI and the tray GUI without sudo; anyone else adds themselves with `sudo
usermod -aG tsunagi "$USER"`. The group also lets its members configure
systemd-resolved for the overlay zones through the polkit rule.
The GUI package depends on `gtk3`, `libayatana-appindicator` (the tray icon),
and the usual windowing libraries.
## Removal
```sh
sudo pacman -R tsunagi
```
stops and disables the service. The `tsunagi` user and `/var/lib/tsunagi` are
left in place; remove them by hand if you want them gone.
## Automatic package repository
GitHub releases are also published to the Arch repository after all release
assets have uploaded. Add this to `/etc/pacman.conf`:
```ini
[btwiusearch.net]
SigLevel = Optional TrustAll
Server = https://btwiusearch.net/arch_repo/$arch/
```
Install with `sudo pacman -Syu tsunagi`, or `sudo pacman -Syu tsunagi-gui` for
the x86_64 desktop variant. Subsequent versions arrive through `pacman -Syu`.
Prerelease tags are included. ARM packages are provided for `aarch64` and `armv7h`.
Maintainers must set the `ARCH_REPO_TOKEN` Actions secret to a fine-grained token
with **Contents: Read and write** permission on `house-of-vanity/arch_repo` only.
The separate notification job fails clearly if the secret is missing; the built
release remains available. Once the secret is configured, rerun the failed job.
A successful notification schedules publication; check the
[Arch repository workflow](https://github.com/house-of-vanity/arch_repo/actions/workflows/update_repo.yaml)
for the deployment result. A manual run there can import an existing tag without
rebuilding it. Repository setup and recovery are documented in
[arch_repo](https://github.com/house-of-vanity/arch_repo#github-setup).
Arch package versions use epoch `1` and spell prereleases as `0.1.0rc.33`, so
pacman upgrades correctly from RC to stable. The epoch also migrates packages
installed using the former `0.1.0_rc.33` spelling. It appears in pacman's version
metadata, not in archive filenames. This does not change the Git tag or the
application's version string.
Package/version checks can be run on Arch Linux with `python`, `libarchive`, and
`zstd` installed: `bash dist/arch/test-pkg.sh`.