On 11/13/25 11:49, Alyssa Ross wrote: > Demi Marie Obenour writes: > >> There is now a way to update the OS, so the previous documentation is >> now stale! >> >> Signed-off-by: Demi Marie Obenour >> --- >> 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. > > Let's phrase this so it says that there's work going on to enable > updates but it's not all set up yet. User-focused documentation > shouldn't really be suggesting that people will have to build their own > images and run their own update servers. Would it be okay to mention that it is WIP, and also add a link to the build configuration options for those who *have* built their own images? That will continue to be relevant even after official binary releases are available. Developers are users too, and they might be a bit confused when their image either doesn't update at all or updates to an official build without any of their changes. >> 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. > > This doesn't really belong in the "Using Spectrum" section, because > people who're only using Spectrum should have working updates out of the > box. It would make more sense to be documented alongside the > configuration mechanism — that's the audience for this. I'll add the info to the build configuration mechanism. >> 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 >> +// 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. > > And be on btrfs? > >> + >> +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 > > Is this currently true? If not, that's a systemd-sysupdate bug. >> +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. > > We should probably reference systemd-sysupdate so people can understand > what their update server is supposed to serve, without us having to > duplicate that information in our own documentation. Good idea. >> + >> +Right now, it is not possible to change the update URL or signing key >> +except via an update or by reinstalling the OS. This is actually stale. It was true in v1 because some of this information was hard-coded into the update VM, but now all of that information comes from the host. -- Sincerely, Demi Marie Obenour (she/her/hers)