Perun: Difference between revisions

From Local Area Network
New tool page, source-checked against the project README
 
Plainer prose: fewer quotes, project claims attributed, glosses folded in
 
(One intermediate revision by the same user not shown)
Line 2: Line 2:
| name        = Perun
| name        = Perun
| what        = Privacy-first run tracker, rebuilt on the Logos stack as an Android app and a Basecamp module
| what        = Privacy-first run tracker, rebuilt on the Logos stack as an Android app and a Basecamp module
| stage      = Full Release
| stage      = Almost done
| licence    = MIT or Apache-2.0 (licence files in the repository)
| licence    = MIT or Apache-2.0 (licence files in the repository)
| code        = https://github.com/vpavlin/perun
| code        = https://github.com/vpavlin/perun
Line 10: Line 10:
| verified_against = README and commit of 11 October 2026
| verified_against = README and commit of 11 October 2026
}}
}}
'''Perun''' is a privacy-first run tracker with an Android app that sends runs over [[Logos Messaging]] (Logos Delivery) to a [[Basecamp]] module on the desktop. It is published by the GitHub user vpavlin.
'''Perun''' is a privacy-first run tracker by the GitHub user vpavlin. Its Android app sends runs over [[Logos Messaging]] (Logos Delivery) to a [[Basecamp]] module on the desktop.


== What it does ==
== What it does ==
* Records runs on an Android phone with GPS, also in the background, and shows them on the phone.
* The Android app records runs with GPS, also in the background, and shows them on the phone.
* Sends a run to the user's Basecamp with "Sync to Basecamp" over Logos Delivery. The app uses the phone's shared Loam node when it is installed, and otherwise runs its own node.
* The app's "Sync to Basecamp" sends a run to the user's Basecamp over Logos Delivery. The app uses Loam's shared node when Loam is installed, and otherwise runs its own. Loam is a separate app that runs one shared Logos Delivery node per phone for local-first apps.
* Receives runs in <code>perun_core</code>, the Basecamp core module, which decodes the track, computes splits, elevation, pace and heart rate, and stores them in SQLite.
* <code>perun_core</code>, the Basecamp core module, receives each run, decodes the track, computes splits, elevation, pace and heart rate, and stores them in an SQLite database.
* Shows the runs in Perun Analytics (<code>perun_analytics</code>), the desktop Basecamp view.
* Perun Analytics (<code>perun_analytics</code>), the desktop Basecamp view, shows the runs.
* Can run <code>perun_core</code> headless as an always-on hub.
* <code>perun_core</code> can also run headless, with no interface, as an always-on hub.
* Uses a shared wire contract with a compact track codec, so that a normal run fits in one 150 KB Delivery message.
* Both ends follow a shared wire contract, the message format they agree on. Its compact track codec fits a normal run in one 150 KB Delivery message.
* Keeps the blockchain out of scope for now. Logos Storage is an optional backup and is not on the sync path.
* The blockchain is out of scope for now, and Logos Storage is an optional backup that is not on the sync path.


Stage: Full Release. The README says "the Android app and the Basecamp core + view are released", and adds that "the desktop is Linux x64 only for now". The original React web app now lives in a separate repository, vpavlin/perun-legacy. The README does not say whether it is an official Logos project.
Stage: Almost done. The README says "the Android app and the Basecamp core + view are released", meaning published on apps.vpavlin.xyz, and adds that the desktop is Linux x64 only for now. The modules are still below version 1.0. The original React web app now lives in a separate repository, vpavlin/perun-legacy. The README does not say whether it is an official Logos project.


== Use it ==
== Use it ==
# Android: add the F-Droid repository from [https://apps.vpavlin.xyz apps.vpavlin.xyz] and install Perun. The README recommends installing Loam as well. It runs on arm64 phones.
# Android: add the F-Droid repository from [https://apps.vpavlin.xyz apps.vpavlin.xyz] and install Perun, ideally with Loam as well. It runs on arm64 phones.
# Desktop: this needs Basecamp 0.3 on Linux x64. Add <code>https://apps.vpavlin.xyz/logos-repo.json</code> in Basecamp's package manager, then install Perun Analytics. It pulls in <code>perun_core</code>.
# Desktop: this needs Basecamp 0.3 on Linux x64. Add <code>https://apps.vpavlin.xyz/logos-repo.json</code> in Basecamp's package manager, then install Perun Analytics. It pulls in <code>perun_core</code>.
# Instead of the repository, a portable <code>.lgx</code> from a [https://github.com/vpavlin/perun/releases GitHub Release] can be installed with <code>lgpm install URL --to ./modules</code>, where URL is the release file.
# Instead of the repository, a portable <code>.lgx</code> from a [https://github.com/vpavlin/perun/releases GitHub Release] can be installed with <code>lgpm install URL --to ./modules</code>, where URL is the release file.


== Build it ==
== Build it ==
* <code>nix build ./module#lgx-portable</code> builds a portable bundle. The README says to always build the portable variant, not <code>.#lgx</code>.
* <code>nix build ./module#lgx-portable</code> builds a portable bundle. The portable variant should always be built instead of <code>.#lgx</code>.
* Pushing a <code>module-v*</code> tag makes CI build the <code>perun_analytics</code> portable <code>.lgx</code> for linux-amd64 and attach it to a GitHub Release.
* According to the README, pushing a <code>v*</code> tag makes CI build the <code>perun_analytics</code> portable <code>.lgx</code> for linux-amd64 and attach it to a GitHub Release. The workflow file triggers only on <code>module-v*</code> tags.
* After a release, <code>scripts/gen-repo-index.sh vX.Y.Z</code> refreshes <code>repo/index.json</code>, which is then committed.
* After a release, <code>scripts/gen-repo-index.sh vX.Y.Z</code> refreshes <code>repo/index.json</code>, which is then committed.


Line 46: Line 46:
* [https://github.com/vpavlin/perun/blob/master/module/metadata.json module/metadata.json] and [https://github.com/vpavlin/perun/blob/master/core/metadata.json core/metadata.json], GitHub
* [https://github.com/vpavlin/perun/blob/master/module/metadata.json module/metadata.json] and [https://github.com/vpavlin/perun/blob/master/core/metadata.json core/metadata.json], GitHub
* [https://github.com/vpavlin/perun/tags perun tags], GitHub
* [https://github.com/vpavlin/perun/tags perun tags], GitHub
* [https://github.com/vpavlin/perun/blob/master/.github/workflows/release.yml release.yml] workflow, GitHub
* [https://apps.vpavlin.xyz apps.vpavlin.xyz], app catalogue


{{Page status|Stub}}
{{Page status|Stub}}

Latest revision as of 23:27, 4 November 2026

Perun
What it does: Privacy-first run tracker, rebuilt on the Logos stack as an Android app and a Basecamp module
Stage: Almost done
Licence: MIT or Apache-2.0 (licence files in the repository)
Verified on 4 November 2026 against README and commit of 11 October 2026.

Perun is a privacy-first run tracker by the GitHub user vpavlin. Its Android app sends runs over Logos Messaging (Logos Delivery) to a Basecamp module on the desktop.

What it does

  • The Android app records runs with GPS, also in the background, and shows them on the phone.
  • The app's "Sync to Basecamp" sends a run to the user's Basecamp over Logos Delivery. The app uses Loam's shared node when Loam is installed, and otherwise runs its own. Loam is a separate app that runs one shared Logos Delivery node per phone for local-first apps.
  • perun_core, the Basecamp core module, receives each run, decodes the track, computes splits, elevation, pace and heart rate, and stores them in an SQLite database.
  • Perun Analytics (perun_analytics), the desktop Basecamp view, shows the runs.
  • perun_core can also run headless, with no interface, as an always-on hub.
  • Both ends follow a shared wire contract, the message format they agree on. Its compact track codec fits a normal run in one 150 KB Delivery message.
  • The blockchain is out of scope for now, and Logos Storage is an optional backup that is not on the sync path.

Stage: Almost done. The README says "the Android app and the Basecamp core + view are released", meaning published on apps.vpavlin.xyz, and adds that the desktop is Linux x64 only for now. The modules are still below version 1.0. The original React web app now lives in a separate repository, vpavlin/perun-legacy. The README does not say whether it is an official Logos project.

Use it

  1. Android: add the F-Droid repository from apps.vpavlin.xyz and install Perun, ideally with Loam as well. It runs on arm64 phones.
  2. Desktop: this needs Basecamp 0.3 on Linux x64. Add https://apps.vpavlin.xyz/logos-repo.json in Basecamp's package manager, then install Perun Analytics. It pulls in perun_core.
  3. Instead of the repository, a portable .lgx from a GitHub Release can be installed with lgpm install URL --to ./modules, where URL is the release file.

Build it

  • nix build ./module#lgx-portable builds a portable bundle. The portable variant should always be built instead of .#lgx.
  • According to the README, pushing a v* tag makes CI build the perun_analytics portable .lgx for linux-amd64 and attach it to a GitHub Release. The workflow file triggers only on module-v* tags.
  • After a release, scripts/gen-repo-index.sh vX.Y.Z refreshes repo/index.json, which is then committed.

Releases

The latest tags are module-v0.6.0 and mobile-v1.12.0, both dated 16 July 2026. module/metadata.json gives perun_analytics version 0.9.0, and core/metadata.json gives perun_core version 0.10.4.

See also

Sources

Page status: Stub. Stub · Outline · Usable · Guide · Star. Anyone can improve this page and change its status.
Retrieved from "https://alienware-1.tailb5c716.ts.net/index.php?title=Perun&oldid=858"