From 3e39c6526579965a33bc106a3fd3e7bf1d01e63b Mon Sep 17 00:00:00 2001
From: Ben Senescu <44480372+bensenescu@users.noreply.github.com>
Date: Tue, 28 Apr 2026 17:39:38 -0400
Subject: [PATCH] docs: clarify self-hosting troubleshooting (#140)

* docs: clarify self-hosting troubleshooting

* docs: simplify Docker env troubleshooting
---
 docs/SELF_HOSTING_CLOUDFLARE.md | 12 ++++++++++--
 docs/SELF_HOSTING_DOCKER.md     | 18 ++++++++++++++++++
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/docs/SELF_HOSTING_CLOUDFLARE.md b/docs/SELF_HOSTING_CLOUDFLARE.md
index ea591f8..6661c7a 100644
--- a/docs/SELF_HOSTING_CLOUDFLARE.md
+++ b/docs/SELF_HOSTING_CLOUDFLARE.md
@@ -85,7 +85,9 @@ Why this is needed:
 
 ## Give teammates access to OpenSEO
 
-To let teammates sign in to OpenSEO, update your Cloudflare Access policy.
+Cloudflare Access makes small-team self-hosting simple: your teammates do not
+need Cloudflare accounts. Add their email addresses to the Access `Allow` policy,
+and Cloudflare will handle the login flow before they reach OpenSEO.
 
 1. Open Cloudflare Zero Trust.
 2. Go to Access -> Applications.
@@ -94,4 +96,10 @@ To let teammates sign in to OpenSEO, update your Cloudflare Access policy.
 5. Add teammate emails (or your company email domain / group).
 6. Save.
 
-After saving, teammates can open your OpenSEO URL and sign in through Cloudflare Access.
+Screenshots from the setup flow:
+
+- [Edit the Access policy](https://github.com/user-attachments/assets/c7bbc7b4-a18e-4ae4-9fe5-3b33c72048a7)
+- [Add teammate emails to the allow list](https://github.com/user-attachments/assets/fa4ecaf2-31f7-4a64-9001-210cf729747b)
+
+After saving, teammates can open your OpenSEO URL and sign in through Cloudflare
+Access. OpenSEO will use a shared workspace for everyone allowed by the policy.
diff --git a/docs/SELF_HOSTING_DOCKER.md b/docs/SELF_HOSTING_DOCKER.md
index 3dee4da..66ef274 100644
--- a/docs/SELF_HOSTING_DOCKER.md
+++ b/docs/SELF_HOSTING_DOCKER.md
@@ -81,3 +81,21 @@ docker compose down
 ```bash
 docker compose down -v
 ```
+
+## Troubleshooting environment variables
+
+To confirm Docker Compose is using the expected environment variables:
+
+```bash
+docker compose config
+```
+
+Check that `AUTH_MODE=local_noauth`, and that `DATAFORSEO_API_KEY` is the base64
+encoded value of your DataForSEO email and API password in this format:
+`email:password`.
+
+If you changed `.env`, recreate the container so Compose reapplies it:
+
+```bash
+docker compose up -d --force-recreate open-seo
+```