paperscan/docs/FDROID.md

Publishing PaperScan on F-Droid

Two routes, from easiest to most reach:

1. Your own F-Droid repository — you host your signed APKs; users add your repo URL.
2. The official f-droid.org repository — huge reach, but they build from source and vet dependencies.

Both use the store metadata in fastlane/metadata/android/.

---

1. Your own F-Droid repository (recommended first)

You serve a small static site containing your signed APKs plus a signed index. Users add the URL once in the F-Droid app and then get updates automatically. No review, no rebuild, and the prebuilt OpenCV libraries are a non-issue because you provide the APK.

One-time setup

Install fdroidserver (needs a JDK + the Android SDK build-tools on PATH):

pipx install fdroidserver          # or: sudo apt install fdroidserver

Create the repo workspace and its repo signing key (separate from the app signing key — it signs the index, not the app):

export FDROID_HOME="$HOME/paperscan-fdroid"
mkdir -p "$FDROID_HOME" && cd "$FDROID_HOME"
fdroid init                        # generates config.yml + keystore.p12

Edit config.yml:

repo_url: "https://fdroid.geyskens.eu/repo"     # where you'll host it
repo_name: "PaperScan"
repo_description: "Self-hosted F-Droid repository for PaperScan."
archive_older: 3                                 # keep last 3 versions in the main repo

⚠️ Back up keystore.p12 and its passwords (in config.yml / ~/.config/fdroidserver). Lose it and you must publish a new repo URL — clients can't verify updates otherwise.

Let F-Droid pick up the localized store text: point it at this repo's fastlane metadata:

mkdir -p "$FDROID_HOME/metadata"
ln -s /path/to/paperscan/fastlane/metadata/android "$FDROID_HOME/metadata/eu.geyskens.pdfscan"

Publishing a version

Use the helper script (pulls every release APK from Gitea and rebuilds the index):

FDROID_HOME="$HOME/paperscan-fdroid" /path/to/paperscan/scripts/update-fdroid-repo.sh

Then publish the generated repo/ directory to your web host, e.g.:

rsync -a --delete "$FDROID_HOME/repo/" web:/var/www/fdroid/repo/

Serve it as plain static files (any web server). Users then: F-Droid app → Settings → Repositories → + → https://fdroid.geyskens.eu/repo, and enable it. Tip: https://fdroid.geyskens.eu/repo?fingerprint=<FINGERPRINT> (from fdroid update output) lets them add it with the fingerprint pre-filled.

Automating it in CI (optional)

The existing Gitea Actions build already produces a signed APK per tag. To also refresh the F-Droid repo, add a job that: installs fdroidserver, restores the repo keystore from a secret, runs scripts/update-fdroid-repo.sh, and rsynces repo/ to the web host (host key + key as secrets). Keep the repo keystore in a secret just like the app signing key.

---

2. The official f-droid.org repository

Bigger audience (it's in the default F-Droid app), but stricter:

• License — must be a recognized free license. PaperScan is GPL-3.0 ✔ (LICENSE).
• Build from source — F-Droid builds the APK on their servers; no prebuilt binaries in the APK's own code. ⚠️ Our org.opencv:opencv Maven dependency ships prebuilt native .so libraries. F-Droid flags prebuilt binaries; you may need to build OpenCV from source or get the artifact allow-listed. This is the main hurdle — resolve it before submitting.
• Reproducible-ish, no trackers — PaperScan already has no analytics/trackers and only the Camera + Internet permissions, which helps.

Process:

1. Open a Request For Packaging (RFP) issue at https://gitlab.com/fdroid/rfp (or go straight to a merge request).
2. Add a build recipe metadata/eu.geyskens.pdfscan.yml to the fdroiddata repo describing the source (git.geyskens.eu), the tag, and the Gradle build. The fastlane metadata is picked up automatically for the listing.
3. Iterate with the F-Droid maintainers (mostly around the OpenCV native libs).

Because F-Droid builds from source, they also re-sign the APK with F-Droid's key — so an app installed from f-droid.org can't be updated from your own repo and vice-versa (different signatures). That's expected; pick one channel per user.