[PATCH v2 7/8] Documentation: Update support

Demi Marie Obenour
2025-11-12T22:18:37Z

There is now a way to update the OS, so the previous documentation is
now stale!

Signed-off-by: Demi Marie Obenour <demiobenour@gmail.com>
---
Documentation/installation/index.adoc | 3 ++-
Documentation/using-spectrum/index.adoc | 2 ++
Documentation/using-spectrum/updates.adoc | 29 +++++++++++++++++++++++++++++
3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
index d67c88dda062066c19c3b21e699f074cc18a6dbc..536c3dd9f78faa2ecad4127dc9ccc2058a230b1a 100644
--- a/Documentation/installation/index.adoc
+++ b/Documentation/installation/index.adoc
@@ -18,6 +18,7 @@ development.

== Uninstalling and Updating

-Currently, there is no implementation for a software update.
+See xref:../using-spectrum/updates.adoc[Updating the OS] for how to enable
+updates.

You can replace Spectrum by installing another OS.
diff --git a/Documentation/using-spectrum/index.adoc b/Documentation/using-spectrum/index.adoc
index 25347a4ed7bb1f899ee0a3b85aa51da94bb954b4..5d9ea657f7c6f8c21edbf8637d2d2d0bf52f931d 100644
--- a/Documentation/using-spectrum/index.adoc
+++ b/Documentation/using-spectrum/index.adoc
@@ -11,3 +11,5 @@ Ready to get started with Spectrum? Here is what you can do next:

* xref:running-vms.adoc[Start some applications].
* xref:creating-custom-vms.adoc[Create your own VM] to use other applications.
+* xref:updates.adoc[Enable updates] so you can use newer versions of Spectrum
+ without reinstalling the OS.
diff --git a/Documentation/using-spectrum/updates.adoc b/Documentation/using-spectrum/updates.adoc
new file mode 100644
index 0000000000000000000000000000000000000000..ffd6fda269617768d486e58e30661bbefc8b2bbd
--- /dev/null
+++ b/Documentation/using-spectrum/updates.adoc
@@ -0,0 +1,29 @@
+= Updating the OS
+:page-parent: Using Spectrum
+
+// 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
+
+Spectrum supports updates via the `update` command. This
+takes the path to a staging directory as argument. `update`
+will create the directory, use it for the update, and then
+delete it. The parent directory must exist.
+
+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 automatically be rolled back. Updates
+are digitally signed and Spectrum will refuse to install an
+update that does not have a trusted signature.
+
+Currently, Spectrum does not provide an update server, so
+you must provide your own. You can do this via
+xref:../development/build-configuration.adoc[build configuration].
+The default sets the signing key to `/dev/null` and the server
+URL to an invalid value, so updates won't work. To enable updates,
+set `update-url` to the URL of your server and `update-signing-key`
+to a binary GnuPG keyring to verify the updates with. Not all possible
+URLs will work, but most invalid URLs will cause an error during the
+build rather than runtime misbehavior.
+
+Right now, it is not possible to change the update URL or signing key
+except via an update or by reinstalling the OS.

--
2.51.2