Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

Docs: updating LordOS in place (docs/UPDATES.md), release steps for the APT repository, FAQ

Federico Pereira85e62aaa328e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4320a7..d1df8cb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,27 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
CPU time, threads, context switches, page faults, start time, nice, control group and LordOS
restrictions), open files and ports (with the addresses of each socket), the executable and the
command line, updated every second ([docs/MONITOR.md](docs/MONITOR.md#process-actions-081)).
+- **Update LordOS from the Store, without reinstalling.** Store → Updates now shows "LordOS
+ <version> is available" with the release notes and an Update button, next to Debian's updates;
+ files, settings and accounts are kept, and a "Restart required" notice appears when the new
+ version (or a new kernel) is installed. It works the same on the ISO install, the Raspberry Pi
+ image, Debian with `install.sh` and servers, and `sudo apt update && sudo apt upgrade` does the
+ same. An optional daily check (on by default, never installs anything) notifies when something
+ new is available ([docs/UPDATES.md](docs/UPDATES.md)).
+- **A signed LordOS package repository** at `https://lordos.org/apt` (suite `stable`, amd64 and
+ arm64), signed with a dedicated OpenPGP key (Ed25519, fingerprint
+ `1DDA F390 107D F264 FA8A 0918 3972 CC6D E4DA 2336`) shipped as
+ `/usr/share/keyrings/lordos-archive-keyring.gpg`; the `lordos` package adds
+ `/etc/apt/sources.list.d/lordos.sources` and removes it when uninstalled. Built and signed on the
+ maintainer's machine by `tools/release/apt-repo.sh`, tested on a staging path first.
+- **Migrations between versions.** The package's `postinst` applies each version's system changes
+ once and in order (`/usr/lib/lordos/migrate`, `packaging/migrations/`), so skipping versions
+ converges to the same state; each user's settings get the same treatment at login
+ (`sdk/settings.js`). The first two enable per-app network permissions where they were left off,
+ and keep root's SSH key login on servers upgraded from 0.8.0 (0.8.1 turns root login off).
+- **Local repositories in the package engine:** a `file:/path` source (a disk or a USB stick) is
+ read like a download, as `nobody`, and checked the same way.
+
- **`tools/diag/keylag.sh`: where does the typing delay come from?** In two minutes it reports the
composition mode, the VM and its guest tools and Chromium's complaints, and with
`lordos.inputdebug=1` on the kernel line (one boot, root only) it times each stage of a key in
@@ -145,6 +166,16 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
suggests a display that works; `vmwgfx` only loads on VMware itself, so the console stays
visible elsewhere.
+### Upgrading
+
+- **From 0.8.0 (once):** run `curl -fsSL https://lordos.org/install.sh | sh` again. It upgrades in
+ place (keeps users, settings and the login setup) and its package adds the LordOS repository;
+ from then on new versions come through Store → Updates or `apt`. Or add the repository by hand and
+ `sudo apt update && sudo apt install lordos` ([docs/UPDATES.md](docs/UPDATES.md#how-a-system-gets-the-repository)).
+- On a server administered as root with an SSH key, the upgrade keeps root's key login
+ (`/etc/ssh/sshd_config.d/09-lordos-root-keys.conf`) even though 0.8.1's default is no root login;
+ delete that file to apply the default.
+
## [0.8.0-beta] - 2026-10-18
LordOS is a free GNU/Linux distribution based on Debian 13 ("trixie") with its own desktop
diff --git a/docs/INSTALL-DEBIAN.md b/docs/INSTALL-DEBIAN.md
index de6e919..8d138c1 100644
--- a/docs/INSTALL-DEBIAN.md
+++ b/docs/INSTALL-DEBIAN.md
@@ -176,6 +176,16 @@ machine reachable from the internet:
`--uninstall` removes `/etc/lordos/remote/config`, so the port is closed.
+## Updating
+
+The package adds the signed LordOS repository (`/etc/apt/sources.list.d/lordos.sources`, key
+`/usr/share/keyrings/lordos-archive-keyring.gpg`), so new versions arrive in place: Store → Updates
+shows "LordOS <version> is available", or `sudo apt update && sudo apt upgrade` does the same. Files,
+settings, users and the login setup are kept, and the package applies whatever each version changes
+in the system ([UPDATES.md](UPDATES.md)). Running `install.sh` again also upgrades in place; it is
+the one-time step for LordOS 0.8.0, whose package does not have the repository yet. Uninstalling
+removes the repository with the package.
+
## Uninstalling
```sh
diff --git a/docs/PACKAGES.md b/docs/PACKAGES.md
index f27609f..9013b6b 100644
--- a/docs/PACKAGES.md
+++ b/docs/PACKAGES.md
@@ -39,7 +39,11 @@ The code is in `server/src/pkg/`:
- **HTTP instead of HTTPS.** LordOS has no TLS of its own, so `https://` sources are downloaded
over `http://`, with the same path. Security comes from the signatures and the SHA-256 hashes,
as with apt and `http://deb.debian.org`. Someone watching the network can see which packages
- are downloaded, but can't change them.
+ are downloaded, but can't change them. (So a repository on a CDN must serve plain HTTP as is,
+ not redirect it: [UPDATES.md](UPDATES.md), "Serving it".)
+- **Local repositories.** A `file:/path` source (a repository on a disk or a USB stick, like apt's
+ `file:` method) is read by the same unprivileged child, as `nobody`: only world-readable files,
+ checked exactly like a download. An HTTP redirect can never lead to a `file:` URL.
- **Downloads without root.** The process that talks to the network drops privileges before
connecting: it becomes `nobody`, with no groups, with `no_new_privs` and no way back to root.
It passes the bytes to the root process through a pipe. The root process only writes them into
@@ -67,6 +71,7 @@ The code is in `server/src/pkg/`:
| `/var/lib/lordos/pkg/lists/` | Verified `InRelease` files and the compressed indexes, named by their SHA-256 (what didn't change isn't downloaded again) |
| `/var/lib/lordos/pkg/icons/64/` | 64×64 icons of the desktop apps (DEP-11) |
| `/var/lib/lordos/pkg/auto` | Packages LordOS installed as dependencies |
+| `/var/lib/lordos/pkg/notes` | The verified `main/notes/ReleaseNotes` of every source that has one (LordOS's; [UPDATES.md](UPDATES.md)); world-readable |
| `/var/cache/lordos/pkg/` | `.deb` files while they're being installed (deleted when done) |
## Helper actions (`admin.run`)
@@ -164,6 +169,8 @@ lord.pkg.apps({ category, type = 'desktop-application', limit = 100, offset = 0,
// [App + { package, installed, version, size }], sorted by name
lord.pkg.categories() // { AudioVideo: 210, Development: 180, … } (desktop apps)
lord.pkg.icon(name) // path of the 64×64 PNG or null
+lord.pkg.releaseNotes(name, version) // Markdown release notes a source published for that version, or null
+lord.pkg.rebootRequired() // null, or the packages that asked for a restart (/run/reboot-required.pkgs)
// Summary = { name, version (candidate), summary, section, size, installedSize (bytes),
// installed (version or null), upgradable, essential, auto, app: App | null }
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 52331b5..9234c22 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -58,7 +58,38 @@ The releases page is the project's public changelog: every release is documented
lines joined, its "Verifying" part replaced by the footer) plus a fixed footer: the downloads
table, the verification steps and links to lordos.org, the paper, the docs and the security
page. Read it once before publishing.
-7. **Publish:**
+7. **The APT repository** (what installed systems update from; [UPDATES.md](UPDATES.md)). On the
+ maintainer's Mac, where the archive key lives (never on a VM):
+
+ ```sh
+ # staging first: the same .debs, the notes from this version's CHANGELOG section
+ tools/release/apt-repo.sh build staging <release-dir>/lordos_<file-version>_amd64.deb <release-dir>/lordos_<file-version>_arm64.deb
+ tools/release/apt-repo.sh publish staging
+ tools/release/apt-repo.sh verify staging # https and http, signature, every index hash
+ ```
+
+ On a clean VM with the previous release installed, point a copy of `lordos.sources` at
+ `https://lordos.org/apt-staging` (or a `file:` copy of the tree) and check: `sudo apt update`
+ is clean, Store → Updates shows "LordOS <version> is available" with these notes, Update installs
+ it, the migrations run (`ls /var/lib/lordos/migrations`), the user's settings are untouched,
+ "Restart required" appears and the system comes back after the restart; a second `apt install
+ --reinstall lordos` runs no migration again. On the Raspberry Pi, `apt-get update` against
+ staging in a temporary `Dir::State::Lists` (no change to the board) validates the arm64 index.
+ Then the same for the live repository:
+
+ ```sh
+ tools/release/apt-repo.sh build live <release-dir>/lordos_<file-version>_amd64.deb <release-dir>/lordos_<file-version>_arm64.deb
+ tools/release/apt-repo.sh publish live
+ tools/release/apt-repo.sh verify live
+ ```
+
+ A version is never re-uploaded with other contents (the script refuses); a fix is a new version.
+ `verify live` must pass **before** any release whose package carries `lordos.sources` is
+ published: otherwise `apt update` fails on every system that installs it. A change between
+ versions that is not just new files (a unit to enable, a renamed setting, a config to convert)
+ is a migration in `packaging/migrations/` or `sdk/settings.js` ([UPDATES.md](UPDATES.md),
+ "Migrations"), never a manual step in the release notes.
+8. **Publish:**
```sh
gh release create v<version> --title "LordOS <version>" --prerelease --verify-tag \
@@ -68,7 +99,7 @@ The releases page is the project's public changelog: every release is documented
Leave out `--prerelease` only for a version without a suffix. The Debian installer
(`install.sh`) finds betas too: `releases/latest` skips pre-releases, so it falls back to the
newest release of any kind ([INSTALL-DEBIAN.md](INSTALL-DEBIAN.md)).
-8. **Check:** download from the release page and run the verification commands from the notes;
+9. **Check:** download from the release page and run the verification commands from the notes;
run `curl -fsSL https://lordos.org/install.sh | sh` on a clean Debian 13; update the website if
it names the current version.
diff --git a/docs/UPDATES.md b/docs/UPDATES.md
new file mode 100644
index 0000000..04bf717
--- /dev/null
+++ b/docs/UPDATES.md
@@ -0,0 +1,253 @@
+# Updating LordOS in place
+
+From 0.8.1, a LordOS system moves to a new version without reinstalling: the Store shows
+"LordOS <version> is available" with the release notes, installs it with the same package engine
+it uses for Debian packages, applies whatever the new version changes in the system (the
+migrations below) and asks for a restart. Files, settings and accounts are kept. It works the same
+on a PC installed from the ISO, on the Raspberry Pi 5 image, on Debian 13 with `install.sh` and on
+a server or VPS, and `apt` sees the same repository.
+
+| Piece | Where |
+|---|---|
+| The signed repository | `https://lordos.org/apt`, suite `stable`, component `main`, amd64 and arm64 |
+| Its source on every system | `/etc/apt/sources.list.d/lordos.sources` (deb822, `Signed-By:`) |
+| Its key on every system | `/usr/share/keyrings/lordos-archive-keyring.gpg` (in the `lordos` package) |
+| Building, signing and uploading it | `tools/release/apt-repo.sh` (on the maintainer's Mac) |
+| The Store's side | `apps/store/debian.js` (`Updates`), `sdk/updates.js`, `lord.pkg.releaseNotes` and `lord.pkg.rebootRequired` (`server/src/ui/js_pkg.c`) |
+| Version-to-version changes | `packaging/migrations/` (system, as root) and `MIGRATIONS` in `sdk/settings.js` (each user's settings) |
+
+## The repository
+
+```
+https://lordos.org/apt/
+ dists/stable/InRelease signed (clear-signed Release)
+ dists/stable/Release, Release.gpg the same, with a detached signature
+ dists/stable/main/binary-amd64/Packages(.xz, .gz)
+ dists/stable/main/binary-arm64/Packages(.xz, .gz)
+ dists/stable/main/notes/ReleaseNotes(.xz) release notes of each lordos version (below)
+ pool/main/l/lordos/lordos_<version>_<arch>.deb
+ lordos.sources the same file the package installs
+https://lordos.org/keys/lordos-archive-keyring.gpg (.asc) the public key
+https://lordos.org/apt-staging/ the same layout, for tests before anything goes live
+```
+
+- **One suite, `stable`,** with every published release (until 1.0 every release is a beta, and the
+ betas are what users run). Origin and Label are `LordOS`. Test builds go to `apt-staging`, never to
+ `apt`. A `beta` suite can be added later for opt-in previews.
+- **The pool only grows.** A published `.deb` is never replaced (`apt-repo.sh` refuses a version that
+ already exists with other contents); the previous versions stay, so `apt install lordos=<version>`
+ can go back. Versions follow dpkg's order, so a test build named `0.8.1~staging1` sorts after
+ `0.8.0` and before `0.8.1` (checked by `build/pkg-test`).
+- **Built with Debian's tools.** `apt-ftparchive` writes `Packages` and `Release` (in a
+ `debian:trixie` container on the Mac, or natively on a Debian host); `gpg` signs on the Mac.
+- **Release notes.** `main/notes/ReleaseNotes` is a deb822 file covered by the signed `Release`:
+ one stanza per lordos version with `Package`, `Version` and `Notes` (the version's section of
+ [CHANGELOG.md](../CHANGELOG.md) as Markdown, through `tools/release/release-notes.sh` without its
+ footer; continuation lines start with a space, ` .` is an empty line). Our package engine downloads
+ it in `pkg-update`, checks its SHA-256 against `InRelease` like any index and keeps it in
+ `/var/lib/lordos/pkg/notes`; `lord.pkg.releaseNotes(name, version)` returns the Markdown. `apt`
+ ignores the file.
+
+### Serving it (CDN)
+
+`lordos.org` is S3 behind CloudFront. Two things the website's defaults do would break APT, so the
+repository paths need their own CloudFront cache behaviors, `apt/*` and `apt-staging/*`:
+
+1. **Plain HTTP must be served, not redirected.** Our package engine has no TLS of its own (see
+ [PACKAGES.md](PACKAGES.md), "HTTP instead of HTTPS") and reads `https://` sources over `http://`,
+ exactly like `http://deb.debian.org`: what protects the files is the signature and the SHA-256
+ of every file, not the transport. `apt` itself uses HTTPS. Viewer protocol policy: **HTTP and
+ HTTPS** (`allow-all`).
+2. **No URL rewriting.** The site's `lordos-router` function (viewer request) turns a path without
+ an extension into `<path>/index.html`, and APT's files `InRelease`, `Release` and `Packages` have
+ none. The two behaviors have **no function association**.
+
+Everything else is copied from the default behavior: origin `s3-lordos.org`, GET/HEAD, the same
+cache policy and response headers policy. `keys/*` needs nothing special (HTTPS, files with an
+extension). `tools/web/cdn-apt-behaviors.sh <admin-profile>` makes this change (once, by the
+account's administrator: the deploy profile cannot change the distribution). The website's deploy
+script (`tools/web/deploy.sh`) never touches `apt/`, `apt-staging/` or `keys/`.
+`apt-repo.sh verify <target>` checks all of this from the outside.
+
+## The keys
+
+| Key | Private part | Public part |
+|---|---|---|
+| **APT archive key** (signs `InRelease`/`Release.gpg`): OpenPGP v4, Ed25519, sign only, `LordOS Archive Signing Key`, fingerprint `1DDA F390 107D F264 FA8A 0918 3972 CC6D E4DA 2336`, expires 2031-10-18 | the maintainer's Mac only: GnuPG home `~/.config/lordos-release/apt-gnupg` (0700) and an armored export `~/.config/lordos-release/apt-archive-signing.secret.asc` (0600); backup copies of both in `~/.ssh/ssh/lordos-release/`, the same place as the release key's | `packaging/keys/lordos-archive-keyring.gpg` (and `.asc`), installed as `/usr/share/keyrings/lordos-archive-keyring.gpg`, published at `https://lordos.org/keys/` |
+| **Release key** (signs `SHA256SUMS` of a GitHub release; raw Ed25519) | `~/.config/lordos-release/release-ed25519.key.pem` | see [SIGNING.md](SIGNING.md) |
+
+APT needs OpenPGP, so the repository has its own key instead of reusing the raw Ed25519 release key.
+Neither private key is ever copied to a VM, a build machine, a server or the repository. Keep an
+offline copy of `~/.config/lordos-release/` (the whole folder) as well.
+
+**Before 2031-10-18**, extend the key's expiry on the Mac (`gpg --quick-set-expire <fingerprint> 5y`
+with `GNUPGHOME=~/.config/lordos-release/apt-gnupg`), export it again into `packaging/keys/` and ship
+it in a release some months before the old date: a system that has not updated by then needs
+`install.sh` again. To replace the key, ship the new one in the keyring file next to the old one for
+at least one release before signing with it.
+
+## How a system gets the repository
+
+- **The `lordos` package** carries the source as `/usr/lib/lordos/apt/lordos.sources`. Its
+ `postinst` copies it to `/etc/apt/sources.list.d/lordos.sources` when that file is missing, and
+ its `postrm` removes it with the package (otherwise `apt update` would fail on a repository whose
+ key is gone). It is not a conffile: an administrator's change, such as `Enabled: no` to stop
+ LordOS updates, is kept on every upgrade.
+- **New installs** from the 0.8.1 ISO, the Raspberry Pi image and `install.sh` get it with the
+ package; none of them needs a step of its own.
+- **LordOS 0.8.0** (one time): its package has no repository yet. Either run the installer again,
+ which upgrades in place (it keeps the login setup, the users and their settings):
+
+ ```sh
+ curl -fsSL https://lordos.org/install.sh | sh
+ ```
+
+ or add the repository by hand and upgrade with apt (or with Store → Updates afterwards):
+
+ ```sh
+ sudo curl -fsSLo /usr/share/keyrings/lordos-archive-keyring.gpg https://lordos.org/keys/lordos-archive-keyring.gpg
+ gpg --show-keys /usr/share/keyrings/lordos-archive-keyring.gpg # 1DDA F390 107D F264 FA8A 0918 3972 CC6D E4DA 2336
+ sudo curl -fsSLo /etc/apt/sources.list.d/lordos.sources https://lordos.org/apt/lordos.sources
+ sudo apt update && sudo apt install lordos
+ ```
+
+ That file is byte for byte the one the package would write, so the package keeps it as it is.
+
+```
+# /etc/apt/sources.list.d/lordos.sources
+Types: deb
+URIs: https://lordos.org/apt
+Suites: stable
+Components: main
+Signed-By: /usr/share/keyrings/lordos-archive-keyring.gpg
+```
+
+## Store → Updates
+
+| | |
+|---|---|
+| ![LordOS update available](store-update-available-light.png) | ![LordOS update available, dark](store-update-available-dark.png) |
+| "LordOS <version> is available", with the release notes | The same in dark mode |
+| ![Updating](store-update-progress-light.png) | ![Restart required](store-update-restart-dark.png) |
+| Updating (the plan, then the progress of `pkg-install lordos`) | Installed: "Restart required" |
+| ![The daily check's notification](store-update-notification-dark.png) | |
+| The daily check found an update and says so once (here a Debian update; after the restart, About shows the new version) | |
+
+(Screenshots from the staging test on VM 120: the test builds are called `0.8.1~staging5` and
+`~staging6`, and their notes are 0.8.1's unreleased changelog.)
+
+- **"Check for updates"** runs `pkg-update`: every source's signed `InRelease`, Debian's and
+ LordOS's, then the indexes and the release notes.
+- **"LordOS <version> is available"** appears when the candidate of the `lordos` package is newer
+ than the installed one: the installed version, the download size, **What's new** (the release
+ notes, the first lines with "Show all") and **Update**. Update shows the plan first
+ (`lord.pkg.plan({ install: ['lordos'] })`: lordos and any new dependency), then runs
+ `pkg-install lordos` through the administration helper, with the same progress bar as any
+ install. Only administrators (the `sudo` group) can update.
+- **Debian updates** are listed below with "Update all" (`pkg-upgrade`, which also takes lordos if
+ it is pending).
+- **"Restart required"** appears when an installed update needs it: the running `lord-server` is
+ not the installed `lordos` version, or `/run/reboot-required` exists (the Debian convention: the
+ lordos `postinst` writes it on an upgrade, and its kernel hook
+ `/etc/kernel/postinst.d/zz-lordos-reboot-required` on every new kernel). "Restart Now…" opens the
+ session's Restart dialog (with its countdown and the open apps; [SESSIONS.md](SESSIONS.md)) when
+ the session can restart; otherwise it says to log out and choose Restart on the login screen.
+ "Later" hides it. Nothing restarts on its own: the update replaces the files under the running
+ session, which keeps working with what it already loaded until the restart.
+- **Check for updates automatically** (on by default, per user, `settings.json` → `updates.autoCheck`):
+ five minutes after login and then every hour, if the lists are more than a day old and the user is
+ an administrator, the session runs `pkg-update` quietly and, when the set of available updates is
+ new, shows one notification ("LordOS 0.8.2 is available", or "3 updates are available") that
+ opens Updates. It never installs anything. When nothing changed it costs a few small requests
+ (`If-Modified-Since`, 304). LordOS has no metered-connection setting yet; turning the check off
+ is the way to avoid it on a metered link.
+- **Local repositories.** The engine also reads `file:/path` sources (a copy of the repository on a
+ disk or USB stick, for machines without internet), checked the same way.
+
+The whole path is our own engine ([PACKAGES.md](PACKAGES.md)): the `InRelease` signature is checked
+by `server/src/pkg/pgp.c` (Ed25519 v4, SHA-512) against the keyring named in `Signed-By`, every
+file by its SHA-256, and dpkg installs. `apt` and the Store share dpkg's lock and see the same
+state, so either can be used.
+
+## Migrations
+
+What changes between versions in the installed system (not in the files the package ships) is a
+migration. Two kinds:
+
+**System migrations** (root), `packaging/migrations/NNN-<version>-<name>.sh`, installed in
+`/usr/lib/lordos/migrations/` and run by `/usr/lib/lordos/migrate` from the package's `postinst`:
+
+- each one runs **once**, in `NNN` order; `/var/lib/lordos/migrations/<name>` records it (the time
+ it ran). So 0.8.1 → 0.8.2 → 0.8.3 and 0.8.0 → 0.8.3 in one step run the same migrations and end
+ in the same state;
+- it gets the version it upgrades from in `LORDOS_OLD_VERSION` (empty on a new install, where
+ most migrations have nothing to do) and runs under `sh -eu`;
+- it must be **idempotent** and safe without systemd (a chroot building an image), must not touch
+ the users' home folders, and must keep what an administrator changed;
+- if one fails, the ones after it don't run, `dpkg` leaves lordos unconfigured and says so, and the
+ next `dpkg --configure -a` or Store update runs it again.
+
+Today's migrations:
+
+| Migration | What it does |
+|---|---|
+| `001-0.8.1-network-permissions` | Enables `lord-netperm.service` (per-app network permissions) where `lordos.service` is enabled. The ISO, the Pi image and `install.sh` already did; a system set up with `apt` alone had it off. Runs once: disabling it later sticks. |
+| `002-0.8.1-root-ssh-keys` | 0.8.1 adds `PermitRootLogin no` (`/etc/ssh/sshd_config.d/10-lordos.conf`). On an **upgrade** from 0.8.0 with SSH installed and keys in `/root/.ssh/authorized_keys` (a VPS run as root), it writes `09-lordos-root-keys.conf` with `PermitRootLogin prohibit-password`, so root keeps logging in with keys (never passwords) instead of being locked out at the next restart. New installs never get it; delete the file to apply LordOS's default. |
+
+**Settings migrations** (each user), in `sdk/settings.js`: `MIGRATIONS` is a list of
+`[schema, (settings) => newSettings]` applied in order when the session loads
+`~/.config/lordos/settings.json`; the file records the last one in `schema`. 0.8.1 starts recording
+it (schema 1, nothing changes). A setting renamed or reshaped in a release gets an entry here, so a
+user who skips versions still converges.
+
+Things that only need new files (a new unit, a new default config) ship in the package as usual; a
+new unit that must be enabled on upgraded systems needs a migration, since `postinst` only enables
+`lord-fand`.
+
+## The Raspberry Pi kernel
+
+The LordOS kernel for the Pi 5 (`linux-image-<version>-lordos-rpi-2712`, from
+`tools/rpi/build-kernel.sh`) is **not** in the repository yet: kernel updates on the Pi come with a
+new image for now. Its package installs exactly like Raspberry Pi's own (`raspi-firmware`'s hook
+copies the newest kernel to `kernel_2712.img`), with no `tryboot` fallback, so a broken kernel would
+leave the board unbootable with no way back from the Store. It goes into the repository when the
+image boots new kernels through the firmware's `tryboot` first and keeps the previous one as the
+fallback. The `lordos` package itself updates on the Pi like anywhere else (arm64).
+
+## Tests (2026-10-18)
+
+- **Staging** (`https://lordos.org/apt-staging`, built and signed on the Mac with `apt-repo.sh`):
+ lordos 0.8.0 (amd64, arm64, from the 0.8.0 release, checked against its signed `SHA256SUMS`) and
+ test builds `0.8.1~staging*`.
+- **Signatures:** `InRelease` verifies with LordOS's own code (`build/pkg-test pgp
+ packaging/keys/lordos-archive-keyring.gpg InRelease`: 1 key, 1 valid signature) and with Debian
+ 13's `apt` (`sqv`); one changed byte is rejected (`pkg.pgp.badSignature`).
+- **apt, VM 120 (0.8.0 installed from the ISO, user logged in):** the 0.8.0 one-time step, then
+ `apt install lordos`: 0.8.0 → 0.8.1~staging in 29 s with the session open; migration 001
+ applied; `lordos`, `lord-netperm`, `lord-fand` active; `settings.json` byte for byte the same;
+ `/run/reboot-required.pkgs` = `lordos`; after the restart the login screen came back with the new
+ version. That run found the `PermitRootLogin no` lock-out (the VM is administered as root with a
+ key), which migration 002 now prevents.
+- **`install.sh` on an installed LordOS** (VM 120 back at 0.8.0, session running): with the
+ staging package (`--deb`) it upgraded in place to 0.8.1~staging5, kept `session.conf`, the users,
+ groups and settings, ran migrations 001 and 002, and reported "LordOS is running and was upgraded
+ in place"; running it again reinstalls the same version and changes nothing else.
+- **Store → Updates, VM 120 at 0.8.1~staging5,** the repository as a `file:` source (the same
+ signed tree as staging): Check for updates verified LordOS's `InRelease` with our own code
+ (73,103 packages from 4 sources), showed "LordOS 0.8.1~staging6 is available" with its notes and
+ liblzma5 under Debian updates; Update showed the plan (1 to update, 6.0 MB) and installed it with
+ progress; "Restart required" appeared; after the restart the session came back on staging6 with
+ the user's settings (and `schema: 1` recorded). **Daily check:** with the lists aged two days,
+ five minutes after login the session ran `pkg-update` on its own and showed "1 update is
+ available" once (`updates.notified` recorded in `settings.json`). **Second upgrade:** a build with a third
+ migration ran only that one (`old version: 0.8.1~staging3`); `apt install --reinstall lordos` and
+ running `/usr/lib/lordos/migrate` again applied nothing.
+- **Raspberry Pi 5 (arm64, lordos 0.8.0):** `apt-get update` against a copy of staging in a
+ temporary `Dir::State::Lists` (nothing on the board changed; removed afterwards): signature good,
+ `binary-arm64/Packages` read, `lordos 0.8.0 arm64` listed with the right `Filename` and SHA-256.
+- `make -C server test` (21 suites passed, 5 skipped for missing tools; `pkg-test` 83/83 with the
+ release-notes reader and pre-release version order), `node tools/i18n-check.mjs`, the brand
+ check and `shellcheck` on every new script.
+- **Not yet:** the CDN change above, so `https://lordos.org/apt-staging` is uploaded and signed but
+ `InRelease` still answers 404 (the router) and http 301; `apt-repo.sh verify staging` passes
+ only after `tools/web/cdn-apt-behaviors.sh` is run by the account administrator.
diff --git a/docs/store-update-available-dark.png b/docs/store-update-available-dark.png
new file mode 100644
index 0000000..9c2e882
Binary files /dev/null and b/docs/store-update-available-dark.png differ
diff --git a/docs/store-update-available-light.png b/docs/store-update-available-light.png
new file mode 100644
index 0000000..2531eec
Binary files /dev/null and b/docs/store-update-available-light.png differ
diff --git a/docs/store-update-notification-dark.png b/docs/store-update-notification-dark.png
new file mode 100644
index 0000000..4e6f1e0
Binary files /dev/null and b/docs/store-update-notification-dark.png differ
diff --git a/docs/store-update-progress-light.png b/docs/store-update-progress-light.png
new file mode 100644
index 0000000..9ad7aae
Binary files /dev/null and b/docs/store-update-progress-light.png differ
diff --git a/docs/store-update-restart-dark.png b/docs/store-update-restart-dark.png
new file mode 100644
index 0000000..32701e3
Binary files /dev/null and b/docs/store-update-restart-dark.png differ
diff --git a/tools/web/cdn-apt-behaviors.sh b/tools/web/cdn-apt-behaviors.sh
new file mode 100755
index 0000000..0bcde3e
--- /dev/null
+++ b/tools/web/cdn-apt-behaviors.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+# One-time CloudFront change so lordos.org can serve the APT repository (docs/UPDATES.md,
+# "Serving it"): two cache behaviors, apt/* and apt-staging/*, copied from the default one but
+# serving plain HTTP as is (allow-all: LordOS's package engine reads https sources over http and
+# trusts the signatures, like apt with deb.debian.org) and without the lordos-router function
+# (it would turn InRelease, Release and Packages into <path>/index.html).
+#
+# tools/web/cdn-apt-behaviors.sh <aws-profile-that-can-update-the-distribution>
+#
+# The deploy profile ("lordos") cannot change the distribution; run this with the account's
+# administrator profile. Idempotent: running it again replaces the two behaviors with fresh copies.
+# Then check with: tools/release/apt-repo.sh verify staging
+set -eu
+PROFILE=${1:?usage: cdn-apt-behaviors.sh <aws-profile>}
+DISTRIBUTION=E35DXDFJ83X7Z8
+t=$(mktemp -d)
+trap 'rm -rf "$t"' EXIT
+aws --profile "$PROFILE" cloudfront get-distribution-config --id "$DISTRIBUTION" > "$t/current.json"
+python3 - "$t" <<'PY'
+import copy, json, sys
+t = sys.argv[1]
+d = json.load(open(f"{t}/current.json"))
+c = d["DistributionConfig"]
+keep = [b for b in c.get("CacheBehaviors", {}).get("Items", []) or [] if b["PathPattern"] not in ("apt/*", "apt-staging/*")]
+for pattern in ("apt/*", "apt-staging/*"):
+ b = copy.deepcopy(c["DefaultCacheBehavior"])
+ b["PathPattern"] = pattern
+ b["ViewerProtocolPolicy"] = "allow-all"
+ b["FunctionAssociations"] = {"Quantity": 0}
+ b["Compress"] = False
+ keep.append(b)
+c["CacheBehaviors"] = {"Quantity": len(keep), "Items": keep}
+json.dump(c, open(f"{t}/new.json", "w"))
+open(f"{t}/etag", "w").write(d["ETag"])
+PY
+aws --profile "$PROFILE" cloudfront update-distribution --id "$DISTRIBUTION" --if-match "$(cat "$t/etag")" \
+ --distribution-config "file://$t/new.json" --query Distribution.Status --output text
+echo "CloudFront is deploying the change (a few minutes); then: tools/release/apt-repo.sh verify staging"
diff --git a/web/content/faq/faq.json b/web/content/faq/faq.json
index 747ed5b..6fc6b58 100644
--- a/web/content/faq/faq.json
+++ b/web/content/faq/faq.json
@@ -736,22 +736,22 @@
"pt": "Como mantenho o LordOS atualizado?"
},
"a": {
- "en": "Open the Store's Updates tab and press Check for updates: it refreshes Debian's package lists, shows what will change and upgrades everything together, including Debian's security updates. Nothing is checked or downloaded automatically. You can still use `apt` in the Terminal if you prefer.",
- "es": "Abrí la pestaña Actualizaciones de la Tienda y tocá Buscar actualizaciones: refresca las listas de paquetes de Debian, te muestra qué va a cambiar y actualiza todo junto, incluidas las actualizaciones de seguridad de Debian. Nada se revisa ni se descarga solo. Si preferís, podés seguir usando `apt` en la Terminal.",
- "pt": "Abra a aba Atualizações da Loja e toque em Procurar atualizações: ela atualiza as listas de pacotes do Debian, mostra o que vai mudar e atualiza tudo junto, incluindo as atualizações de segurança do Debian. Nada é verificado nem baixado automaticamente. Se preferir, você ainda pode usar o `apt` no Terminal."
+ "en": "Open the Store's Updates tab and press Check for updates: it refreshes the package lists of Debian and of LordOS, shows what will change and updates everything together, including Debian's security updates. From LordOS 0.8.1 the Store also checks once a day and tells you when something new is available (you can turn that off in the same tab); it never installs anything without asking. You can still use `apt` in the Terminal if you prefer.",
+ "es": "Abrí la pestaña Actualizaciones de la Tienda y tocá Buscar actualizaciones: refresca las listas de paquetes de Debian y de LordOS, te muestra qué va a cambiar y actualiza todo junto, incluidas las actualizaciones de seguridad de Debian. Desde LordOS 0.8.1 la Tienda además revisa una vez por día y te avisa cuando hay algo nuevo (se desactiva en la misma pestaña); nunca instala nada sin preguntar. Si preferís, podés seguir usando `apt` en la Terminal.",
+ "pt": "Abra a aba Atualizações da Loja e toque em Procurar atualizações: ela atualiza as listas de pacotes do Debian e do LordOS, mostra o que vai mudar e atualiza tudo junto, incluindo as atualizações de segurança do Debian. A partir do LordOS 0.8.1 a Loja também verifica uma vez por dia e avisa quando há algo novo (dá para desativar na mesma aba); ela nunca instala nada sem perguntar. Se preferir, você ainda pode usar o `apt` no Terminal."
}
},
{
- "id": "new-versions",
+ "id": "update-lordos",
"q": {
- "en": "How do I get a new LordOS version?",
- "es": "¿Cómo paso a una versión nueva de LordOS?",
- "pt": "Como pego uma versão nova do LordOS?"
+ "en": "How do I update LordOS?",
+ "es": "¿Cómo actualizo LordOS?",
+ "pt": "Como atualizo o LordOS?"
},
"a": {
- "en": "New versions are published on [GitHub Releases](https://github.com/lordbasex/LordOS/releases) as a `.deb` package, an ISO and a Raspberry Pi image. On Debian, running the one-line installer again upgrades LordOS; you can also install a downloaded `.deb` from the Store. A built-in updater for LordOS itself is not available yet. Each release's notes list everything that changed, and [CHANGELOG.md](https://github.com/lordbasex/LordOS/blob/main/CHANGELOG.md) keeps the whole history.",
- "es": "Las versiones nuevas se publican en [GitHub Releases](https://github.com/lordbasex/LordOS/releases) como paquete `.deb`, ISO e imagen para Raspberry Pi. En Debian, volver a ejecutar el instalador de una línea actualiza LordOS; también podés instalar un `.deb` descargado desde la Tienda. Un actualizador propio de LordOS todavía no está disponible. Las notas de cada versión detallan todo lo que cambió, y [CHANGELOG.md](https://github.com/lordbasex/LordOS/blob/main/CHANGELOG.md) guarda el historial completo.",
- "pt": "As versões novas são publicadas no [GitHub Releases](https://github.com/lordbasex/LordOS/releases) como pacote `.deb`, ISO e imagem para Raspberry Pi. No Debian, rodar de novo o instalador de uma linha atualiza o LordOS; você também pode instalar um `.deb` baixado pela Loja. Um atualizador próprio do LordOS ainda não está disponível. As notas de cada versão listam tudo o que mudou, e o [CHANGELOG.md](https://github.com/lordbasex/LordOS/blob/main/CHANGELOG.md) guarda o histórico completo."
+ "en": "In place, without reinstalling: from LordOS 0.8.1, when a new version is out, Store → Updates shows \"LordOS <version> is available\" with its release notes and an Update button. Your files and settings are kept, and the Store asks you to restart when the update is installed. It works the same on a PC installed from the ISO, on the Raspberry Pi image and on Debian with the one-line installer; with `apt`, `sudo apt update && sudo apt upgrade` does it too. LordOS 0.8.0 needs one step first: run `curl -fsSL https://lordos.org/install.sh | sh` again, which upgrades it in place and adds the signed LordOS repository. Every release is also on [GitHub Releases](https://github.com/lordbasex/LordOS/releases), and [CHANGELOG.md](https://github.com/lordbasex/LordOS/blob/main/CHANGELOG.md) keeps the whole history.",
+ "es": "Sobre la instalación, sin reinstalar: desde LordOS 0.8.1, cuando sale una versión nueva, Tienda → Actualizaciones muestra «LordOS <versión> está disponible» con sus notas y un botón Actualizar. Tus archivos y ajustes se conservan, y la Tienda te pide reiniciar cuando la actualización queda instalada. Funciona igual en una PC instalada desde la ISO, en la imagen para Raspberry Pi y en Debian con el instalador de una línea; con `apt`, `sudo apt update && sudo apt upgrade` también lo hace. LordOS 0.8.0 necesita un paso antes: volver a ejecutar `curl -fsSL https://lordos.org/install.sh | sh`, que la actualiza en el lugar y agrega el repositorio firmado de LordOS. Cada versión también está en [GitHub Releases](https://github.com/lordbasex/LordOS/releases), y [CHANGELOG.md](https://github.com/lordbasex/LordOS/blob/main/CHANGELOG.md) guarda el historial completo.",
+ "pt": "No lugar, sem reinstalar: a partir do LordOS 0.8.1, quando sai uma versão nova, Loja → Atualizações mostra \"LordOS <versão> está disponível\" com as notas e um botão Atualizar. Seus arquivos e ajustes são mantidos, e a Loja pede para reiniciar quando a atualização fica instalada. Funciona igual num PC instalado pela ISO, na imagem para Raspberry Pi e no Debian com o instalador de uma linha; com o `apt`, `sudo apt update && sudo apt upgrade` também faz isso. O LordOS 0.8.0 precisa de um passo antes: rodar de novo `curl -fsSL https://lordos.org/install.sh | sh`, que o atualiza no lugar e adiciona o repositório assinado do LordOS. Cada versão também está no [GitHub Releases](https://github.com/lordbasex/LordOS/releases), e o [CHANGELOG.md](https://github.com/lordbasex/LordOS/blob/main/CHANGELOG.md) guarda o histórico completo."
}
},
{