fdroidserver-ipfs/SPEC.md

fdroidserver-ipfs

A drop-in replacement for registry.gitlab.com/fdroid/docker-executable-fdroidserver:master tailored for publishing F-Droid repositories over IPFS.

The upstream image works for HTTP-served repos but has two gaps that break the IPFS workflow. This image patches both.

Problem

Pinning an F-Droid repo to IPFS and serving it through public HTTP gateways (ipfs.io, dweb.link, cloudflare-ipfs.com, …) exposes two upstream limitations:

1. The ipfs-cid Python module isn't installed, so any fdroidserver code path that computes a CIDv1 for repo artifacts fails on the stock image.
2. index-v2.json is published under a stable filename. Public IPFS gateways cache aggressively by URL path, so clients keep getting the previous index for hours after a republish even though the underlying CID has changed.

Scope

This repo produces one OCI image — call it fdroidserver-ipfs — built FROM the upstream docker-executable-fdroidserver:master and applying the minimum set of changes needed for the IPFS workflow. Everything not listed below is intentionally inherited unchanged from upstream.

Change 1 — install ipfs-cid

Install the Debian ipfs-cid package (available in Trixie, which the upstream image is based on):

RUN apt-get update \
 && apt-get install -y --no-install-recommends ipfs-cid \
 && rm -rf /var/lib/apt/lists/*

Note: the PyPI package of the same name is a Python library only and ships no binary, so pip install ipfs-cid silently leaves CID generation disabled. fdroidserver auto-detects the binary on PATH (fdroidserver/common.py::shutil.which('ipfs_cid')) and, when present, calls calculate_IPFS_cid() for every published file — APKs, source tarballs, icons, screenshots, etc. — writing the resulting CIDv1 into each file's ipfsCIDv1 JSON field (fdroidserver/update.py:1661-1663, :1717-1719). On the stock upstream image the binary is missing, so the field is silently omitted and the IPFS-routing code path on the client is never exercised.

Why this matters for the client. fdroidclient has native IPFS support: org.fdroid.download.MirrorChooser (in libs/download/) reads the ipfsCIDv1 field on each file and, when a configured mirror is flagged isIpfsGateway, fetches the file by CID via that gateway instead of by URL. So once ipfs-cid is installed, every per-package asset (APK, icon, …) is automatically reachable via any IPFS gateway by any client with one configured — no patching required.

Change 2 — add ipfsCIDv1 to the index entry + cache-busted filename

Change 1 fixes per-package files but does not fix the index itself. The index block inside entry.json is built by fdroidserver/common.py::file_entry(), which only emits name / sha256 / size and never adds ipfsCIDv1 — even when one could be computed. So fdroidclient has no CID for index-v2.json to feed into MirrorChooser, and falls back to the stable HTTP path → public IPFS gateways serve a stale cached copy for hours after a republish.

The post-process wrapper closes both halves of this gap in one pass:

1. Computes the IPFS CIDv1 of repo/index-v2.json (using calculate_IPFS_cid from fdroidserver.common, which is the same code path fdroidserver itself uses for APKs).
2. Renames repo/index-v2.json → repo/index-v2-<h>.json, where <h> is the last 12 hex characters of the SHA-256 of the file's content. This image is IPFS-only — no stable copy is kept alongside.
3. Rewrites repo/entry.json so that entry["index"]:
   • Updates name to /index-v2-<h>.json
   • Adds ipfsCIDv1 with the value computed in step 1
   • Leaves sha256 and size unchanged (the bytes didn't move)
4. Re-signs entry.jar by calling fdroidserver.signindex.sign_index(repodir, "entry.json") — reuses the existing config.yml keystore + FDROID_KEY_STORE_PASS / FDROID_KEY_PASS env vars; no extra config surface.
5. If GPG signing is enabled in config.yml, regenerates entry.json.asc.
6. Applies the same CID/rename/rewrite to any diff/*.json files published alongside (each is referenced by its own name field in entry.json).

Two-layer cache strategy, on purpose:

• IPFS-aware clients (any user with an IPFS gateway configured as a mirror) follow the ipfsCIDv1 and fetch the index by CID. Always fresh, never gateway-cached by URL.
• Plain-HTTP clients still hit a new URL on every publish thanks to the <h> suffix → public gateway path caches naturally miss → fresh index without waiting for TTLs.

entry.jar itself stays at the fixed /entry.jar URL — gateways will still cache it, but it's tiny and clients fetch it first to discover both the current index filename and its CID, which are the cache-busted references we actually care about.

entry.json does not currently carry an ipfsCIDv1 for the index entry, but fdroidclient's parser is configured with ignoreUnknownKeys = true (libs/index/.../IndexParser.kt) and EntryFileV2 already declares the field (libs/index/.../IndexV2.kt), so adding it is both backwards-safe and natively consumed by current client versions.

Delivery: a small Python script (fdroidserver-ipfs-rehash, or similar) installed into the image's PATH that imports fdroidserver.signindex / fdroidserver.common directly. Either invoked manually after fdroid update, or wired into a container entrypoint that runs both. Entrypoint design is deferred until we know how the image gets driven in production.

Out of scope

• Changes to index-v1.* or the legacy index.jar flow.
• Pinning to IPFS, gateway selection, DNSLink updates — handled by whatever drives the container, not by the image itself.
• Anything unrelated to the two issues above.

Non-goals for this spec

This document captures what the image needs to do and why. The concrete Dockerfile layering, the exact rehash/re-sign script, and the workflow YAML are implementation details and land in follow-up changes.