Document package layering via systemd (#294)

modules/ROOT/nav.adoc

@@ -26,6 +26,7 @@
 ** xref:running-containers.adoc[Running Containers]
 ** xref:authentication.adoc[Configuring Users and Groups]
 ** xref:hostname.adoc[Setting a Hostname]
+** xref:layering-packages.adoc[Layering packages on the host system]
 ** xref:customize-nic.adoc[How to Customize a NIC Name]
 ** xref:sysconfig-configure-swaponzram.adoc[Configuring SwapOnZRAM]
 ** xref:sysconfig-configure-wireguard.adoc[Configuring WireGuard]

modules/ROOT/pages/layering-packages.adoc

@@ -0,0 +1,59 @@
+= Layering packages on the host system
+
+To make other software accessible on the host system installation you can use https://coreos.github.io/rpm-ostree/[`rpm-ostree install`] to layer rpm packages. By default, packages are downloaded from the https://docs.fedoraproject.org/en-US/quick-docs/repositories/[Fedora repositories].
+
+[NOTE]
+====
+It is recommended to use layering only if there is no other possible containerisation option.
+The intention of Fedora CoreOS is to keep the base image as simple and small as possible for security and maintainability reasons. That is why you should in general prefer the usage of `podman` containers over layering software.
+====
+
+To start the layering of a package, you need to write a systemd unit that executes the `rpm-ostree` command to install the wanted package(s). 
+Changes are applied to a new deployment and a reboot is necessary for those to take effect.
+
+== Example: Layering nano and setting it as the default editor
+
+This example shows on how to install the text editor `nano` and add a script to `/etc/profile.d` so that it is set as the default editor for all users.
+The parameter `--allow-inactive` is useful if the package is added to the root image in a future Fedora CoreOS release. In such a case, the parameter prevents that the service would fail.
+
+NOTE: In the future, we will have a more Ignition-friendly method of doing this with stronger guarantees. See upstream issues https://github.com/coreos/butane/issues/81[butane#81] and https://github.com/coreos/fedora-coreos-tracker/issues/681[fedora-coreos-tracker#681] for more information.
+
+NOTE: The `After=systemd-machine-id-commit.service` directive is important in the following examples to avoid some subtle issues. Similarly, any `ConditionFirstBoot=true` services should use `Before=first-boot-complete.target systemd-machine-id-commit.service`. See https://github.com/systemd/systemd/blob/3045c416e1cbbd8ab40577790522217fd1b9cb3b/man/systemd.unit.xml#L1315[the systemd documentation] for more details.
+
+[source,yaml]
+----
+variant: fcos
+version: 1.3.0
+systemd:
+  units:
+    # installing nano as a layered package with rpm-ostree
+    - name: rpm-ostree-install-nano.service
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Layer nano with rpm-ostree
+        # We run after `systemd-machine-id-commit.service` to ensure that
+        # `ConditionFirstBoot=true` services won't rerun on the next boot.
+        After=systemd-machine-id-commit.service
+        After=network-online.target
+        ConditionPathExists=!/var/lib/rpm-ostree-install-nano.stamp
+
+        [Service]
+        Type=oneshot
+        RemainAfterExit=yes
+        ExecStart=/usr/bin/rpm-ostree install --allow-inactive nano
+        ExecStart=/bin/touch /var/lib/rpm-ostree-install-nano.stamp
+        ExecStart=/bin/systemctl --no-block reboot
+
+        [Install]
+        WantedBy=multi-user.target
+storage:
+  files:
+    # use nano as default editor
+    - path: /etc/profile.d/nano.sh
+      overwrite: true
+      contents:
+        inline: |
+          #/bin/sh
+          export EDITOR=nano
+----