sam
56ef4610a6
docs/FDROID.md covers both a self-hosted F-Droid repo and the official f-droid.org route (incl. the prebuilt-OpenCV caveat). scripts/update-fdroid-repo.sh pulls the release APKs from Gitea and rebuilds the signed index. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
# 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/`](../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`):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
export FDROID_HOME="$HOME/paperscan-fdroid"
|
|
mkdir -p "$FDROID_HOME" && cd "$FDROID_HOME"
|
|
fdroid init # generates config.yml + keystore.p12
|
|
```
|
|
|
|
Edit `config.yml`:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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.:
|
|
|
|
```bash
|
|
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 `rsync`es `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.
|