Demi Marie Obenour <demiobenour@gmail.com> writes:

> 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.

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.

>  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.

> 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.

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?

> +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.

> +
> +Right now, it is not possible to change the update URL or signing key
> +except via an update or by reinstalling the OS.