Re: [PATCH v2 7/8] Documentation: Update support

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

[-- Attachment #1.1.1: Type: text/plain, Size: 5142 bytes --]

On 11/13/25 11:49, Alyssa Ross wrote:
> 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.

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

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)

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 7253 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]