From 540d7476fb2a3ec812720158f797a3a916eadeba Mon Sep 17 00:00:00 2001
From: Bernhard Guillon <Bernhard.Guillon@begu.org>
Date: Tue, 7 Jul 2026 11:49:16 +0200
Subject: Switch from Unix sockets to TCP for Docker Desktop compatibility

Architecture:
- Container acts as TCP server (listens on :5151)
- Windows binary connects as TCP client
- Same protocol: newline-delimited JSON

Usage:
  docker run -p 5151:5151 -v C:\src:/host:ro -v data:/data sourcewatch
  sourcewatch.exe -dir C:\src -connect localhost:5151

This avoids Docker Desktop's inability to mount Windows Unix sockets
into Linux containers (they become directories instead of files).
---
 README.md | 57 ++++++++++++++++++++++++++++-----------------------------
 1 file changed, 28 insertions(+), 29 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index d0bcd01..0fd0e23 100644
--- a/README.md
+++ b/README.md
@@ -7,17 +7,18 @@ A file synchronization tool that watches a Windows source directory and syncs ch
 ```
 Windows Host                          Docker Container
 ┌─────────────────────┐              ┌─────────────────────────┐
-│ sourcewatch.exe     │              │ sourcewatch (linux)     │
-│   watches C:\src    │   AF_UNIX    │   - receives manifest   │
-│   ReadDirectory     │◄────────────►│   - syncs changed files │
-│     ChangesW        │   socket     │   - listens for events  │
+│ sourcewatch.exe     │     TCP      │ sourcewatch (linux)     │
+│   watches C:\src    │◄────────────►│   - receives manifest   │
+│   ReadDirectory     │  connect     │   - syncs changed files │
+│     ChangesW        │  :5151       │   - listens for events  │
 └─────────────────────┘              └─────────────────────────┘
 ```
 
-1. **Windows binary** scans source directory (fast native NTFS) and sends file metadata
-2. **Container** compares with local state, copies only changed files
-3. **Windows binary** watches for changes, sends events over socket
-4. **Container** receives events and syncs in real-time
+1. **Container** starts and listens on TCP port 5151
+2. **Windows binary** connects to container, scans source directory (fast native NTFS), sends file metadata
+3. **Container** compares with local state, copies only changed files
+4. **Windows binary** watches for changes, sends events over TCP
+5. **Container** receives events and syncs in real-time
 
 ## Building
 
@@ -51,21 +52,10 @@ podman build -t sourcewatch .
 GOOS=windows GOARCH=amd64 go build -o sourcewatch.exe .
 ```
 
-### Step 2: Start the Windows watcher
+### Step 2: Start the container
 
 ```bash
-# PowerShell
-.\sourcewatch.exe -dir C:\myproject -socket D:\sourcewatch.sock
-
-# Git Bash
-./sourcewatch.exe -dir /c/myproject -socket /d/sourcewatch.sock
-```
-
-### Step 3: Start the container
-
-```bash
-docker run -d \
-  -v D:\sourcewatch.sock:/run/sourcewatch.sock \
+docker run -d -p 5151:5151 \
   -v C:\myproject:/host:ro \
   -v project-data:/data \
   sourcewatch
@@ -74,19 +64,28 @@ docker run -d \
 Or with Podman:
 
 ```bash
-podman run -d \
-  -v D:\sourcewatch.sock:/run/sourcewatch.sock \
+podman run -d -p 5151:5151 \
   -v C:\myproject:/host:ro \
   -v project-data:/data \
   sourcewatch
 ```
 
+### Step 3: Start the Windows watcher
+
+```powershell
+# PowerShell
+.\sourcewatch.exe -dir C:\myproject -connect localhost:5151
+
+# Git Bash
+./sourcewatch.exe -dir /c/myproject -connect localhost:5151
+```
+
 ### Standalone mode (no Windows watcher)
 
-If you don't need real-time watching, run without `-socket`:
+If you don't need real-time watching, run with `-listen ""`:
 
 ```bash
-docker run -v /path/to/source:/host:ro -v data:/data sourcewatch
+docker run -v /path/to/source:/host:ro -v data:/data sourcewatch -listen ""
 ```
 
 ## Flags
@@ -95,7 +94,7 @@ docker run -v /path/to/source:/host:ro -v data:/data sourcewatch
 
 ```
 -dir string       Source directory to watch (required)
--socket string    Unix socket path to serve events on (required)
+-connect string   TCP address of the container (default "localhost:5151")
 -log-level string Log level: debug, info, warn, error, none (default "info")
 -verbose          Enable verbose logging (shorthand for -log-level debug)
 ```
@@ -105,7 +104,7 @@ docker run -v /path/to/source:/host:ro -v data:/data sourcewatch
 ```
 -host string       Host source directory (default "/host")
 -data string       Data destination directory (default "/data")
--socket string     Unix socket to receive events from (default "/run/sourcewatch.sock")
+-listen string     TCP address to listen on (default ":5151")
 -verbose           Enable verbose logging (shorthand for -log-level debug)
 -log-level string  Log level: debug, info, warn, error, none (default "info")
 -dry-run           Preview what would be synced without copying
@@ -113,7 +112,7 @@ docker run -v /path/to/source:/host:ro -v data:/data sourcewatch
 
 ## Protocol
 
-Communication uses newline-delimited JSON over Unix socket:
+Communication uses newline-delimited JSON over TCP:
 
 ```json
 {"type":"manifest","files":{"path":{"size":1234,"modtime":"2024-01-01T00:00:00Z","mode":"0644"}}}
@@ -142,7 +141,7 @@ build/
 - One-way sync only (`/host` → `/data`)
 - `/host` must be read-only
 - `?` single-character wildcard not supported (go-gitignore limitation)
-- Windows binary requires Go 1.24+ to build
+- Windows binary requires Go 1.21+ to build
 
 ## License
 
-- 
cgit v1.2.3