From 0d74686d77481552718cfacf2574322c00033979 Mon Sep 17 00:00:00 2001 From: Prasanth Baskar Date: Wed, 12 Aug 2026 19:11:45 +0530 Subject: [PATCH] docs: require overlay storage driver for bootc switch A fresh host without an explicit /etc/containers/storage.conf can hit 'graph driver "overlay" overwritten by graph driver "vfs"' on bootc switch, because /run/bootc/storage (bootc's tmpfs staging store) picks vfs on its own and containers/storage refuses to trust the configured overlay default over what it already recorded. Deleting that directory doesn't help since the driver gets re-derived the same way next run; pinning the driver in /etc/containers/storage.conf does. Signed-off-by: Prasanth Baskar --- docs/laptop-bootc-architecture.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/laptop-bootc-architecture.md b/docs/laptop-bootc-architecture.md index fc986ee..3152f33 100644 --- a/docs/laptop-bootc-architecture.md +++ b/docs/laptop-bootc-architecture.md @@ -43,6 +43,25 @@ flowchart TD an internal kernel-command-line crate rename. - Secure Boot must remain disabled until a signed Arch UKI workflow is added. +## Host prerequisites + +- `/etc/containers/storage.conf` must explicitly set `driver = "overlay"`: + ```toml + [storage] + driver = "overlay" + ``` + Without it, a fresh `bootc switch` can fail with: + ``` + ERRO[0000] User-selected graph driver "overlay" overwritten by graph + driver "vfs" from database - delete libpod local files + ("/run/bootc/storage") to resolve. + ``` + `/run/bootc/storage` is bootc's own ephemeral staging store for the image + it is about to switch to, kept on tmpfs. Deleting that directory alone does + not fix it, since the driver decision is re-derived on the next invocation; + the host-wide storage driver must be pinned explicitly at the `/etc` + level, which overrides every other `storage.conf` on the system. + ## Image policy - Official Arch packages by default for the operating system and desktop.