Setup an FDroid App Repo

From F-Droid
Jump to: navigation, search is the default package repository (repo) in the FDroid client, but it is not the only possibility. Anyone can create their own repo, and users can control which repos their client is using, including even disabling the default repo. This model is modeled somewhat after the Debian GNU/Linux distro. Like Debian and Ubuntu, you can also setup your own repos for anyone to use.

This is a quick HOWTO to setup your own repository wherever you want to host it. It is somewhat technical, you will use the terminal, but you don't need to be a terminal expert to follow along. First, this HOWTO will walk through setting up a test repo that is not very secure. Then it will walk through setting up a repo for real world use, with the signing key on a separate machine from the public webserver. Before you start, you need to get the fdroidserver tools and a webserver. For the webserver, this HOWTO will use nginx since its lightweight, but any will do if you already have one running.

sudo apt-get install nginx

In the case of this HOWTO, we're going to setup a "Simple Binary Repository" to host a collection of APKs. The repo will be set up in the recommended fdroid/ subdirectory. This gives the fdroid tool its own directory to work in, and makes the repo URL clearly marked as an FDroid repo. Also, the F-Droid client will automatically search for a repository at the "/fdroid/repo" path if the user only the server (e.g. ""). Let's give our normal user control over this subdirectory in the web root so that we don't need to run the F-Droid tools as root (with nginx, the webroot is /usr/share/nginx/www, it is different for other webservers):

sudo mkdir /usr/share/nginx/www/fdroid
sudo chown -R $USER /usr/share/nginx/www/fdroid
cd /usr/share/nginx/www/fdroid
fdroid init

Now put your APK files into /usr/share/nginx/www/fdroid/repo and you are ready to run the commands to build the repo (if fdroid init cannot find your Android SDK in /opt/android-sdk or $ANDROID_HOME, it will prompt you for the path):

cd /usr/share/nginx/www/fdroid
cp /path/to/*.apk /usr/share/nginx/www/fdroid/repo/
fdroid update --create-metadata

Voila! Now you have a working F-Droid Repo! Remember, this is **just a test** setup, remember to move on to the Real World Setup after this! Add your new repo to an F-Droid client on your Android device to test it out. That is done in the Manage Repos screen available from the menu. Your repo URL will be the hostname or IP address of your machine with /fdroid/repo/ added to the end of it, i.e. or You can temporarily uncheck the official repos to easily see what F-Droid found in your new repo.


You can also customize your repo by editing the config file. Be sure to use a programming text editor, like editor /usr/share/nginx/www/fdroid/ In the config file, you can set the name of the repo, the description, the icon, paths to specific versions of the build tools, links to a related wiki, and whether to keep stats. Here's the basic repo description block:

repo_url = ""
repo_name = "My Local Repo"
repo_icon = "GP_Logo_hires.png"
repo_description = """
This is a local test repository of Hans-Christoph Steiner <>.  It is a repository of Guardian Project apps.

To put your icon into your repo, choose a PNG image to put in your repo. The PNG goes in /usr/share/nginx/www/fdroid/, the file can be named whatever you want (by default its fdroid-icon.png). If you change the name from the default, be sure to update repo_icon and archive_icon in /usr/share/nginx/www/fdroid/

A final note about security: this setup is not a good setup for a real public repo, instead it is a quick and easy way to test out FDroid. At the very least, when generating the repo in place, make sure that is not accessible via the web, since it contains passwords. If the file permissions are correct (e.g. chmod 0600, then will not be readable by the webserver.

App Metadata

You can control lots of aspects of how an app is represented in your repo by editing the app's metadata. Running fdroid update --create-metadata creates stub files for you, in order to have a working repo. Then you can edit those files to add a description, donation links, bug tracker, license, home page, etc. See the manual for more info on what all the options are.

Current Version Code provides a handy way to deploy beta releases in the same stream as your full releases. You can set Current Version Code to your current stable release, then add APKs to your repo. Users will only be updated automatically to the version code you specify. Any APKs for a given app in your repo that have a newer version code will not be automatically installed. Instead, the user can see them in the app detail view in the client, and can manually install them.

Real World Setup

Now that you have a working repo, it is straightforward to create a real world setup. Generating a repo in place like we did above is very easy, that is why this HOWTO started there, but it is not as secure as it should be if your repo is going to be your main distribution point. For example, the repo signing keys should not ever be on a public server.

To improve this situation, generate the repo on a non-public machine like your laptop, keeping and the keystore only on that machine (remember to make backups!). Then use fdroid server update to publish the changes to your repo on a separate server via ssh. So start a new repo from scratch on your non-public machine:

mkdir ~/fdroid
cd ~/fdroid
fdroid init
cp /path/to/*.apk ~/fdroid/repo/
fdroid update --create-metadata
emacs  # add the serverwebroot, etc.
fdroid server update -v

Now edit to set serverwebroot, it is in the form of a standard SCP file destination. Then fdroid server update will do the publishing via rsync over ssh. So both computers will have to have ssh and rsync installed and setup. You can also use your own existing signing key rather than the one generated by fdroid init, just edit repo_keyalias, keystore, keystorepass, keypass, and keydname in ~/fdroid/