cpulse — A terminal UI for diagnosing Docker Compose…

Pitch

Description

Comments

About this project

Cpulse provides a live terminal UI that helps diagnose why Docker Compose stacks get stuck. It displays real-time container statuses and a dependency graph, allowing quick identification of issues without sifting through log clutter. Simplify debugging and enhance your development workflow with cpulse.

compose-pulse is a powerful terminal-based user interface designed to diagnose issues within Docker Compose environments efficiently. By providing real-time insights into container states and their interdependencies, compose-pulse simplifies the debugging process, enabling users to understand why their Docker Compose stacks are malfunctioning without wading through extensive log files.

Key Features

Live Monitoring: Observe all Docker containers in real time, ensuring any issues are promptly identified and addressed.
Dependency Visualization: Render the depends_on relationship as an intuitive tree structure, highlighting the relationships between services.
Root Cause Analysis: Quickly identify and understand the underlying causes of service failures, reducing the time spent on troubleshooting.

Service States

Every service is assigned a state glyph, representing its current status. The states include:

Glyph	State	Meaning
`●`	`healthy`	Running, with health checks passing (or none defined)
`◐`	`starting`	Container exists, health check is in progress
`┄`	`blocked`	Waiting on an unsatisfied `depends_on` condition
`┄`	`pending`	Not blocked but does not yet have a container
`✓`	`completed`	Exited successfully after performing its task
`✕`	`failed`	Exited with an error or unknown exit code
`✕`	`unhealthy`	Running but failing health check tests
`⚠`	`degraded`	Running but experiencing an excessive restart loop

This clear separation between healthy and unhealthy containers streamlines the debugging process.

User Interface

Designed with a layout similar to lazydocker, the interface comprises:

A top bar that displays live statistics on service states and the last poll time.
A left column listing projects and dependency trees, complete with state indicators and resource usage data.
A right panel offering detailed views such as logs, performance stats, and health checks for individual services.

Commands

Launching the tool is straightforward. Simply run:

cpulse

This will automatically detect all containers on the local Docker daemon, with Docker Compose-managed containers organized by project.

For a headless diagnosis, running:

cpulse doctor

provides a summary of any critical issues preventing stack operations.

Interaction & Shortcuts

The application features intuitive keyboard shortcuts for navigation and interaction, such as:

Use ↑/↓ to navigate service lists.
Press Enter to zoom into selected services or run health probes.
Access the actions menu with x to manage container states without leaving the interface.

Prerequisites

Requires Docker Desktop or Docker Engine running on macOS or Linux.

This tool significantly enhances the user experience for developers and system administrators managing Docker Compose environments, facilitating swift diagnosis and resolution of stack-related issues.