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
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 omitted.
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 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 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
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.
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
/fdroid/repo/. 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 <email@example.com>. 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.
chmod 0600 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
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 Build Metadata
Reference for more info on what all the
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