From ffe3806d43c420197fcb092392845dc89c700e33 Mon Sep 17 00:00:00 2001
From: Claude Agent <claude-agent@romfast.ro>
Date: Tue, 28 Apr 2026 11:54:53 +0000
Subject: [PATCH] docs(lxc103): document overlay network race condition + heal
 script fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug confirmat Dokploy #2033 + docker/compose #12862: Docker Compose containers
cu external overlay network pică la restart Docker (exit 128, network not found).
Documentat cauza, fix-ul generic dokploy-compose-heal.service și fix-ul DNS daemon.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 proxmox/lxc103-dokploy/README.md | 82 +++++++++++++++++++++++++++++++-
 1 file changed, 81 insertions(+), 1 deletion(-)

diff --git a/proxmox/lxc103-dokploy/README.md b/proxmox/lxc103-dokploy/README.md
index d0f9bf0..a07f9f9 100644
--- a/proxmox/lxc103-dokploy/README.md
+++ b/proxmox/lxc103-dokploy/README.md
@@ -222,6 +222,86 @@ systemctl restart dokploy-dnsrr-fix
 
 ---
 
+## Fix: Docker Compose — Overlay Network Race Condition la Restart (Bug Permanent Rezolvat)
+
+### Problema
+
+Proiectele **Docker Compose** din Dokploy (ex: space-booking) care folosesc
+`dokploy-network` ca rețea externă (`external: true`) **pică la restart Docker**.
+
+Eroarea din `docker inspect <container>`:
+```
+failed to set up container networking: could not find a network matching
+network mode dokploy-network: network dokploy-network not found
+```
+Container-ul iese cu **exit code 128** și nu mai pornește singur.
+
+### Cauza
+
+Race condition confirmat în:
+- **Dokploy** issues #2033, #1802 — fără fix livrat
+- **Docker Compose** upstream issue #12862 — nerezolvat (aprilie 2026)
+
+La restart Docker daemon:
+1. Docker Swarm inițializează rețelele overlay (`dokploy-network`) — durează câteva secunde
+2. Docker Compose containers cu `restart: unless-stopped` pornesc **imediat**
+3. `dokploy-network` nu e încă disponibilă → exit 128
+
+Serviciile **Swarm** (Application type în Dokploy) nu au această problemă —
+orchestratorul știe să aștepte rețelele înainte de a programa task-urile.
+
+### De ce Docker Compose în loc de Application (Swarm)
+
+Proiectele multi-serviciu (ex: frontend + backend) rămân Compose deoarece
+serviciile comunică intern între ele (ex: nginx `proxy_pass http://backend:8000`
+pe o rețea bridge shared). Conversia la Swarm Application ar necesita modificări
+în codul aplicației.
+
+### Soluția
+
+Script generic care rulează la boot, așteaptă `dokploy-network` și repornește
+**orice** container Compose eșuat din cauza lipsei rețelei:
+
+```bash
+# Script: /usr/local/bin/dokploy-compose-heal.sh
+# Service: /etc/systemd/system/dokploy-compose-heal.service (enabled)
+```
+
+Logica scriptului:
+- Polling `dokploy-network` disponibil (max 90s, interval 3s)
+- Caută containere cu `exit code 128` + eroare "network" + label `com.docker.compose.project`
+- Le repornește — **nu atinge** containerele oprite intenționat (exit 0)
+
+```bash
+# Verificare status
+systemctl status dokploy-compose-heal
+
+# Logs la ultimul boot
+journalctl -u dokploy-compose-heal -n 30
+
+# Rulare manuală (după un docker restart neașteptat)
+systemctl start dokploy-compose-heal
+```
+
+### Fix aditional: DNS Docker daemon
+
+Docker containers foloseau implicit DNS-ul Tailscale (`100.100.100.100`)
+care **nu e accesibil** din interiorul containerelor — Dokploy primea
+`ESERVFAIL` la validarea domeniilor.
+
+Fix aplicat în `/etc/docker/daemon.json`:
+```json
+{"dns": ["8.8.4.4", "8.8.8.8"]}
+```
+
+### Pentru orice proiect Compose nou în Dokploy
+
+1. Adaugă domeniul în **Dokploy UI → Domains → Add Domain** (nu doar în labels din docker-compose.yml)
+   — Dokploy generează `.yml` static în Traefik dynamic config, persistent la restart
+2. Dacă containerul pică după restart Docker → `systemctl start dokploy-compose-heal` rezolvă automat
+
+---
+
 ## Documentație Asociată
 
 - **Arhitectură completă IIS:** `../vm201-windows/docs/vm201-dokploy-infrastructure.md`
@@ -233,6 +313,6 @@ systemctl restart dokploy-dnsrr-fix
 
 ---
 
-**Ultima actualizare:** 2026-03-03
+**Ultima actualizare:** 2026-04-28
 **Autor:** Marius Mutu
 **Proiect:** ROMFASTSQL - LXC 103 Dokploy