Make an F-Droid custom repo

bgstack15

2025-07-18 08:59

Purpose

The official F-Droid repos which I mirror in my fdroid mirror do not contain some packages for various reasons. Because that project is supposed to be about mirroring only the relevant parts of the official repos, I need a separate spot to store apks I care about.

Preparing the main F-droid custom repo

User fdroid already exists. I took these steps, following Reference 1.

# my user
mkdir -p /mnt/public/www/example/repo/fdroid
chown fdroid:admins /mnt/public/www/example/repo/fdroid
sudo su - fdroid
cd /mnt/public/www/example/repo/fdroid
fdroid init # generated a keystore.p12

I intend to use a cert signed by my own CA, so I will follow Reference 2 and my previous post.

openssl genpkey -algorithm RSA -out fdroid-server3.ipa.example.com.key -pass pass:''
openssl req -new -key fdroid-server3.ipa.example.com.key \
    -subj "/OU=fdroid/CN=server3.ipa.example.com" \
    -addext "subjectAltName = DNS:fdroid.ipa.example.com,DNS:server3.ipa.example.com,DNS:internal.example.com" \
    -out fdroid-server3.ipa.example.com.csr
ipa host-add --force fdroid.ipa.example.com
# other DNS SANs already exist as hosts in ipa.example.com
ipa service-add --force FDROID/server3.ipa.example.com
ipa service-add --force FDROID/fdroid.ipa.example.com
ipa service-add --force FDROID/internal.example.com
ipa cert-request --chain --principal=FDROID/server3.ipa.example.com fdroid-server3.ipa.example.com.csr --certificate-out=fdroid-server3.ipa.example.com.pem

I had to split out the CA cert from the .pem file because if it is in the pkcs12, then fdroid clients will have a problem reading the repo:

> Bad fingerprint
> org.fdroid.index.SigningException: index.jar code signers must only have a single certificate

After fixing the pem to have a single entry:

openssl pkcs12 -export -in fdroid-server3.ipa.example.com.pem -inkey fdroid-server3.ipa.example.com.key -out fdroid-server3.ipa.example.com.p12 -name fdroid
# see-keepass-for-pw

Unfortunately my requested subject was not given, but I do have a cert, with serial number 11412853854 (0x2a842545e).

sudo chown fdroid:admins *p12
sudo chmod 0660 *p12
sudo chgrp admins repo
sudo chmod u=rwX,g=rwX repo

I adjusted config.yml with the relevant details. I put the bare csr, key, and pem in .certs/.

Now I placed the desired wireguard apk in the directory /mnt/public/www/example/repo/fdroid/repo by running /mnt/public/Support/Programs/wireguard/get-latest-upstream-wireguard-apk.sh. And then generate the initial metadata with this.

. ~/venv2/bin/activate
fdroid update -c --use-date-from-apk

I set up the icon too:

cp -pi /mnt/mirror/fdroid/bgstack15.png /mnt/public/www/example/repo/fdroid/

I copied in the existing css assets:

cp -pr /mnt/mirror/fdroid/assets /mnt/public/www/example/repo/fdroid

What packages are included here

So far I only wanted this additional package.

wireguard

Related files

These files are underneath /mnt/public/www/example/repo/fdroid/.

.certs/
bgstack15.png
config.yml
fdroid-server3.ipa.example.com.p12
generate-web-example.conf is the config file for fdroid_generate_web.py

Additional files

/etc/installed/fdroid/fdroid_generate_web.py
/mnt/public/Support/Programs/wireguard/get-latest-upstream-wireguard-apk.sh

Operations

Checking for updated packages

Checking for new wireguard packages

As user fdroid@server3, run /mnt/public/Support/Programs/wireguard/get-latest-upstream-wireguard-apk.sh

Adding a new package

(Based on Reference 4 Find the desired .apk files and place them in /mnt/public/www/example/repo/fdroid/repo. Then for an icon, you might need to explode the zip-format .apk file and find a suitable icon, and place it as file:

/mnt/public/www/example/repo/fdroid/repo/com.example.appname/en-US/icon.png

Make sure user fdroid can write to that en-US directory because it will generate some hash of the file and make a symlink to it.

You also have to add contents to a yml file in metadata/. To build the blank default ones for any new packages, run fdroid update -c --use-date-from-apk. Perhaps check https://gitlab.com/fdroid/fdroiddata/-/tree/master/metadata by downloading it with git. The web view is hard to navigate because of the large number of files.

Updating the repository

Once all desired apk files are in place in /mnt/public/www/example/repo/fdroid/repo, switch to user fdroid@server3 and run these commands.

cd /mnt/public/www/example/repo/fdroid
fdroid update

Also update the static web page I generate.

CONF_FILE=/mnt/public/www/example/repo/fdroid/generate-web-example.conf /etc/installed/fdroid/fdroid_generate_web.py

Knowledge Base