F-Droid.org is the default package repository (repo) in the F-Droid 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 f-droid.org 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. Custom repos do not even need to build the APKs, they can just be “simple binary repos” of any APKs.
If you want to maintain a simple binary repository of APKs and packages obtained elsewhere, the process is quite simple:
- Set up the server tools
- Create a directory called fdroid, then run
fdroid initin that directory to generate the signing key that uniquely identifies your repo.
- Optionally edit the config.yml file to your liking, detailed examples are in examples/config.yml
- Within fdroid, make a directory called repo and put APK files in it.
- If it reports that any metadata files are missing, you can create
them in the
metadatadirectory and run it again.
- To ease creation of metadata files, run
fdroid updatewith the
-coption. It will create ’skeleton’ metadata files that are missing, and you can then just edit them and fill in the details.
- Then, if you’ve changed things, run
fdroid updateadds an icons directory into the repo directory, and also creates the repository index files (index.xml, index.jar, etc) NOTE: To make this process secure, read Real World Setup below!
- Publish the resulting contents of the repo directory
to your web server (or set
serverwebrootin your config.yml then use
Following the above process will result in a repo directory, which you simply need to push to any HTTP (or preferably HTTPS) server to make it accessible.
While some information about the applications (and versions thereof)
is retrieved directly from the APK files, most comes from the
corresponding file in the metadata/ directory. The
metadata file covering ALL versions of
a particular application is named package.id.yml where package.id is
the unique identifier for that package. All build metadata fields are
relevant for binary APKs, except for
Builds: entries, which should be
Local Demo Repo HOWTO
This is a full 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
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
its own directory to work in, and makes the repo URL clearly marked as
an F-Droid repo. Also, the F-Droid client will automatically search for
a repository at the /fdroid/repo path if the user only enters the server
(e.g. “https://f-droid.org”). 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
cannot find your Android SDK in /opt/android-sdk or
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.
http://192.168.2.53/fdroid/repo/. You can temporarily uncheck the
official repos to easily see what F-Droid found in your new repo.
While you can serve the repository at an arbitrary URL, it is customary
to make it available at an URL ending with
A good reason to actually do this is that the F-Droid client sets up an
intent filter and registers itself for such URLs. As a result, a user
that has the F-Droid app installed and opens such a well-formed URL
will have their device open F-Droid and guide them directly to adding
the repository to it.
You can also customize your repo by editing the config file. Be sure to
use a programming text editor, like
/usr/share/nginx/www/fdroid/config.yml. 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 = "http://guardianproject.info/fdroid/repo" repo_name = "My Local Repo" repo_icon = "GP_Logo_hires.png" repo_description = """ A local test repository of Hans-Christoph Steiner <firstname.lastname@example.org>. 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
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 F-Droid. At
the very least, when generating the repo in place, make sure that
config.yml is not accessible via the web, since it contains
passwords. If the file permissions are correct (e.g.
config.yml), then config.yml will not be readable by the webserver.
You can control lots of aspects of how an app is represented in your
repo by editing the app’s metadata. Running
--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
Build Metadata Reference for more info
on what all the options are.
CurrentVersionCode provides a handy way to deploy beta releases in the same stream as your full releases. You can set CurrentVersionCode 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 config.yml and the
keystore only on that machine (remember to make backups!). Then use
fdroid deploy 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 config.yml # add the serverwebroot, etc. fdroid deploy -v
Now edit config.yml to set
serverwebroot, it is in the form of a
standard SCP file destination. Then
fdroid deploy 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
keydname in ~/fdroid/config.yml.