[PATCH v6 7/8] Documentation: Update support

[Demi Marie Obenour <demiobenour@gmail.com>]

The documentation previously stated that updates were not possible
without reinstalling.  This is still the case by default, but it is
possible for developers to enable updates for images they build.
Update the documentaion to reflect this.

Signed-off-by: Demi Marie Obenour <demiobenour@gmail.com>
---
Changes since v4:
- Move the documentation from the user section to the developer section.
Changes since v2:
- Move the documentation on how to enable updates to the part on build
  configuration.
- Clarify what happens if an update is interrupted.
- Move details to a technical note.
- Link to systemd-sysupdate.
---
 Documentation/development/build-configuration.adoc | 15 ++++++++
 Documentation/development/index.adoc               |  2 ++
 Documentation/development/updates.adoc             | 42 ++++++++++++++++++++++
 Documentation/installation/index.adoc              |  6 +++-
 4 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/Documentation/development/build-configuration.adoc b/Documentation/development/build-configuration.adoc
index 545aa8c05ac40a101b5ee280015cde7ec4f3a66f..49651d05890900b74cafb3d75945b3bcc5b86ce6 100644
--- a/Documentation/development/build-configuration.adoc
+++ b/Documentation/development/build-configuration.adoc
@@ -20,6 +20,21 @@ The configuration file should contain an attribute set.  See
 https://spectrum-os.org/git/spectrum/tree/lib/config.default.nix[lib/config.default.nix]
 for supported configuration attributes and their default values.
 
+To enable updates, you need to specify a version, an update URL, and an update signing key.
+By default, the update URL is set to a .invalid domain and the update signing key is
+an invalid key.  Therefore, updates will not work.  To enable updates, provide a valid key
+and update server URL.
+
+Spectrum uses https://www.freedesktop.org/software/systemd/man/latest/systemd-sysupdate.html[systemd-sysupdate],
+so see the https://www.freedesktop.org/software/systemd/man/latest/sysupdate.d.html[sysupdate.d]
+documentation for what you need to put on your server.  Building
+https://spectrum-os.org/git/spectrum/tree/release/updates.nix[release/updates.nix] produces an
+directory that is compatible with systemd-sysupdate, except that the signature
+(`SHA256SUMS.sha256.asc`) is missing.
+
+Updates are signed, so the worst a compromised update
+server can do is fill up your user data partition.
+
 .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay]
 [example]
 [source,nix]
diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
index 6b48418ba218354ee0493cd82188c54141f63e9e..4e504253dc16286273e1af5cae9614789b2c4a12 100644
--- a/Documentation/development/index.adoc
+++ b/Documentation/development/index.adoc
@@ -18,6 +18,8 @@ Spectrum is free software, currently under active development.
 TIP: For information on writing guidelines,
 see xref:../contributing/writing_documentation.adoc[Documentation Style Guide].
 
+If you want to update Spectrum without reinstalling, see how to
+xref:updates.adoc[Enable updates].
 
 == Mailing Lists
 
diff --git a/Documentation/development/updates.adoc b/Documentation/development/updates.adoc
new file mode 100644
index 0000000000000000000000000000000000000000..8746f97e5d9b36d4960a64544af08f57ff89ce9a
--- /dev/null
+++ b/Documentation/development/updates.adoc
@@ -0,0 +1,42 @@
+= Updating the OS
+:page-parent: Development
+
+// SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Right now, there is no official update server or update signing key.
+However, it is possible to run your own update server.  See
+xref:../development/build-configuration.adoc[build configuration]
+for how to enable updates for your own Spectrum images.
+
+== Updating the system
+
+If you have built your image with updates enabled, you can update the
+system using the `spectrum-update` command.  This takes the path to a
+staging directory as argument.  This directory must be on a BTRFS
+filesystem.  It is strongly recommended to not use this directory
+for any other purpose.  However, it's safe to rename the directory
+and use `spectrum-update` with the new path afterwards.
+
+If there is a problem with the update, it's safe to try again.
+If that still doesn't work, you can delete the directory and
+try again with an empty one.  This will cause `spectrum-update`
+to download the latest version even if it is already installed, but
+is otherwise harmless.
+
+Updates are atomic and take effect after the system reboots.
+If the system is rebooted, crashes, or loses power during an
+update, the update will not take effect.  It is safe to resume
+an interrupted update.
+
+Since Spectrum's host has no network access, the VM that does the
+updates (`sys.appvm-systemd-sysupdate`) is given a BTRFS subvolume to
+write the updates into.  It uses `systemd-sysupdate` to download the updates
+into this directory.  Once it exits, the host snapshots this directory and
+checks it for malicious filenames or non-regular files.  If the check
+passes, this directory is used as the source for `systemd-sysupdate`,
+which installs the updates to the OS volume and EFI system partition.
+
+See the documentation of
+https://www.freedesktop.org/software/systemd/man/systemd-sysupdate.html[systemd-sysupdate].
+for some of the details.
diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
index d67c88dda062066c19c3b21e699f074cc18a6dbc..d1df2edc9b0ca902824ff729eec139270fb40777 100644
--- a/Documentation/installation/index.adoc
+++ b/Documentation/installation/index.adoc
@@ -18,6 +18,10 @@ development.
 
 == Uninstalling and Updating
 
-Currently, there is no implementation for a software update.
+Software updates are a work in progress and are not currently available.
+
+If you built Spectrum yourself, see
+xref:../development/build-configuration.adoc[Build configuration] for how
+to enable updates for it.
 
 You can replace Spectrum by installing another OS.

-- 
2.52.0