feat: Docker and docker-compose implementation with mDNS discovery investigation

[luandro]

Draft: Docker Implementation & mDNS Discovery Investigation

Summary

This branch contains:

1. A complete multi-stage Dockerfile for comapeo-local-server
2. Docker Compose configuration with volume persistence and health checks
3. Investigation findings into why mDNS discovery fails in containerized environments

Status: ⚠️ Docker builds and runs successfully, but mDNS peer discovery is not functional in rootless Docker environments. The investigation concludes that running directly on the host with Node is required for proper LAN discovery.

---

What This Branch Adds

Dockerfile (linux/arm64 and linux/amd64)

• Multi-stage build (builder → runtime)
• Compiles native dependencies (better-sqlite3, sodium-native) in builder stage
• Minimal runtime image with pre-compiled modules
• Healthcheck that waits for /data/.ready marker
• Persistent data volume at /data

docker-compose.yml

• network_mode: host for mDNS support
• Persistent volume for CoMapeo state
• Sensible environment defaults (dev-friendly)
• Restart policy: unless-stopped
• Configurable via .env file

---

Investigation Findings

The Problem

When run through docker compose, the daemon starts correctly and logs show mDNS advertisement calls succeeding. However, Android peers cannot discover the containerized instance.

Root Cause

This is a Docker runtime issue, not a CoMapeo daemon bug.

Findings from DOCKER_DISCOVERY_FINDINGS.md:

1. Container sees wrong network interfaces

   • Inside container: tap0 (10.0.2.100), docker0 (172.17.0.1)
   • Host reality: Wi-Fi interface with real LAN address
   • The container does not see the Wi-Fi interface that Android uses

2. Rootless Docker limitation

   • network_mode: host in rootless Docker ≠ true host networking for mDNS
   • The container gets a sandboxed network view that doesn't include the real LAN

3. Verification that daemon logic is correct

   • Running directly with Node on host = discovery works
   • Android sees the service, avahi-browse shows _comapeo._tcp
   • The issue is purely environmental

Conclusion

For mDNS-based peer discovery to work, comapeo-local-server must run directly on the host with Node, not in a Docker container on rootless Docker.

---

Files Changed

• Added: Dockerfile, docker-compose.yml
• Added: DOCKER_DISCOVERY_FINDINGS.md (full investigation report)
• Added: TASKS.md (implementation batches)
• Added: PROGRESS.md (development tracking)
• Modified: Various sync/daemon modules (since removed/reverted in main)

---

Testing

Build

docker build -t comapeo-local-server .

Run

docker compose up

Expected Behavior

• ✅ Container starts successfully
• ✅ Daemon logs show successful startup
• ✅ Healthcheck passes after boot
• ❌ Android peers cannot discover the service (rootless Docker limitation)

---

Recommendations

1. For production: Deploy using systemd on the host (see README.md)
2. For Docker: Would require rootful Docker or alternative mDNS relay setup
3. This branch: Preserved for reference and potential future Docker improvements

---

Related

• Original implementation plan referenced PLAN.md from comapeo-desktop
• Build verified at Node level; full Docker smoke requires Docker daemon