Skip to content

Latest commit

 

History

History
139 lines (90 loc) · 9.57 KB

setup.md

File metadata and controls

139 lines (90 loc) · 9.57 KB

Set up for you own apps

This guide will show you how to set up an F-Droid repo with this tool. It makes some assumptions you need to know about:

  • You use GitHub to host the repositories of your app(s)
  • You create GitHub releases for your app(s)
    • My recommendation is to create a GitHub Actions workflow in your app repo that builds & signs your APK, then publishes it as a release (maybe as a draft release so you have more control). If you want to see how I did it with a Flutter app, go here.
  • Your release tag names are something like v1.2.3 (recommended, but should work anyways regardless)

This tool does not build your apps from source. It assumes that the build process runs in the application's repository.

When building/releasing a new version of your app, you need to make sure that you update not only the versionName, but also the versionCode. It seems like the latter is preferred by F-Droid for comparing versions.

  • In Flutter, you have something like version: 1.2.3+4 in your pubspec.yaml file. The 1.2.3 is the versionName, the versionCode is after the +, so 4 in this case. You should update both for F-Droid to recognize an update.

Install & initialize your F-Droid repository

  1. First of all, clone this repository and delete everything from the fdroid directory. This deletes my repo files; you can now use it for your own apps. If you want to reduce the size of the repository, you can also delete the .git directory, then git init again (you need to force-push/create a new repo after that).

  2. Now you can install the F-Droid server tools by running the following:

     sudo add-apt-repository ppa:fdroid/fdroidserver
 sudo apt-get update
 sudo apt-get install fdroidserver

    Make sure that you install version 2.x of the fdroidserver package. In the previous step we added the repository because the fdroidserver package I found at first (in the default repo) was outdated; so just make sure it's version 2 (you can also check with apt-get -s install fdroidserver).

    We only need these tools once to set up the repository. After these steps you can delete them, as now GitHub Actions will manage everything.

  3. Then run fdroid init in the fdroid subdirectory:

     cd fdroid && fdroid init --repo-keyalias KEYALIAS

    This creates two files: fdroid/config.yml and fdroid/keystore.p12. The first one is the configuration file for your repository, the second one is a keystore file (these are used for signing apps when building, but this tool doesn't build apps).

    Edit the base_fdroid_config.yml. Make sure the repo_url looks something like this (it should include your username instead of xarantolus):

    repo_url: https://raw.githubusercontent.com/xarantolus/f-droid/main/fdroid/repo

    You should also set archive_older to 0 to disable the archive:

    archive_older: 0

  4. Open your GitHub repository, go to Settings and then to Secrets. We will create a few "Repository secrets" now (do not mix them up with the "Environment secrets", we don't want those!)

  5. Go to the Settings tab, then to Actions, then to General. Set Workflow permissions to Read and write permissions.

  6. Run the following command:

     base64 keystore.p12 > out.txt

    And now create secret with the name KEYSTORE_P12, and again paste the content of out.txt.

  7. Then open this page and generate a new GitHub personal access token with the repo scope pre-selected. Set the expiration date to "No expiration" (or really any timeframe on how often you want to manually update this secret). Copy the token and set it as the GH_ACCESS_TOKEN repository secret.

  8. Find the generated keystorepass in fdroid/config.yml and set it to FDROID_STORE_KEYSTORE_PASSWORD repository secret.

That should be it. You can now also generate a new QR code for your repo using online tools, then replace the file in .github/qrcode.png. And of course, you should now add your apps!

Add a new app

Now you can edit the apps.yaml file to include a new app. Usually you just need to input the GitHub link and everything should work:

android:
  git: "https://github.com/bitwarden/android"
  author_name: "bitwarden" # If not set, the owner of the repo will be used
  applications:
    - filename: "com.x8bit.bitwarden-fdroid.apk"
      id: "com.x8bit.bitwarden" # Recommended to be the package name of the app
      name: "Bitwarden"
      categories:
        - Security
      description: |
        Bitwarden is the easiest and safest way to store all of your logins and passwords while conveniently keeping them synced between all of your devices.

        Password theft is a serious problem. The websites and apps that you use are under attack every day. Security breaches occur and your passwords are stolen. When you reuse the same passwords across apps and websites hackers can easily access your email, bank, and other important accounts.

        Security experts recommend that you use a different, randomly generated password for every account that you create. But how do you manage all those passwords? Bitwarden makes it easy for you to create, store, and access your passwords.

        Bitwarden stores all of your logins in an encrypted vault that syncs across all of your devices. Since it's fully encrypted before it ever leaves your device, only you have access to your data. Not even the team at Bitwarden can read your data, even if we wanted to. Your data is sealed with AES-256 bit encryption, salted hashing, and PBKDF2 SHA-256.

        Bitwarden is focused on open source software. The source code for Bitwarden is hosted on GitHub and everyone is free to review, audit, and contribute to the Bitwarden codebase.
      last_updated: "2024-03-22T10:55:53Z" # Optional

    - filename: "com.x8bit.bitwarden.beta-fdroid.apk"
      id: "com.x8bit.bitwarden.beta" # Recommended to be the package name of the app
      name: "Bitwarden Beta"
      categories:
        - Security
      description: |
        Bitwarden is the easiest and safest way to store all of your logins and passwords while conveniently keeping them synced between all of your devices.

        Password theft is a serious problem. The websites and apps that you use are under attack every day. Security breaches occur and your passwords are stolen. When you reuse the same passwords across apps and websites hackers can easily access your email, bank, and other important accounts.

        Security experts recommend that you use a different, randomly generated password for every account that you create. But how do you manage all those passwords? Bitwarden makes it easy for you to create, store, and access your passwords.

        Bitwarden stores all of your logins in an encrypted vault that syncs across all of your devices. Since it's fully encrypted before it ever leaves your device, only you have access to your data. Not even the team at Bitwarden can read your data, even if we wanted to. Your data is sealed with AES-256 bit encryption, salted hashing, and PBKDF2 SHA-256.

        Bitwarden is focused on open source software. The source code for Bitwarden is hosted on GitHub and everyone is free to review, audit, and contribute to the Bitwarden codebase.


authenticator-android:
  ...

If the repository has APK releases, they should be imported into this repo the next time GitHub Actions run.

Metadata and screenshots

Metadata can be added in two places: the apps.yaml file and the app repositories.

Metadata file

Description: As described in Add a new app, you can set a git URL and a description in the apps.yaml file

Categories: A list of categories, preferably one of the categories already listed in the official repo

Metadata from the repository

Screenshots: This tool will make any file from the git repository for which the path contains screenshot available as screenshot. Basically, if you run find . -type f | grep -i screenshot in your app repo you should find all files that will be used.

Changelog: To display a "what's new" changelog in F-Droid, you just need to fill out the body/text of the GitHub release.

License: The License spdx_id given by GitHub. Make sure GitHub recognizes the license type of your app.

Tag line: The tag line of the app shown in F-Droid is the same text as the repository description on GitHub.

Repository URL

When you link to your repository, you can also add the fingerprint to the URL. To get the fingerprint, you need to look at the fdroid command output (or search for the following lines in GitHub Actions):

2021-10-11 06:01:21,726 INFO: Creating signed index with this key (SHA256):
2021-10-11 06:01:21,726 INFO: 08 08 98 AE 43 09 AE CE B5 89 15 E4 3A 4B 7C 4A 3E 2C DA 40 C9 17 38 E2 C0 2F 58 33 9A B2 FB D7

Just remove all spaces from after "INFO" in the second line and you'll end up with your fingerprint:

080898AE4309AECEB58915E43A4B7C4A3E2CDA40C91738E2C02F58339AB2FBD7

Now add it to your repo URL (add a ?fingerprint=, then your key):

https://raw.githubusercontent.com/xarantolus/fdroid/main/fdroid/repo?fingerprint=080898AE4309AECEB58915E43A4B7C4A3E2CDA40C91738E2C02F58339AB2FBD7

You should of course replace the username in the URL. This is the URL your users should add to the F-Droid client. You can also generate a QR code for this URL.