Docker-Stacks/frappe-crm-erp
Watch
1
0
Fork
You've already forked frappe-crm-erp
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: document per-container filesystem isolation pitfall #2

Merged
csaeum merged 3 commits from fix/docs-container-isolation-pitfall into main 2026-07-25 18:36:09 +00:00
Conversation 0 Commits 3 Files changed 4 +94 -36
csaeum commented 2026-07-25 18:02:08 +00:00
Owner
Copy link

Zusammenfassung

Lange Debugging-Sitzung im LeadScraper-Projekt: Neue Funktionen (Territory-Anlage, Herkunfts-Notiz) funktionierten über bench execute, aber nicht über echte Hintergrund-Jobs (frappe.enqueue, z.B. jeder CRM-UI-Suchlauf) — ohne jeden Fehler im Error Log.

Root Cause: backend, websocket, queue-short, queue-long, scheduler sind trotz gleichem Image separate Container mit je eigener beschreibbarer Schicht. docker cp in backend erreicht queue-long (der Container, der Hintergrund-Jobs tatsächlich ausführt) nie. Kein Fehler sichtbar, weil einfach eine ältere Code-Version ohne die neue Funktion lief.

Zusätzlich: rekursives docker cp ordner/. container:/ziel/ hat sich als unzuverlässig erwiesen (meldet Erfolg, kopiert aber nicht immer alles) — Einzeldatei-Kopie + Verifikation ist der zuverlässige Weg.

Neuer Abschnitt 9b in docs/install.md dokumentiert das für künftige manuelle Test-Iterationen (ohne vollständigen Image-Rebuild).

## Zusammenfassung Lange Debugging-Sitzung im LeadScraper-Projekt: Neue Funktionen (Territory-Anlage, Herkunfts-Notiz) funktionierten über `bench execute`, aber nicht über echte Hintergrund-Jobs (`frappe.enqueue`, z.B. jeder CRM-UI-Suchlauf) — ohne jeden Fehler im Error Log. **Root Cause:** `backend`, `websocket`, `queue-short`, `queue-long`, `scheduler` sind trotz gleichem Image **separate Container mit je eigener beschreibbarer Schicht**. `docker cp` in `backend` erreicht `queue-long` (der Container, der Hintergrund-Jobs tatsächlich ausführt) nie. Kein Fehler sichtbar, weil einfach eine ältere Code-Version ohne die neue Funktion lief. Zusätzlich: rekursives `docker cp ordner/. container:/ziel/` hat sich als unzuverlässig erwiesen (meldet Erfolg, kopiert aber nicht immer alles) — Einzeldatei-Kopie + Verifikation ist der zuverlässige Weg. Neuer Abschnitt 9b in `docs/install.md` dokumentiert das für künftige manuelle Test-Iterationen (ohne vollständigen Image-Rebuild).
Spent a long debugging session chasing what looked like a stale-cache
bug in LeadScraper (missing territory/notes only when triggered via a
real background job, never via bench execute). Root cause: backend,
websocket, queue-short, queue-long and scheduler are separate
containers from the same image, each with its own writable layer -
docker cp into backend never reached queue-long, which is the one that
actually executes background jobs. No error surfaced anywhere because
the older code simply didn't have the new function, and
AttributeError only showed up when specifically grepping queue-long's
own logs.

Also noting that recursive `docker cp dir/. container:/path/` proved
unreliable in this environment (reports success, doesn't always fully
copy) - per-file copy + explicit verification is the reliable pattern.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Two real bugs found while actually switching the running stack over to
docker-compose.dev-apps.yml (previously only built and documented, never
used in practice):

1. LEADSCRAPER_SRC_PATH pointed at the inner leadscraper/ package folder
   instead of the repo root. bench/pip expect apps/<name> to look like a
   real `git clone` target (pyproject.toml, README.md, and the actual
   leadscraper/ package as a subfolder) - mounting the package folder
   directly onto apps/leadscraper removed a nesting level and broke
   `import leadscraper` entirely (ModuleNotFoundError, not even a subtle
   bug - nothing worked).

2. docker-compose.override.yml is only auto-loaded when `docker compose
   up` runs with zero -f flags. Adding any -f (as required to include
   dev-apps.yml) replaces the automatic file selection entirely -
   override.yml must be listed explicitly or the local port mapping is
   silently missing (stack starts fine, port 8080 just isn't published).
   The dev-apps.yml usage comment and README.md section 7 both asserted
   the opposite; fixed both plus added an explicit warning.

Verified against the running stack: `import leadscraper.lead_scraper.
crm_lead_sync` succeeds, a live host-side edit is immediately visible in
both queue-long and websocket without any docker cp, and login works
with all three compose files included.
README.md and docs/install.md each had the local/dev-mount/live start
commands scattered across separate sections, which is exactly how the
override.yml auto-load caveat got missed in one place while documented
correctly in another. Both docs now have a single "Startbefehle-Referenz"
table (Lokal Standard / Lokal + Dev-Mount / Live) listing the exact
compose files used per scenario and the override.yml warning once,
right next to the commands. Section 7 (dev-apps) now points back to
this table instead of repeating the command.
csaeum merged commit 94becbabd5 into main 2026-07-25 18:36:09 +00:00
csaeum deleted branch fix/docs-container-isolation-pitfall 2026-07-25 18:36:09 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Docker-Stacks/frappe-crm-erp!2
No description provided.