flatpak: Add more information on hosting signed repositories

This now covers the basics of using the current `ostree-push` version.

https://phabricator.apertis.org/T8173



Signed-off-by: Ryan Gonzalez <ryan.gonzalez@collabora.com>

content/guides/flatpak.md

@@ -456,8 +456,7 @@ $ flatdeb --build-area=$(pwd)/flatdeb-builddir \
 
 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.
+`flatdeb-builddir/ostree-repo`.
 
 As with runtimes, if building for the host's architecture, then `--arch=` can be
 omitted.
@@ -487,9 +486,10 @@ Flatpak application signatures occur on several levels:
   * whole repositories
   * single-file bundles
 
-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.
+Please note, however, that GPG signatures, the upstream default, 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
 
@@ -520,17 +520,98 @@ 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
 
 ### 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)
-file.
+When distributing several applications and their runtimes, it can be useful to
+publish the whole repository.
+
+#### Hosting the repository
+
+Depending on whether `apertis-flatdeb` or `flatpak-builder` is used, the
+repository will be stored in the folder specified by either the `--ostree-repo`
+or `--repo` command-line argument, respectively. In its simplest form, hosting
+the repository can simply be placing its contents as-is on a remote server.
+
+However, uploading the data to the server is somewhat sensitive: during the
+upload process, some files in the OSTree repository may be present before the
+files they in turn depend on. Thus, the repository may turn out to be unusable
+until the upload completes. In order to remedy this, a tool named `ostree-push`
+can be used, which will upload the repository files in a well-defined order to
+the remote server over SSH.
+
+When using `ostree-push`, it's recommended to pull down the contents of the
+remote repository *before* building the runtimes or apps in question via
+`flatdeb` or `flatpak-builder`:
+
+```
+$ ostree init --repo=repo
+$ ostree remote --repo=repo --sign-verify=ed25519=inline:<PUBLICKEY> \
+    --if-not-exists origin https://example.org/flatpak/repo
+$ ostree pull --repo=repo --depth=-1 --mirror origin <REFS>...
+```
+
+where `<PUBLICKEY>` is the base64-encoded public Ed25519 key, and `<REFS>`
+contains the references that will later be uploaded. For instance, for the
+runtime `org.test.Platform/x86_64/v2022` and app `org.test.App/x86_64/v2022pre`,
+the following `pull` command would be used:
+
+```
+$ ostree pull --repo=repo --depth=-1 --mirror origin \
+    runtime/org.test.Platform/x86_64/v2022 \
+    app/org.test.Platform/x86_64/v2022
+```
+
+(Note the `runtime/` and `app/` prefix.)
+
+After the build process is completed, the newly built items can be uploaded via
+the following:
+
+```
+$ ostree-push --repo repo ssh://<USER>@<HOST>:<PORT>/<PATH> <REFS>...
+```
+
+where:
+
+- `<HOST>` is the SSH server to connect to
+- `<USER>` is the user to sign in as on the server
+- `<PORT>` is the port the SSH server is running on (`:<PORT>` may be omitted
+  entirely if the default port of 22 is used)
+- `<REFS>` is identical to as mentioned previously for `ostree pull`
+
+Continuing the previous example, if we now wanted push the same refs to
+`/var/public/repo` on an SSH server `ssh.test.com`, port `2022`, logging in as
+the user `archive`, the command used would be the following:
+
+```
+$ ostree-push --repo repo ssh://archive@ssh.test.com:2022/var/public/repo \
+    runtime/org.test.Platform/x86_64/v2022 \
+    app/org.test.Platform/x86_64/v2022
+```
+
+After `ostree-push` is run, the summary file (essentially an index file for the
+repository) will need to be rebuilt. This can be accomplished by running the
+following on the server containing the repository:
+
+```
+$ flatpak build-update-repo --sign=<SECRETKEY> <REPO>
+```
+
+where `<SECRETKEY>` is the base64-encoded secret Ed25519 key and `<REPO>` is the
+path to the repository. One can pass `--generate-static-deltas` in order to make
+pulling from the repository faster, at the expense of taking up more storage
+space on the host system.
+
+#### Making the repository publicly accessible
+
+In order for the repository to easily be added to client systems, a
+[.flatpakrepo](https://docs.flatpak.org/en/latest/hosting-a-repository.html#flatpakrepo-files)
+file can be used.
 
-The only difference here is that the `GPGKey=...` line must be replaced with
-`SignatureKey=<PUBLICKEY>`, where `<PUBLICKEY>` is the base64-encoded public
-Ed25519 key.
+The only difference here compared to the linked documentation is that the
+`GPGKey=...` line must be replaced with `SignatureKey=<PUBLICKEY>`, where
+`<PUBLICKEY>` is the base64-encoded public Ed25519 key.
 
 Such a .flatpakrepo file could be:
 
@@ -545,9 +626,10 @@ Icon=https://example.org/flatpak/icon.svg
 SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
 ```
 
-### Publishing a single application
+#### Making a single application accessible
 
-One convenient way to distribute single flatpak applications is to use
+One way to make installing a single flatpak application from a repository
+convenient is to use
 [.flatpakref](https://docs.flatpak.org/en/latest/repositories.html#flatpakref-files)
 files. Those files include all necessary information for flatpak to be able to
 install and update the application.