From 4a2cee8e6cf2cfe0975b11fbccf6beb36b99cc60 Mon Sep 17 00:00:00 2001
From: Ben Radford <benradf@users.noreply.github.com>
Date: Mon, 11 Dec 2023 18:55:39 +0000
Subject: [PATCH] Document expected filesystem layout and OverlayFS mount
 command.

---
 src/libstore/local-overlay-store.md | 42 +++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/libstore/local-overlay-store.md b/src/libstore/local-overlay-store.md
index a0b9c3adf..813efc3e9 100644
--- a/src/libstore/local-overlay-store.md
+++ b/src/libstore/local-overlay-store.md
@@ -5,6 +5,7 @@ R"(
 This store type is a variation of the [local store] designed to leverage Linux's [Overlay Filesystem](https://docs.kernel.org/filesystems/overlayfs.html) (OverlayFS for short).
 Just as OverlayFS combines a lower and upper filesystem by treating the upper one as a patch against the lower, the local overlay store combines a lower store with an upper almost [local store].
 ("almost" because while the upper fileystems for OverlayFS is valid on its own, the upper almost-store is not a valid local store on its own because some references will dangle.)
+To use this store, you will first need to configure an OverlayFS mountpoint [appropriately](#example-filesystem-layout) as Nix will not do this for you (though it will verify the mountpoint is configured correctly).
 
 ### Parts of a local overlay store
 
@@ -15,6 +16,9 @@ The parts of a local overlay store are as follows:
   This is any store implementation that includes a store directory as part of the native operating system filesystem.
   For example, this could be a [local store], [local daemon store], or even another local overlay store.
 
+  The lower store must not change while it is mounted as part of an overlay store.
+  To ensure it does not, you might want to mount the store directory read-only (which then requires the [read-only] parameter to be set to `true`).
+
   Specified with the `lower-store` setting.
 
   - Lower store directory.
@@ -51,4 +55,42 @@ The parts of a local overlay store are as follows:
 
     Specified with the `state` setting, is always `${state}/db`.
 
+
+### Example filesystem layout
+
+Say we have the following paths:
+
+- `/mnt/example/merged-store/nix/store`
+
+- `/mnt/example/store-a/nix/store`
+
+- `/mnt/example/store-b`
+
+
+Then the following store URI can be used to access a local-overlay store at `/mnt/example/merged-store`:
+
+```
+  local-overlay://?root=/mnt/example/merged-store&lower-store=/mnt/example/store-a&upper-layer=/mnt/example/store-b
+```
+
+The lower store is located at `/mnt/example/store-a/nix/store`, while the upper layer is at `/mnt/example/store-b`.
+
+Before accessing the overlay store you will need to ensure the OverlayFS mount is set up correctly:
+
+```
+  mount -t overlay overlay \
+    -o lowerdir="/mnt/example/store-a/nix/store" \
+    -o upperdir="/mnt/example/store-b" \
+    -o workdir="/mnt/example/workdir" \
+    "/mnt/example/merged-store/nix/store" \
+```
+
+Note that OverlayFS requires `/mnt/example/workdir` to be on the same volume as the `upperdir`.
+
+By default, Nix will check that the mountpoint as been set up correctly and fail with an error if it has not.
+You can override this behaviour by passing [`check-mount=false`](???) if you need to.
+
+
+
+
 )"