flatpak: add instructions for creating apps/runtimes using flatdeb

Signed-off-by: Arnaud Ferraris <arnaud.ferraris@collabora.com>

content/guides/flatpak.md

 +++
-date = "2021-03-23"
+date = "2021-06-25"
 weight = 100
 toc = true
 
-title = "Application verification using Flatpak"
+title = "Application distribution using Flatpak"
 +++
 
+# Apertis Flatpak demo
+
+Apertis provides a [demo](https://gitlab.apertis.org/infrastructure/apertis-flatdeb-demo)
+Flatpak application. This demo includes a runtime containing the libraries required to run the
+[GNOME Fonts](https://gitlab.gnome.org/GNOME/gnome-font-viewer) application.
+
+In order to install the demo application, the Flatpak repositories for both the
+runtime and application must first be setup:
+
+```
+$ flatpak --user remote-add --no-gpg-verify apertis-demo-runtime https://images.apertis.org/flatpak/runtime
+$ flatpak --user remote-add --no-gpg-verify apertis-demo-app https://images.apertis.org/flatpak/app
+```
+
+You can then proceed with the installation:
+
+```
+$ flatpak --user install org.apertis.demo.gnome_font_viewer
+```
+
+{{% notice warning %}}
+During installation you will be prompted for which version to install. Due to
+incompatibilities between flatpak versions, it is highly recommended you select
+the version corresponding to the Apertis version your system is running.
+{{% /notice %}}
+
+Finally, run the application by executing the following command:
+
+```
+$ flatpak run org.apertis.demo.gnome_font_viewer
+```
+
+# Creation
+
+The preferred way of creating Flatpak runtimes and applications for Apertis is
+by using `flatdeb`, which automates most of the creation process and can
+generate ready-to-use runtimes and applications with a few command invocations.
+
+## Prerequisities
+
+`flatdeb` can be installed by cloning its [Git repository](https://gitlab.apertis.org/pkg/apertis-flatdeb.git)
+and installing its dependencies as mentioned in the
+[README](https://gitlab.apertis.org/pkg/apertis-flatdeb/-/blob/apertis/v2022dev3/README) file.
+
+Once `flatdeb` has been downloaded, create a new folder (outside the `flatdeb`
+source tree) in which you will create your runtime and application.
+
+First you need to create a `suite` definition so `flatdeb` knows which package
+repositories to use. Create a new `suites` folder, then a new file in this folder,
+named after the Apertis version you're targetting: for Apertis `v2022dev2`, the
+file will be `suites/v2022dev2.yaml`. You can simply copy
+[this template file](https://gitlab.apertis.org/infrastructure/apertis-flatdeb-demo/-/blob/master/suites/template.yaml)
+which already contains everything needed for an Apertis suite, and name it
+appropriately.
+
+Once the suite is configured, we need to generate a base chroot for flatdeb to
+work in. From the working directory, please execute the following command:
+
+```
+$ /path/to/apertis-flatdeb/run.py --build-area=$(pwd)/flatdeb-builddir \
+                                  --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \
+                                  --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \
+                                  base
+```
+
+This will create a `flatdeb-builddir` subfolder containing a file named
+`base-<SUITE_NAME>-<TARGET_ARCHITECTURE>.tar.gz` containing the base rootfs
+needed for future operations. If you delete this file, or want to target a
+different Apertis version, you will have to run the above command again.
+
+## Runtime
+
+By using `flatdeb`, one can create and populate a Flatpak runtime by using
+available `.deb` packages. This makes the runtime creation simpler and faster by
+removing the need to build everything from source and automating dependency
+management.
+
+The runtime is described in a yaml file located in a `runtimes` subfolder and
+containing the following elements:
+- `id_prefix`: the runtime unique identifier in [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation)
+- `add_packages`: the list of binary packages to be included in the runtime
+- `add_packages_multiarch`: the list of multiarch-capable packages (typically,
+  those are shared libraries) to be included in the runtime
+- `sdk`: this section also contains `add_packages` and (optionally)
+  `add_packages_multiarch` items; those are the packages needed for building
+  the application, but are not required to run it.
+
+The runtime recipe may also contain a `pre_apt_script` element, used for
+configuring the flatdeb environment before installing the packages. In the demo
+application, this script is used to add the `development` repository, as some of
+the required packages are only present in `development` and not in `target`,
+which happens to be the base system of the runtime.
+
+The packages listed under `add_packages` in the `sdk` section are those needed
+for building the application. That includes development libraries and headers,
+the build system and compilers, and optionally additional development tools.
+
+The packages listed under the main `add_packages*` sections are the runtime
+dependencies of the application. Those are mainly shared libraries, but they can
+also include executables the application would depend on, or even resources for
+making the application more useful. In the demo application, we added a number
+of fonts packages: as this application is a font viewer, we can therefore ensure
+the application can effectively find and display all installed fonts.
+
+Once the runtime recipe is complete, you can generate the runtime with the
+following commands:
+
+```
+$ /path/to/apertis-flatdeb/run.py --build-area=$(pwd)/flatdeb-builddir \
+                                  --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \
+                                  --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \
+                                  --platform runtimes runtimes/<RUNTIME_NAME>.yaml
+$ /path/to/apertis-flatdeb/run.py --build-area=$(pwd)/flatdeb-builddir \
+                                  --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \
+                                  --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \
+                                  --sdk runtimes runtimes/<RUNTIME_NAME>.yaml
+```
+
+This will generate first the `Platform` runtime, which is needed for running the
+application, then the `Sdk` runtime, which is needed for building the
+application. Those will both be stored in an OSTree repository under
+`flatdeb-builddir/ostree-repo`.
+
+## Application
+
+Applications are generated from a more classic
+[Flatpak manifest](https://docs.flatpak.org/en/latest/manifests.html), the only
+notable points here being that:
+- `runtime` must mention your runtime as `<id_prefix>.Platform`
+- the same goes for `sdk` which should contain `<id_prefix>.Sdk`
+- `runtime-version` will contain the suite name (Apertis release)
+
+The manifest should be located under a new subfolder named `apps`.
+
+The application is generated by executing the following command:
+
+```
+$ /path/to/apertis-flatdeb/run.py --build-area=$(pwd)/flatdeb-builddir \
+                                  --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \
+                                  --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \
+                                  app --app-branch=<SUITE_NAME> apps/<APP_NAME>.yaml
+```
+
+Once the command completes, the application will be available from the same OSTree
+repository already containing the runtime, under `flatdeb-builddir/ostree-repo`.
+Serving this directory through an HTTP server is enough to distribute your
+Flatpak runtime and application.
+
+# Verification
+
 Starting with Apertis v2022dev2, [Flatpak](https://flatpak.org) includes the
 ability to distribute [application bundles]( {{< ref "glossary.md#application-bundle" >}} )
 verified with [ed25519](https://ed25519.cr.yp.to/) signatures.
@@ -31,7 +181,7 @@ Please note, however, that GPG signatures are disabled on Apertis. It is still
 possible to pull from GPG-signed repositories, but those signatures won't be
 verified. Similarly, it is not possible to sign flatpak applications using GPG.
 
-# Creating signed flatpak applications
+## Creating signed flatpak applications
 
 The simplest way to create a signed flatpak is to use `flatpak-builder` with
 the `--sign=<SECRETKEY>` command-line argument, where `<SECRETKEY>` is the
@@ -60,9 +210,9 @@ multiple signatures of each object.
 More details about those commands are available in the
 [Flatpak documentation](https://docs.flatpak.org/en/latest/building.html).
 
-# Publishing signed flatpaks applications
+## Publishing signed flatpaks applications
 
-## Publishing a repository
+### Publishing a repository
 
 When distributing several applications, it can be useful to publish the whole
 repository using a [.flatpakrepo](https://docs.flatpak.org/en/latest/hosting-a-repository.html#flatpakrepo-files)
@@ -85,7 +235,7 @@ Icon=https://example.org/flatpak/icon.svg
 SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
 ```
 
-## Publishing a single application
+### Publishing a single application
 
 One convenient way to distribute single flatpak applications is to use
 [.flatpakref](https://docs.flatpak.org/en/latest/repositories.html#flatpakref-files)
@@ -112,7 +262,7 @@ IsRuntime=false
 SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
 ```
 
-## Publishing a bundle
+### Publishing a bundle
 
 Flatpak applications can also be distributed as
 [single-file bundles](https://docs.flatpak.org/en/latest/single-file-bundles.html),
@@ -129,9 +279,9 @@ has to be stored in a location easily accessible to the final user for signature
 verification, as the bundle file itself is signed and doesn't provide any mean
 to retrieve the associated public key.
 
-# Installing a signed flatpak
+## Installing a signed flatpak
 
-## Configuring a remote repository
+### Configuring a remote repository
 
 If the repository publisher provides a `.flatpakrepo` file including the public key,
 then no action is needed other than running `flatpak remote-add <REPONAME> <REPOFILE>`.
@@ -165,7 +315,7 @@ expected.
 
 This option can also be added when using the `flatpak remote-modify` command.
 
-## Installing a signed application
+### Installing a signed application
 
 Similarly to the process of using `.flatpakrepo` files, when installing a single
 application using a `.flatpakref` file including the public key, no additional
@@ -191,7 +341,7 @@ configuration, one can also use the `--sign-verify` command-line option:
 flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= org.example.sampleapplication
 ```
 
-## Installing a signed bundle
+### Installing a signed bundle
 
 Flatpak bundles are not installed from a repository like most flatpak
 applications, but from a single, optionally signed, file. As there is no