Metadata-Version: 2.4
Name: composure
Version: 0.1.3
Summary: A terminal tool to audit, optimize, and visualize Docker-Compose stacks in real-time
Author-email: James Dimonaco <your-email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/JamesDimonaco/composure
Project-URL: Repository, https://github.com/JamesDimonaco/composure
Project-URL: Issues, https://github.com/JamesDimonaco/composure/issues
Keywords: docker,docker-compose,containers,devops,monitoring,tui,terminal,optimization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docker>=7.1.0
Requires-Dist: ruamel-yaml>=0.18.0
Requires-Dist: textual>=0.40.0
Requires-Dist: typer>=0.9.0
Dynamic: license-file

# Composure

A terminal tool to audit, optimize, and visualize Docker-Compose stacks in real-time.

![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)
![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)

## What is Composure?

Composure is a TUI (Terminal User Interface) dashboard that helps you:

- **Monitor** all your Docker containers in real-time
- **Detect waste** by comparing actual resource usage vs allocated limits
- **Visualize networks** to see how containers connect to each other
- **Control containers** directly from the terminal (start, stop, restart, view logs)

## Features

- **Resource Monitoring**: See CPU and memory usage for all containers
- **Waste Detection**: Identify over-provisioned containers with waste scores
- **Limit Awareness**: Quickly spot containers without resource limits
- **Network Visualization**: Tree view showing container network topology
- **Container Controls**: Start, stop, restart containers with keyboard shortcuts
- **Live Logs**: View recent logs for any container
- **Parallel Loading**: Fast startup even with many containers

## Installation

### Using pip (recommended)

```bash
pip install composure
```

### Using uv

```bash
uv tool install composure
```

### Using Docker

```bash
docker run -it -v /var/run/docker.sock:/var/run/docker.sock jamesdimonaco/composure
```

### Debian/Ubuntu (apt)

```bash
# Add the repository
curl -fsSL https://jamesdimonaco.github.io/composure/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/composure.gpg
echo "deb [signed-by=/usr/share/keyrings/composure.gpg] https://jamesdimonaco.github.io/composure stable main" | sudo tee /etc/apt/sources.list.d/composure.list

# Install
sudo apt update
sudo apt install composure
```

### From source

```bash
git clone https://github.com/JamesDimonaco/composure.git
cd composure
uv sync
uv run composure
```

## Usage

Simply run:

```bash
composure
```

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `q` | Quit |
| `r` | Refresh |
| `n` | Toggle network view |
| `s` | Stop selected container |
| `a` | Start selected container |
| `x` | Restart selected container |
| `l` | Show logs for selected container |
| `?` | Show help |
| `↑/↓` | Navigate containers |

## Understanding the Dashboard

### Main View

```
Container     Status   CPU %  CPU Limit  RAM Used  RAM Limit  Efficiency  Waste
nginx         running  0.5%   2 cores    45 MB     512 MB     LOW         90
api           running  2.1%   No limit   128 MB    256 MB     MEDIUM      40
postgres      running  1.2%   1 core     256 MB    512 MB     GOOD        20
```

### Columns Explained

- **Status**: running, exited, paused, etc.
- **CPU %**: Current CPU usage
- **CPU Limit**: Configured CPU limit (or "No limit")
- **RAM Used**: Current memory usage
- **RAM Limit**: Configured memory limit (or "No limit")
- **Efficiency**: LOW/MEDIUM/GOOD/HIGH based on resource utilization
- **Waste**: 0-100 score (higher = more over-provisioned)

### Waste Score

The waste score helps identify containers that have been allocated far more resources than they're using:

- **0-30** (green): Good utilization
- **30-60** (yellow): Could be optimized
- **60-100** (red): Significantly over-provisioned

### Network View

Press `n` to see a tree view of your Docker networks:

```
Docker Networks
├── Compose Networks
│   └── myapp_default (3 containers)
│       ├── nginx
│       ├── api
│       └── postgres
└── System Networks
    └── bridge (empty)
```

## Requirements

- Python 3.9+
- Docker Engine running locally
- Access to Docker socket

## Development

```bash
# Clone the repo
git clone https://github.com/JamesDimonaco/composure.git
cd composure

# Install dependencies
uv sync

# Run in development
uv run composure

# Run tests
uv run pytest
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgments

Built with:
- [Textual](https://github.com/Textualize/textual) - TUI framework
- [docker-py](https://github.com/docker/docker-py) - Docker SDK for Python
- [Typer](https://github.com/tiangolo/typer) - CLI framework
