From 4b3316ebb827f229d57c65dc0c17cc41a05e5511 Mon Sep 17 00:00:00 2001
From: Nick Woolmer <29717167+nwoolmer@users.noreply.github.com>
Date: Thu, 30 Jul 2026 18:56:47 +0100
Subject: [PATCH] fix(docs): remove QDB_CAIRO_ROOT from the Docker Compose
 example

The "Custom data directory permissions" example set
QDB_CAIRO_ROOT=/var/lib/questdb. That is unnecessary, because the Docker
image already passes /var/lib/questdb as its root directory, and it is
harmful, because an absolute cairo.root changes how every other directory
is derived.

With an absolute cairo.root, PropServerConfiguration creates conf, import,
export, tmp and .checkpoint as siblings of the data directory rather than
as children of the root directory. Following the example therefore places
all of them in /var/lib, outside the mounted volume and in a directory the
container user cannot write to. CHECKPOINT CREATE fails with:

  Could not create [dir=/var/lib/.checkpoint//var/lib/questdb/]

Drop the variable from the example, add a caution explaining why it must
not be set, and document the same behaviour on the cairo.root reference
entry.

Also rewrite the volume permissions warning, which described the default
image behaviour inaccurately. The image starts as root, takes ownership of
the data directory and drops privileges; pinning user: is what skips that
step, so the host directory must already be writable by the pinned uid.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 documentation/configuration/cairo-engine.md   |  7 +++
 .../operations/docker-compose-config.md       | 44 +++++++++++++++++--
 2 files changed, 47 insertions(+), 4 deletions(-)

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: