/appimage.github.io

Given an URL to an AppImage, the GitHub action in this project inspects the AppImage and puts it into a community-maintained catalog

Primary LanguageShellOtherNOASSERTION

This is...

  • A crowd-sourced directory of available, reviewed AppImages with data that 3rd party app stores and software centers can use. Given a URL to an AppImage, it inspects the AppImage and puts it into a community-maintained catalog. The idea is that all the metadata travels inside the AppImage, so besides adding a URL to this repository no additional information is asked, since it comes with the AppImage itself.

This is NOT...

  • A distribution. appimage.github.io does not distribute AppImages or provide them for download. It simply links to the respective author's download pages, from where users will be able to download AppImages. It also does not keep track of versions, only of channels such as "release", "beta", "nightly", "continuous" (as defined by the upstream application authors). We think that trying to keep track of all versions in a central repository is futile, since it does not scale.
  • A guarantee of any sorts. While we check that an AppImage follows basic AppImage conventions and that it can run on the oldest still-supported LTS release of Ubuntu, this is basically all we check for right now. No explicit or implied guarantees whatsoever. Use at your own risk and only run applications from authors you trust. We do not imply that you should trust applications or their authors just because they are listed here.

User stories

  • "As a user, I would like to have a central catalog of available AppImages that I can download directly from the application authors, so that I know what is available."
  • "As a developer, I would like to make my application known to as many potential users as possible in order to increase my user base."
  • "As an app center or app store developer, I would like to get information about the available AppImages easily, so that I can focus on building my app center or app store rather than having to crawl the Internet for AppImages myself."

How to submit AppImages to the catalog

Create a new file using

and send a Pull Request.

The file should contain one line with a link to the GitHub repository that hosts AppImages on its Releases page.

Alternatively, a link to the AppImage. Nothing else.

Ideally, the file in data/ contains a link to https://github.com/User/App/ (not to a specific AppImage!), and if the AppImage follows the standard nomenclature, then https://github.com/User/App/releases/whatever/App-1.0-x86_64.AppImage, https://github.com/User/App/releases/whatever/App-1.1-x86_64.AppImage,... will automatically be picked up.

Standard nomenclature:

  • AppImage filename consists of pieces: Application name, hyphen, version, hyphen, architecture, dot, AppImage suffix
  • First piece of the AppImage filename, "App" == name of the repo
  • Blanks in the app name become _
  • Respect uppercase. If the app is called "App", do NOT use "app"
  • Example: App-1.1-x86_64.AppImage in a repo called "App"

Then send a Pull Request to this repository. GitHub Actions will instantly perform an automated review of the AppImage, and in case it succeeds, you will see a green result in your pull request. If you get a red result, check the log of the GitHub Actions build, and fix it.

Then the autodetection works.

Checklist for submitting your own AppImage

As a format, AppImage is designed in a way that does not impose restrictions on the person generating AppImages. Basically you are free to put inside an AppImage whatever you want. For appimage.github.io, however, additional rules apply. AppImages submitted to AppImage hub undergo automatic and possibly additional manual review.

  • Must be downloadable from a URL. Our testing system fetches the AppImage using wget. Currently we cannot get AppImages from locations behind authentication and/or cookie-protected locations. For commercial applications we recommend to have a generally downloadable demo/trial version. Please contact us if you would like to add your commercial AppImage to the directory and it is not available for general download
  • Must run on the oldest still-supported Ubuntu LTS release without the installation of additional packages. Targeting the oldest still-supported LTS is to ensure that the AppImage will run not only on the very latest, but also on older target systems, such as enterprise distributions (not limited to Ubuntu)
  • Must execute in our GitHub Actions based testing environment
  • Must pass appdir-lint.sh
  • Must have a desktop file that passes desktop-file-validate
  • Must run without active Internet connection (and at least show some information)
  • Should have an AppStream metainfo file in usr/share/metainfo. If it does, must pass appstreamcli validation
  • Should show a useful screen rather than some crude dialog box since the main window will be used for the main screenshots. Note that you can provide your own screenshots by using an AppStream metainfo file
  • Should be available under a constant URL that does not contain the version number. Alternatively, should be available on GitHub Releases or the openSUSE Build Service (you are free to suggest additional serices like these)
  • Must display something sensible when there is no network connection (offline/air-gapped use). Electron apps, for example, can use something like
  (async () => {
    if (await isOnline() === true) {
      mainWindow.loadURL(HermesURL);
    } else {
      mainWindow.loadFile('offline.html')
    }
    mainWindow.maximize();
    mainWindow.show();
  })();

How to use

App stores and software centers can consume the metadata collected by this project. See AppImage ecosystem.

peek 2017-11-26 11-28

Currently we are providing a JSON feed at https://appimage.github.io/feed.json. If you would like to use this data but need changes, please contact us on #AppImage at irc.libera.chat, so that we can discuss an output format that would serve your needs best. PLEASE NOTE that the data output format is not finalized yet and is subject to change any time without prior notice, until we release a stable version of it.

Projects using this data

Here are some examples of projects using this data, to illustrate on how you can use this data in your own projects:

Please contact us (or send a pull request) if you are using this data so that we can list your project here.