From b287281940bc1f5e639d5fe71a3f346878427d0d Mon Sep 17 00:00:00 2001
From: Evyatar Bluzer <bluzername@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:39:20 +0700
Subject: [PATCH] docs: add inline comments to docker quickstart compose file
 (#2431)

## Problem

The quickstart docker-compose file was recently moved to
\`docker/docker-compose.quickstart.yml\` during the Docker
reorganization but still have zero inline comments. When new user copy
this file for self-hosting, they see variables like:
- \`BETTER_AUTH_SECRET\` - what is this? How to generate?
- \`PAPERCLIP_DEPLOYMENT_MODE: "authenticated"\` - what other modes
available?
- \`PAPERCLIP_DEPLOYMENT_EXPOSURE: "private"\` - what does private vs
public mean?
- \`OPENAI_API_KEY\` and \`ANTHROPIC_API_KEY\` - both required? Or just
one?

They have to go read DOCKER.md or other docs to understand each
variable.

## What I changed

Added inline YAML comments directly in the file:
- Header block with step-by-step quickstart commands (cd docker, export,
docker compose up)
- Section headers grouping LLM keys, deployment settings, and secrets
- Comment explaining each non-obvious variable with valid values
- Note about \`BETTER_AUTH_SECRET\` with openssl generation command
- Comment on the volume explaining what data it persist

No functional change - only YAML comments added.
---
 docker/docker-compose.quickstart.yml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docker/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml
index 65705059aa..16fa17bccc 100644
--- a/docker/docker-compose.quickstart.yml
+++ b/docker/docker-compose.quickstart.yml
@@ -1,3 +1,11 @@
+# Quickstart: single-container Paperclip with embedded database.
+# Copy this file and set the required env vars before running.
+#
+#   cd docker
+#   export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"
+#   export ANTHROPIC_API_KEY="sk-ant-..."
+#   docker compose -f docker-compose.quickstart.yml up --build
+#
 services:
   paperclip:
     build:
@@ -8,11 +16,21 @@ services:
     environment:
       HOST: "0.0.0.0"
       PAPERCLIP_HOME: "/paperclip"
+
+      # ── LLM provider keys (at least one is needed for agents to work) ──
       OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
       ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+
+      # ── Deployment settings ──
+      # "authenticated" requires login, "local_trusted" skips auth
       PAPERCLIP_DEPLOYMENT_MODE: "authenticated"
+      # "private" = LAN only, "public" = internet-facing (use with TLS)
       PAPERCLIP_DEPLOYMENT_EXPOSURE: "private"
+      # Base URL users will access the UI at
       PAPERCLIP_PUBLIC_URL: "${PAPERCLIP_PUBLIC_URL:-http://localhost:3100}"
+
+      # ── Required secret for session signing (generate with: openssl rand -hex 32) ──
       BETTER_AUTH_SECRET: "${BETTER_AUTH_SECRET:?BETTER_AUTH_SECRET must be set}"
     volumes:
+      # Persistent data directory (database, agent workspaces, uploads)
       - "${PAPERCLIP_DATA_DIR:-../data/docker-paperclip}:/paperclip"