Skip to content

K2GO-421 feat(fdroid): self-hosted F-Droid repository on R2 - #816

Merged
luisguzman-adfa merged 3 commits into
mainfrom
feat/K2GO-421-self-hosted-fdroid-repo
Nov 21, 2026
Merged

luisguzman-adfa merged 3 commits into
mainfrom
feat/K2GO-421-self-hosted-fdroid-repo

Conversation

@luisguzman-adfa

Copy link
Copy Markdown
Collaborator

What changes

  • tools/fdroid-repo/: builds the self-hosted F-Droid repository of Knowledge to Go from the fdroid APK on R2, and publishes it to the bucket k2go-apk-repo under fdroid/ (signed index, APKs, landing page).
  • .github/workflows/app-fdroid-repo.yml: new workflow. "App+Play: 2. publish release" calls it after the release job. A manual run writes fdroid-staging/.
  • controller/docs/ADR-K2GO-421-self-hosted-fdroid-repo.md: the design (Accepted).

Why

F-Droid users can add one repository and get Knowledge to Go and its updates from us, while the official f-droid.org inclusion is open (K2GO-399).

Steps to QA

Baseline: https://k2go-download.appdevforall.org/fdroid/repo shows "Object not found".

Change (local test, tools/fdroid-repo/README.md):

  1. Run publish.sh with LOCAL_BUCKET, a test keystore and an APK signed with it.
  2. Serve the folder with r2_mock_server.py --bind 0.0.0.0 and open /fdroid/index.html on a phone on the same Wi-Fi.
  3. Push "Add to F-Droid": F-Droid opens and adds the repository. Install the app from F-Droid.

After the merge: run "App: publish F-Droid repo" by hand for v1.2.0 with staging on, then add the staging repository in F-Droid.

Verifications

  • Unit tests: 20 pass (python -m unittest -v test_fdroid_repo). shellcheck and actionlint are clean on the new files.
  • Phone on the LAN: F-Droid added the repository, then downloaded and installed the app.
  • The run stops before the upload when the release APK is missing, when another key signed it, or when the index names a missing file.
  • Deferred: a Cloudflare cache rule for /fdroid/repo/entry.jar and /fdroid/repo/index*, before the next final release. The first run on real R2 is the staging run.

Notes

  • The repository index is signed with the app signing key: the repository fingerprint is the fingerprint of the app certificate.
  • A Play install cannot update from this repository (Google signs it with another key).

…oid repo on R2

tools/fdroid-repo/publish.sh pulls the published repo from R2, adds the
fdroid APK of the release, runs fdroid update (Debian trixie), verifies,
makes the landing page, and uploads in a safe order (files first, then
the indexes, then entry.jar, then the page; deletions last).

- The repo index is signed with the app signing key (same secrets).
- verify stops the run when the release APK is missing, signed by
  another key, or when the index names a file that is not there.
- The landing page uses the look of the add-ons site, a fdroid.link
  "Add to F-Droid" link and QR code, and an SVG app icon made from the
  adaptive icon of the app. It is also served at the repo address.
- r2_mock_server.py serves a folder the way R2 does, for a local test.
app-fdroid-repo.yml publishes the F-Droid repository from the fdroid APK
that the release job put on R2. "App+Play: 2. publish release" calls it
after the release job (live fdroid/). A manual run writes fdroid-staging/
by default. Release candidates never reach the repository.
Decisions of the maintainer: prefix fdroid/ on k2go-apk-repo, the fdroid
flavor, one signing key for the app and the repo index, three versions
plus archive, R2 as the only state, and the look of the add-ons site.
@luisguzman-adfa
luisguzman-adfa merged commit c57d825 into main Nov 21, 2026
3 checks passed
@luisguzman-adfa
luisguzman-adfa deleted the feat/K2GO-421-self-hosted-fdroid-repo branch November 21, 2026 07:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant