docker-service-discovery/openspec/changes/archive/2026-03-27-docker-service-display/design.md

Context

The goal is to create a web-based tool that provides a real-time overview of services running in a local Docker environment. This is for developers who run multiple services and need a quick way to see what's running and how to access it. The tool will read from the Docker socket to get this information.

Goals / Non-Goals

Goals:

• Provide a unified dashboard of all running Docker services that expose ports.
• Prioritize services managed by Traefik, displaying the user-friendly URL.
• The application should be a single, self-contained service.
• The UI should be clean, simple, and update in near real-time.

Non-Goals:

• This tool will not manage Docker services (start, stop, restart). It is read-only.
• It will not provide detailed service metrics (CPU, memory).
• It will not have an authentication mechanism, as it is intended for local use.

Decisions

• Backend: A Node.js server using the Express framework. It will use the dockerode library to interact with the Docker socket. This provides a good balance of performance and ease of development.
• Frontend: A single-page application built with React. This will allow for a dynamic and responsive user interface.
• Communication: The frontend will communicate with the backend via a REST API. The backend will expose an endpoint that returns a list of services.
• Deployment: The application will be packaged as a single Docker container for easy deployment.

Risks / Trade-offs

• Security Risk: Access to the Docker socket is equivalent to root access on the host machine. The application must be run in a trusted environment.
  • Mitigation: The documentation will clearly state the security implications. The application will be bound to localhost by default to minimize exposure.
• Performance: Polling the Docker socket for changes can be inefficient.
  • Mitigation: The backend will use Docker events to listen for changes in real-time, avoiding constant polling.