Running a Mirror | F-Droid - Free and Open Source Android App Repository (2025)

F-Droid’s collection of apps and files are run on servers run by the coreF-Droid contributors. Originally, this main repository was hosted only onf-droid.org, but as F-Droid grewf-droid.org alone was no longer able to handle theentire load. F-Droid now supports “mirror” servers that replicate a fullcopy of the repositories. Hosting a mirror involves running an HTTPSwebserver that has a full copy of the repository synchronized using rsync.

Primary and Secondary Mirrors

Whenever F-Droid has built a new index, it proactively pushes it to aselected set of mirrors, called the “primary mirrors”. In other words,primary mirrors are updated nearly immediately. As of September 2024, theprimary mirrors are (latestlist):

• ftp.agdsn.de
• ftp.lysator.liu.se
• plug-mirror.rcac.purdue.edu

Most other mirrors are “secondary mirrors”. These mirrors sync periodically(e.g., every 4 hours) from one of the primary mirrors.

Therefore, secondary mirrors usually have a small propagation delay.Nevertheless, note that in practice the time between any two index updatesis dominated by the time to update and build the apps (in the order ofdays). Not having too many primary mirrors also keeps the load on theF-Droid origin server small.

Technically, you can also have a “tertiary mirror” by syncing from asecondary mirror, and so on.

Requirements

There are two official F-Droid repository sections, the “repo” and the“archive”. It’s most important to mirror the “repo” since it is used muchmore than the “archive”.

The primary resources required by a mirror are disk space and uploadbandwidth. Bandwidth requirements are reduced with each new mirror, butdisk requirements grow at a reasonablerate.In March 2019, the primary repository required just over 60GB of disk spacein 24K files, and the archive required 300GB of disk space in 52K files. InFebruary 2024, the primary repository required 450GB in 180K files, and thearchive required 1.9TB in 430K files. The amount of disk space requiredgrows with every new app release.

There are many mirror servers which offer an rsync connection, make sureto select the mirror closest to your mirror server:

You can find current information on disk space requirements by running thefollowing in your terminal:

$ rsync --dry-run --recursive --stats --human-readable ftp.fau.de::fdroid .

Setup

This guide assumes the use of Nginx with a deb-based distribution, andmirroring the primary repository plus the archive. Please adjust accordinglyif you’re using alternatives or don’t intend to mirror the archive. Alsosubstitute the examples paths and domains for your own.

For assistance with this process, feel free to reach out to us.

1. Create appropriate directories

$ sudo mkdir -p /var/www/fdroid/fdroid/repo$ sudo mkdir -p /var/www/fdroid/fdroid/archive$ sudo chown -R www-data.www-data /var/www/fdroid

2. Synchronize the repositories.

These commands are best run in a terminal multiplexer (screen, tmux etc)as they will take some time to complete. With --info=progress2 you can seethe progress.

$ sudo -u www-data -E /usr/bin/rsync -aHS --delete --delete-delay --info=progress2 ftp.fau.de::fdroid/repo/ /var/www/fdroid/fdroid/repo/$ sudo -u www-data -E /usr/bin/rsync -aHS --delete --delete-delay --info=progress2 ftp.fau.de::fdroid/archive/ /var/www/fdroid/fdroid/archive/

3. Establish a cronjob to keep the repositories up to date

Create a cronjob file in /etc/cron.d

$ vi /etc/cron.d/fdroid

Fill the file with entries to update the repositories. These commands willrun at minute 35 past every 6th hour, you can change it to fit your needs.

35 */6 * * * www-data /usr/bin/rsync -aHS --delete --delete-delay ftp.fau.de::fdroid/repo/ /var/www/fdroid/fdroid/repo/35 */6 * * * www-data /usr/bin/rsync -aHS --delete --delete-delay ftp.fau.de::fdroid/archive/ /var/www/fdroid/fdroid/archive/

4. Configure your webserver

This is an example server block for nginx. If used, it should be copied to/etc/nginx/sites-available/ and symlinked to/etc/nginx/sites-enabled. Note that it is important that your URI be/fdroid/repo so that the app can automatically add your mirror.

server { listen [::]:80 ipv6only=off; server_name fdroidmirror.example.com; rewrite ^ https://$host$request_uri permanent;}server { listen [::]:443 ssl http2 ipv6only=off; server_name fdroidmirror.example.com; root /var/www/fdroid/; ssl_certificate /etc/letsencrypt/live/fdroidmirror.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/fdroidmirror.example.com/privkey.pem; # Insert here a TLS config from Mozilla SSL config generator https://mozilla.github.io/server-side-tls/ssl-config-generator/}

5. Test that your mirror works

Manually add your mirror to F-Droid to test that it works.

Go to Settings -> Repositories, click the “+” button, and then manually enter your repository URL (don’t use the QR code):https://fdroidmirror.example.com/fdroid/repo?fingerprint=43238D512C1E5EB2D6569F4A3AFBF5523418B82E0A3ED1552770ABB9A9C9CCAB

Then disable the other mirrors except your new one, refresh the index withpull-to-refresh, and browse and install some apps!

6. Set up a privacy policy

Please include a privacy policy so that users can understand what happenswith their metadata when using your mirror. For inspiration, see:

• FAU: https://ftp.fau.de/datenschutz
• Lysator: https://ftp.lysator.liu.se/datahanteringspolicy.txt
• Purdue PLUG: https://plug-mirror.rcac.purdue.edu/info.html

7. Submit your mirror for inclusion

• Fork the mirror monitor repo,add your mirror to the list in the README, and open a merge request.
• Open an issue on the admin repo,including any pertinent information, requesting the inclusion of yourmirror.
• Once the core contributor team deems your mirror trustworthy and reliable,it will be accepted into the official list.

Other considerations

• Forward emails from cronjob failures so you know if the synchronizationfails
• Monitor disk usage to prevent it from getting full
• Monitor your mirror so you know if it goes down (ideally keyword on/srv/mymirror.org/htdocs/fdroid/repo/index-v1.jar)
• Harden your SSH server config (disable password authentication, installfail2ban)
• Enable unattended security upgrades (in Debian, just apt-get installunattended-upgrades)

Running a Primary Mirror (receiving syncs via push)

The preferred setup is for the F-Droid updates to be pushed to the primarymirror via rsync over ssh with SSH Key authentication. This is the sameas Debian, the keydifference is that there currently is no script used for the command="",but instead, there is a hard-coded rsync command. This really nicelyrestricts the security interaction to only want needs to happen (LeastAuthority!).

command="rsync --server -logDtpre.iLsfx --log-format=X --delete --delay-updates . /srv/fdroid-mirror.at.or.at/htdocs/fdroid/"

The only piece of that command that is customizable is the final path. Itcan be any path but it must point to the /fdroid/ directory and must havethe trailing slash. If any of the rsync options are changed, it willbreak the sync setup.

As an extra precaution, there should be a user account (e.g. fdroid)dedicated to receiving the rsync/ssh connection. It should have aslittle access as possible. It should definitely not have write access tothe authorized_keys file, since that would allow an attacker who gainswrite access to add a separate key configuration line which circumvents allthe restrictions listed there. This can be done simply by doing:

$ sudo chown root.root /home/fdroid/.ssh /home/fdroid/.ssh/authorized_keys$ sudo chmod 0755 /home/fdroid/.ssh$ sudo chmod 0644 /home/fdroid/.ssh/authorized_keys