add documentation for the pkgs.portableService tool (#193081)

* add documentation for the pkgs.portableService tool

as introduced in 499aebcf340

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

2 files changed, 82 insertions, 0 deletions

diff --git a/doc/builders/images.xml b/doc/builders/images.xml
index cd10d69a96d..f86ebd86bee 100644
--- a/doc/builders/images.xml
+++ b/doc/builders/images.xml
@@ -9,4 +9,5 @@
  <xi:include href="images/dockertools.section.xml" />
  <xi:include href="images/ocitools.section.xml" />
  <xi:include href="images/snaptools.section.xml" />
+ <xi:include href="images/portableservice.section.xml" />
 </chapter>
diff --git a/doc/builders/images/portableservice.section.md b/doc/builders/images/portableservice.section.md
new file mode 100644
index 00000000000..1d23cafeefc
--- /dev/null
+++ b/doc/builders/images/portableservice.section.md
@@ -0,0 +1,81 @@
+# pkgs.portableService {#sec-pkgs-portableService}
+
+`pkgs.portableService` is a function to create _portable service images_,
+as read-only, immutable, `squashfs` archives.
+
+systemd supports a concept of [Portable Services](https://systemd.io/PORTABLE_SERVICES/).
+Portable Services are a delivery method for system services that uses two specific features of container management:
+
+* Applications are bundled. I.e. multiple services, their binaries and
+  all their dependencies are packaged in an image, and are run directly from it.
+* Stricter default security policies, i.e. sandboxing of applications.
+
+This allows using Nix to build images which can be run on many recent Linux distributions.
+
+The primary tool for interacting with Portable Services is `portablectl`,
+and they are managed by the `systemd-portabled` system service.
+
+:::{.note}
+Portable services are supported starting with systemd 239 (released on 2018-06-22).
+:::
+
+A very simple example of using `portableService` is described below:
+
+[]{#ex-pkgs-portableService}
+
+```nix
+pkgs.portableService {
+  pname = "demo";
+  version = "1.0";
+  units = [ demo-service demo-socket ];
+}
+```
+
+The above example will build an squashfs archive image in `result/$pname_$version.raw`. The image will contain the
+file system structure as required by the portable service specification, and a subset of the Nix store with all the
+dependencies of the two derivations in the `units` list.
+`units` must be a list of derivations, and their names must be prefixed with the service name (`"demo"` in this case).
+Otherwise `systemd-portabled` will ignore them.
+
+:::{.Note}
+The `.raw` file extension of the image is required by the portable services specification.
+:::
+
+Some other options available are:
+- `description`, `homepage`
+
+  Are added to the `/etc/os-release` in the image and are shown by the portable services tooling.
+  Default to empty values, not added to os-release.
+- `symlinks`
+
+  A list of attribute sets {object, symlink}. Symlinks will be created  in the root filesystem of the image to
+  objects in the Nix store. Defaults to an empty list.
+- `contents`
+
+  A list of additional derivations to be included in the image Nix store, as-is. Defaults to an empty list.
+- `squashfsTools`
+
+  Defaults to `pkgs.squashfsTools`, allows you to override the package that provides `mksquashfs`.
+- `squash-compression`, `squash-block-size`
+
+  Options to `mksquashfs`. Default to `"xz -Xdict-size 100%"` and `"1M"` respectively.
+
+A typical usage of `symlinks` would be:
+```nix
+  symlinks = [
+    { object = "${pkgs.cacert}/etc/ssl"; symlink = "/etc/ssl"; }
+    { object = "${pkgs.bash}/bin/bash"; symlink = "/bin/sh"; }
+    { object = "${pkgs.php}/bin/php"; symlink = "/usr/bin/php"; }
+  ];
+```
+to create these symlinks for legacy applications that assume them existing globally.
+
+Once the image is created, and deployed on a host in `/var/lib/portables/`, you can attach the image and run the service. As root run:
+```console
+portablectl attach demo_1.0.raw
+systemctl enable --now demo.socket
+systemctl enable --now demo.service
+```
+:::{.Note}
+See the [man page](https://www.freedesktop.org/software/systemd/man/portablectl.html) of `portablectl` for more info on its usage.
+:::