Clarify and fix docker-git Docker runtime contract: host docker.sock vs isolated controller runtime

[skulidropek]

Problem

docker-git currently depends on the host Docker daemon via /var/run/docker.sock, but the runtime model is easy to misread as an isolated controller-owned Docker environment.

That mismatch turns host socket permission problems into apparent docker-git server outages.

Related: #77 focuses on a sudo-style workaround. This issue is about the architecture/runtime contract itself.

Reproduction

On this machine:

pnpm run docker-git

fails with:

docker-git host CLI cannot access Docker from the client process.
Client-side sudo fallback is disabled.
Keep the docker-git backend container running and reach it via DOCKER_GIT_API_URL or the default local API port, or grant this user direct Docker access (docker group/rootless Docker).
Probe command: docker info

Additional facts from the failing environment:

• docker info and docker ps fail with permission denied on unix:///var/run/docker.sock
• 127.0.0.1:3334/health is not reachable
• /run/docker.sock and /var/run/docker.sock are root:messagebus 660
• the user is in group docker
• docker.service and docker.socket are running, so this does not look like a full Docker daemon outage

Why this is a product bug

From the current UX, it is easy to assume that docker-git owns its own Docker boundary/runtime.
In reality, current implementation is explicitly coupled to the host Docker socket.

That means a host-level socket ownership/group regression can make docker-git appear "down", even though the real failure is only that docker-git is not isolated from host Docker access.

Current implementation evidence

Repository sources currently describe and implement host-socket coupling:

• docker-compose.yml mounts the host socket into the API container:
  • /var/run/docker.sock:/var/run/docker.sock
• packages/api/README.md says:
  • the API talks to Docker through /var/run/docker.sock
• packages/app/src/docker-git/controller-docker.ts probes local Docker access with docker info
• container entrypoint/template code also assumes the runtime Docker socket is /var/run/docker.sock

Expected behavior

The project should choose one explicit contract and make it true end-to-end:

1. Host-Docker-backed controller

   • Keep using the host Docker daemon/socket
   • Make this explicit in docs and CLI diagnostics
   • Distinguish these cases clearly:
     • host daemon down
     • host socket permission mismatch
     • controller container not running/reachable

2. Isolated controller runtime

   • Stop depending on the host /var/run/docker.sock
   • Provide a dedicated Docker endpoint/runtime boundary for docker-git
   • Ensure host socket ownership/group glitches do not break controller bootstrap

Requested outcome

Decide and document the intended runtime contract:

• either docker-git is intentionally host-Docker-backed, with better diagnostics/docs
• or docker-git should own an isolated runtime/socket boundary, and the implementation should be changed to match that model