Hosting Flatpak Content in OCI Format

Pulp can host Flatpak application and runtime images that are distributed in OCI format. To make such content discoverable, it can provide /index/dynamic and /index/static endpoints as specified by the Flatpak registry index protocol. This is not enabled by default. To enable it, define FLATPAK_INDEX = True in the settings file.

Clients like the flatpak command-line tool or the GNOME Software application will typically query the /index/static endpoint, which is intended to be called repeatedly with identical query parameters, and whose responses are meant to be cached. The /index/dynamic endpoint serves exactly the same content, but is intended for one-off requests that should not be cached. These endpoints can be accessed without authentication. They only provide information about public repositories.

The two endpoints support a number of query parameters (architecture, tag, label, etc.), see the protocol specification for details. Two notes:

  • Every request must include a label:org.flatpak.ref:exists=1 query parameter. This acts as a marker to only report Flatpak content, and to exclude other container content that may also be provided by the Pulp instance.

  • This implementation does not support annotations. Including any annotation query parameters will result in a 400 failure response. Use label query parameters instead. (Existing clients like the flatpak command-line tool never issue requests including any annotation query parameters.)

Install a Flatpak image from Pulp

This section assumes that you have created at least one public distribution in your Pulp instance that serves a repository containing Flatpak content. To do this, see the general Host and Consume a Repository documentation.

You can for example use the flatpak command-line tool to set up a Flatpak remote (named pulp here) that references your Pulp instance:

flatpak remote-add pulp oci+"$BASE_ADDR"

Then, use

flatpak remote-ls pulp

to retrieve a list of all Flatpak applications and runtimes that your Pulp instance serves. (This queries the /index/static endpoint, as explained above.) Finally, if your Pulp instance serves e.g. the org.gnome.gedit application, use

flatpak install pulp org.gnome.gedit

to install it and run it with

flatpak run org.gnome.gedit