From 82d97418b2d9d8b7247d7394afaab6295af0415f Mon Sep 17 00:00:00 2001
From: zvictor <zvictor@users.noreply.github.com>
Date: Thu, 5 Mar 2026 18:33:49 -0300
Subject: [PATCH] set `PAPERCLIP_PUBLIC_URL` in compose files

---
 doc/DOCKER.md                 | 4 ++++
 docker-compose.quickstart.yml | 1 +
 docker-compose.yml            | 1 +
 3 files changed, 6 insertions(+)

diff --git a/doc/DOCKER.md b/doc/DOCKER.md
index b7686984..49d0c4ab 100644
--- a/doc/DOCKER.md
+++ b/doc/DOCKER.md
@@ -42,6 +42,8 @@ Optional overrides:
 PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc docker compose -f docker-compose.quickstart.yml up --build
 ```
 
+If you change host port or use a non-local domain, set `PAPERCLIP_PUBLIC_URL` to the external URL you will use in browser/auth flows.
+
 ## Authenticated Compose (Single Public URL)
 
 For authenticated deployments, set one canonical public URL and let Paperclip derive auth/callback defaults:
@@ -64,6 +66,8 @@ services:
 
 Granular overrides remain available if needed (`PAPERCLIP_AUTH_PUBLIC_BASE_URL`, `BETTER_AUTH_URL`, `BETTER_AUTH_TRUSTED_ORIGINS`, `PAPERCLIP_ALLOWED_HOSTNAMES`).
 
+Set `PAPERCLIP_ALLOWED_HOSTNAMES` explicitly only when you need additional hostnames beyond the public URL host (for example Tailscale/LAN aliases or multiple private hostnames).
+
 ## Claude + Codex Local Adapters in Docker
 
 The image pre-installs:
diff --git a/docker-compose.quickstart.yml b/docker-compose.quickstart.yml
index 373c5d48..66623c75 100644
--- a/docker-compose.quickstart.yml
+++ b/docker-compose.quickstart.yml
@@ -10,5 +10,6 @@ services:
       PAPERCLIP_HOME: "/paperclip"
       OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
       ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+      PAPERCLIP_PUBLIC_URL: "${PAPERCLIP_PUBLIC_URL:-http://localhost:3100}"
     volumes:
       - "${PAPERCLIP_DATA_DIR:-./data/docker-paperclip}:/paperclip"
diff --git a/docker-compose.yml b/docker-compose.yml
index d3cdc6ad..f6d09fd8 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,6 +18,7 @@ services:
       DATABASE_URL: postgres://paperclip:paperclip@db:5432/paperclip
       PORT: "3100"
       SERVE_UI: "true"
+      PAPERCLIP_PUBLIC_URL: "${PAPERCLIP_PUBLIC_URL:-http://localhost:3100}"
     depends_on:
       - db