feat: init

openspec/changes/docker-service-display/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-27

openspec/changes/docker-service-display/design.md

@@ -0,0 +1,30 @@
+## 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.

openspec/changes/docker-service-display/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+This change introduces a web interface to display information about running Docker services that have exposed ports, making it easier to get an overview of the services running on a host.
+
+## What Changes
+
+- A new backend service that connects to the Docker socket (`docker.sock`).
+- A new frontend application that displays the service information.
+- The service will list all Docker services with exposed ports.
+- Services exposed via Traefik will be prioritized and displayed prominently.
+- The web interface will use a card-based layout to show each service.
+
+## Capabilities
+
+### New Capabilities
+- `docker-service-discovery`: Discovers running Docker services and their exposed ports.
+- `service-display-frontend`: A web interface to display the discovered services.
+
+### Modified Capabilities
+- None
+
+## Impact
+
+- This change will introduce a new web service to the host.
+- It will require access to the Docker socket, which has security implications that need to be considered.

openspec/changes/docker-service-display/specs/docker-service-discovery/spec.md

@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Discover running Docker containers
+The system SHALL discover all running Docker containers on the host.
+
+#### Scenario: Containers are running
+- **WHEN** the service starts
+- **THEN** the system has a list of all running containers.
+
+### Requirement: Identify services with exposed ports
+The system SHALL identify which of the running containers have exposed ports.
+
+#### Scenario: Container with exposed ports
+- **WHEN** a container is running with a port mapping
+- **THEN** the system identifies the container and its exposed port.
+
+#### Scenario: Container without exposed ports
+- **WHEN** a container is running without any port mappings
+- **THEN** the system ignores this container.
+
+### Requirement: Prioritize Traefik services
+The system SHALL identify services that are managed by Traefik and extract the public-facing URL.
+
+#### Scenario: Traefik service
+- **WHEN** a container has Traefik labels (e.g., `traefik.http.routers.my-service.rule`)
+- **THEN** the system SHALL extract the router rule and present it as the primary URL for the service.

openspec/changes/docker-service-display/specs/service-display-frontend/spec.md

@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Display services in a card layout
+The frontend SHALL display each discovered service as a card.
+
+#### Scenario: Services are discovered
+- **WHEN** the frontend receives a list of services from the backend
+- **THEN** it SHALL render a card for each service.
+
+### Requirement: Show service details on each card
+Each service card SHALL display the service name, the exposed port, and the URL to access it.
+
+#### Scenario: Displaying a service
+- **WHEN** a service is displayed
+- **THEN** the card SHALL show the service name, port, and URL.
+
+### Requirement: Real-time updates
+The frontend SHALL update in near real-time when services are started or stopped.
+
+#### Scenario: A new service is started
+- **WHEN** a new service is started on the host
+- **THEN** a new card for that service SHALL appear in the frontend without requiring a page refresh.
+
+#### Scenario: A service is stopped
+- **WHEN** a service is stopped on the host
+- **THEN** the corresponding card SHALL be removed from the frontend without requiring a page refresh.

openspec/changes/docker-service-display/tasks.md

@@ -0,0 +1,34 @@
+## 1. Backend Setup
+
+- [x] 1.1 Initialize a new Node.js project for the backend.
+- [x] 1.2 Add dependencies: `express`, `dockerode`, and `cors`.
+- [x] 1.3 Create a basic Express server.
+- [x] 1.4 Configure the server to listen on a specific port.
+
+## 2. Docker Service Discovery
+
+- [x] 2.1 Implement a function to connect to the Docker socket using `dockerode`.
+- [x] 2.2 Create a function to list all running containers.
+- [x] 2.3 Filter the list of containers to include only those with exposed ports.
+- [x] 2.4 Implement logic to identify Traefik services and extract their URLs from container labels.
+- [x] 2.5 Create a REST API endpoint (`/api/services`) that returns the list of discovered services.
+- [x] 2.6 Implement real-time updates using Docker events to watch for container start and stop events.
+
+## 3. Frontend Setup
+
+- [x] 3.1 Initialize a new React project for the frontend.
+- [x] 3.2 Add dependencies: `axios` for making API requests.
+- [x] 3.3 Create a basic layout for the application.
+
+## 4. Frontend Implementation
+
+- [x] 4.1 Create a function to fetch the list of services from the backend API.
+- [x] 4.2 Create a `ServiceCard` component to display the information for a single service.
+- [x] 4.3 Implement the main view to display a grid of `ServiceCard` components.
+- [x] 4.4 Implement real-time updates on the frontend, either through polling or a WebSocket connection.
+
+## 5. Dockerization
+
+- [x] 5.1 Create a `Dockerfile` for the backend service.
+- [x] 5.2 Create a `Dockerfile` for the frontend service.
+- [x] 5.3 Create a `docker-compose.yml` file to run both services together.