diff --git a/documentation/configuration/cairo-engine.md b/documentation/configuration/cairo-engine.md
index 7112f46b6..b22571b74 100644
--- a/documentation/configuration/cairo-engine.md
+++ b/documentation/configuration/cairo-engine.md
@@ -25,6 +25,13 @@ The locale used to handle date types.
 Directory for storing database tables and metadata. This directory is relative
 to the server root directory provided at startup.
 
+If you set it to an absolute path, QuestDB no longer derives its other
+directories from the server root directory. The `conf`, `import`, `export`,
+`tmp` and `.checkpoint` directories are then created as siblings of the
+directory you specify, rather than as children of the server root directory.
+Under Docker this places them outside the mounted volume, so leave `cairo.root`
+at its default and change the volume mapping instead.
+
 ### cairo.system.table.prefix
 
 - **Default**: `sys.`
diff --git a/documentation/cookbook/operations/docker-compose-config.md b/documentation/cookbook/operations/docker-compose-config.md
index 96e77ee7b..dee030fe1 100644
--- a/documentation/cookbook/operations/docker-compose-config.md
+++ b/documentation/cookbook/operations/docker-compose-config.md
@@ -70,22 +70,58 @@ This configuration:
 
 
 :::warning Volume Permissions
-If you encounter permission errors with mounted volumes, ensure the QuestDB container user has write access to the host directory. You may need to set ownership with `chown -R 1000:1000 ./questdb_root` or run the container with a specific user ID.
+By default the `questdb/questdb` image starts as `root`, takes ownership of the
+mounted data directory, and then drops privileges to its own `questdb` user. In
+most cases you do not need to do anything.
+
+If you pin the container user with `user:`, the entrypoint can no longer fix
+ownership, so the host directory must already be writable by the uid and gid you
+pin.
 :::
 
 ## Custom data directory permissions
 
-```yaml title="Run with specific user/group for volume permissions"
+Pin the container user when you want QuestDB to write files as a specific
+account on the host, for example so that the data directory stays readable by
+your own user. Set `user:` to a uid and gid that owns the host directory, which
+is often `1000:1000` for the first non-root account on a Linux host. Run
+`id -u` and `id -g` to check:
+
+```yaml title="Run with a specific user/group for volume permissions"
 services:
   questdb:
     image: questdb/questdb
     user: "1000:1000"
-    environment:
-      - QDB_CAIRO_ROOT=/var/lib/questdb
     volumes:
       - ./questdb_data:/var/lib/questdb
 ```
 
+Make sure that user owns the host directory before starting the container:
+
+```bash
+mkdir -p questdb_data && sudo chown -R 1000:1000 questdb_data
+```
+
+:::caution Do not set `QDB_CAIRO_ROOT` in Docker
+The Docker image already uses `/var/lib/questdb` as its root directory, so
+`QDB_CAIRO_ROOT` is unnecessary. Setting it to an absolute path also changes how
+QuestDB derives its other directories: they become siblings of the data
+directory rather than children of the root directory.
+
+With `QDB_CAIRO_ROOT=/var/lib/questdb`, the checkpoint, import, export and
+temporary directories move to `/var/lib/.checkpoint`, `/var/lib/import`,
+`/var/lib/export` and `/var/lib/tmp` — all outside the mounted volume, in a
+directory the container user cannot write to. `CHECKPOINT CREATE` then fails
+with an error such as:
+
+```
+Could not create [dir=/var/lib/.checkpoint//var/lib/questdb/]
+```
+
+To change where data is stored on the host, change the left-hand side of the
+volume mapping instead.
+:::
+
 ## Complete configuration reference
 
 For a full list of available configuration parameters, see: