Skip to content

feat: add AUR packaging for Arch Linux#6314

Merged
houko merged 2 commits into
librefang:mainfrom
pavver:feat/aur-packaging-files
Jun 26, 2026
Merged

feat: add AUR packaging for Arch Linux#6314
houko merged 2 commits into
librefang:mainfrom
pavver:feat/aur-packaging-files

Conversation

@pavver

@pavver pavver commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Summary

#6313

This PR adds upstream-maintained AUR packaging sources for Arch Linux users.

Added packages:

  • librefang-bin: CLI/daemon package from the GitHub Release Linux tarball.
  • librefang-desktop-bin: native Tauri desktop package from the GitHub Release .deb.
  • librefang-docker: Docker-backed service/helper package pinned to the release image.

The package sources live under:

packaging/aur/

Changes

  • Added PKGBUILD and .SRCINFO for librefang-bin.
  • Added PKGBUILD and .SRCINFO for librefang-desktop-bin.
  • Added PKGBUILD and .SRCINFO for librefang-docker.
  • Added systemd/sysusers/tmpfiles support for the native daemon package.
  • Added /etc/librefang/env for native service environment variables.
  • Added Docker runner helper and librefang-docker.service.
  • Added AUR packaging README with verification and update notes.
  • Added .gitignore for local makepkg outputs.

Package Details

librefang-bin installs:

  • /usr/bin/librefang
  • /usr/bin/librefang-sidecar-telegram
  • /usr/lib/systemd/system/librefang.service
  • /usr/lib/sysusers.d/librefang.conf
  • /usr/lib/tmpfiles.d/librefang.conf
  • /etc/librefang/env

The native service uses:

LIBREFANG_HOME=/var/lib/librefang
WorkingDirectory=/var/lib/librefang

librefang-desktop-bin installs:

  • /usr/bin/librefang-desktop
  • /usr/share/applications/LibreFang.desktop
  • hicolor app icons

This adds the native desktop app to desktop environment application menus.

librefang-docker installs:

  • /usr/bin/librefang-docker
  • /usr/lib/systemd/system/librefang-docker.service
  • /etc/librefang/docker.env

The Docker package pins:

ghcr.io/librefang/librefang:2026.6.24-beta.23

Maintainer Action Required

This PR adds the package sources only.
Maintainers still need to create or approve official AUR repositories:

  • librefang-bin
  • librefang-desktop-bin
  • librefang-docker

For automatic updates on each release, maintainers need to configure:

  • A dedicated AUR account or maintainer-owned AUR SSH key.
  • A GitHub Actions secret such as AUR_SSH_PRIVATE_KEY.
  • A release workflow job that updates PKGBUILD, regenerates .SRCINFO, commits, and pushes to the AUR git repositories.

Until that automation exists, these files can be copied manually into the AUR package repositories for each release.

Verification

Verified locally on Arch with makepkg.

Commands run for all three packages:

makepkg -f
makepkg --printsrcinfo | diff -u .SRCINFO -

Package metadata and file lists were checked with:

pacman -Qp packaging/aur/librefang-bin/librefang-bin-2026.6.24_beta.23-1-x86_64.pkg.tar.zst \
  packaging/aur/librefang-desktop-bin/librefang-desktop-bin-2026.6.24_beta.23-1-x86_64.pkg.tar.zst \
  packaging/aur/librefang-docker/librefang-docker-2026.6.24_beta.23-1-any.pkg.tar.zst

pacman -Qlp packaging/aur/librefang-bin/librefang-bin-2026.6.24_beta.23-1-x86_64.pkg.tar.zst \
  packaging/aur/librefang-desktop-bin/librefang-desktop-bin-2026.6.24_beta.23-1-x86_64.pkg.tar.zst \
  packaging/aur/librefang-docker/librefang-docker-2026.6.24_beta.23-1-any.pkg.tar.zst

Runtime checks:

packaging/aur/librefang-bin/pkg/librefang-bin/usr/bin/librefang --version
packaging/aur/librefang-desktop-bin/pkg/librefang-desktop-bin/usr/bin/librefang-desktop --help
LIBREFANG_DOCKER_ENV=packaging/aur/librefang-docker/librefang-docker.env \
  packaging/aur/librefang-docker/librefang-docker --help

Docker image check:

docker run --rm --network none \
  ghcr.io/librefang/librefang:2026.6.24-beta.23 \
  librefang --version

The packages were also installed locally with pacman -U by a user with sudo access.
The app started and worked.

Documentation Follow-up

After maintainers create and publish the official AUR repositories, update the installation documentation with Arch commands:

yay -S librefang-bin
yay -S librefang-desktop-bin
yay -S librefang-docker

The docs should clarify:

  • Use librefang-bin for CLI, daemon, API, and browser dashboard.
  • Use librefang-desktop-bin for the native desktop app.
  • Use librefang-docker for container-based service deployments.

Out of Scope

  • CI automation that pushes to AUR on every release.
  • Source-build AUR packages such as librefang or librefang-git.
  • Publishing the AUR repositories themselves.

@github-actions github-actions Bot added the size/L 250-999 lines changed label Jun 24, 2026
@pavver pavver changed the title Add AUR packaging for Arch Linux feat: add AUR packaging for Arch Linux Jun 24, 2026

@houko houko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One issue found: the librefang-desktop-bin PKGBUILD hardcodes data.tar.gz when extracting the .deb, which will silently break for any release whose Debian package uses data.tar.xz or data.tar.zst (both are common from Tauri). See the inline comment on line 28 for the safer glob-based pattern.

The other two packages (librefang-bin and librefang-docker) look correct.


Generated by Claude Code

)

package() {
bsdtar -xf "$srcdir/data.tar.gz" -C "$pkgdir"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bsdtar -xf "$srcdir/data.tar.gz" assumes the inner data archive inside the .deb uses gzip compression, but Tauri/Debian packages commonly ship data.tar.xz or data.tar.zst.
If the actual .deb for this release uses a different compression, makepkg will fail with "cannot open: No such file or directory".
The safer pattern used in most AUR .deb PKGBUILDs is:

package() {
  bsdtar -xf "$srcdir/LibreFang_${_desktop_ver}_amd64.deb" -C "$srcdir" data.tar.*
  bsdtar -xf "$srcdir/data.tar"* -C "$pkgdir"
  install -Dm644 "$srcdir/LICENSE" "$pkgdir/usr/share/licenses/${pkgname}/LICENSE"
}

or simply relying on bsdtar's libarchive deb support to extract the whole thing in one pass:

  bsdtar --strip-components=2 -xf "$srcdir/LibreFang_${_desktop_ver}_amd64.deb" -C "$pkgdir"

Either way, please verify the actual compression format of data.tar.* inside the release .deb and document it, or use a glob so future releases with a different compression still work.


Generated by Claude Code

@houko houko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the AUR packaging work.
The native librefang-bin service looks correct — it binds loopback by default, so it boots cleanly and isn't network-exposed.
Two issues on the librefang-docker side, the first a blocker.

Blocker: librefang-docker cannot start out of the box

The helper always passes --env "LIBREFANG_LISTEN=0.0.0.0:4545" (the docker_args array in packaging/aur/librefang-docker/librefang-docker), which is required for --publish to reach the process inside the container.
But a fresh librefang-data volume has no auth configured, and LIBREFANG_ALLOW_NO_AUTH=1 is left commented out in librefang-docker.env.

At boot, LIBREFANG_LISTEN overrides config.api_listen (crates/librefang-kernel/src/kernel/boot.rs:47-48), and then check_bind_auth_safety refuses to start on a non-loopback bind when no auth is configured and the operator has not opted in (crates/librefang-api/src/server.rs:1812-1813, decision logic in evaluate_bind_auth_safety at server.rs:280-302).
The daemon exits non-zero.

So systemctl enable --now librefang-docker.service — exactly what librefang-docker.install tells the user to run — fails immediately, and Restart=on-failure + RestartSec=5 in librefang-docker.service turns it into a crash loop that re-runs docker pull every five seconds.
The package never comes up on a default install.

The only documented escape, uncommenting LIBREFANG_ALLOW_NO_AUTH=1, then makes it boot but exposes an unauthenticated admin API (shell-exec, vault, LLM keys) on the host's 0.0.0.0:4545, reachable from the whole LAN.

Note one constraint when fixing this: binding loopback inside the container (e.g. LIBREFANG_LISTEN=127.0.0.1:4545) does not help, because Docker port publishing forwards into the container's network namespace and a process bound to the container's loopback is unreachable through the published port.
The working safe pattern is to keep the container bound to 0.0.0.0:4545, set LIBREFANG_ALLOW_NO_AUTH=1 by default so the daemon boots, and publish only to the host loopback — --publish 127.0.0.1:${PORT}:4545.
That matches the native package's loopback-only posture: it works out of the box and the open admin API is reachable only from the host, not the LAN.
If you prefer a fully authenticated default instead, the package needs to provision an api_key (or dashboard credentials) on first run rather than leaving auth empty.

Minor: LIBREFANG_MODEL is a no-op env var

librefang-docker.env documents # LIBREFANG_MODEL= and the helper forwards it via append_env_if_set LIBREFANG_MODEL, but nothing in the codebase reads LIBREFANG_MODEL — there are no occurrences outside packaging/aur/, and there is no generic LIBREFANG_-prefixed env-to-config mapping.
Setting it silently does nothing, which is misleading sitting next to OPENAI_API_KEY / ANTHROPIC_API_KEY / GROQ_API_KEY, which are genuinely read through each driver's api_key_env.
Please drop it from both the env file and the forwarding list, or point users at the real surface (config.toml / agent.toml).

@github-actions github-actions Bot added the needs-changes Changes requested by reviewer label Jun 25, 2026
@pavver
pavver requested a review from houko June 25, 2026 07:37

@houko houko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both blockers from the previous review are resolved in 43bb0ac0. Thanks for the quick turnaround.

  • data.tar.gz hardcode → fixed. librefang-desktop-bin/PKGBUILD now globs data.tar.* and extracts with bsdtar --no-same-owner, so .gz / .xz / .zst Debian payloads all work. bsdtar ships with libarchive (a base dependency), so no new depends entry is needed.
  • librefang-docker unauthenticated network exposure → fixed. --publish is now 127.0.0.1:${PORT}:4545, so the daemon is reachable only from host loopback; the in-container LIBREFANG_LISTEN=0.0.0.0:4545 is just the bind needed for the published port to reach the process. First-run boot is handled — librefang-docker.env ships LIBREFANG_ALLOW_NO_AUTH=1 and the helper forwards it, so a fresh librefang-data volume starts cleanly.

One optional, non-blocking note for later: the daemon is still unauthenticated, just confined to host loopback — anyone with a local shell on the host can reach it. Fine for a single-user box; a one-line mention in the env comment / README pointing at how to enable auth would be a nice touch, but it doesn't gate this PR.

Approving.

@github-actions github-actions Bot added ready-for-review PR is ready for maintainer review and removed needs-changes Changes requested by reviewer labels Jun 26, 2026
@houko
houko merged commit cbd8bf4 into librefang:main Jun 26, 2026
29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-review PR is ready for maintainer review size/L 250-999 lines changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants