Metadata-Version: 2.4
Name: easy-docker-manager
Version: 1.2.0
Summary: Keyboard-driven terminal interface for inspecting local Docker containers
Author: Hamid Arabnejad
License-Expression: MIT
Project-URL: Homepage, https://github.com/arabnejad/edm
Project-URL: Issues, https://github.com/arabnejad/edm/issues
Project-URL: Repository, https://github.com/arabnejad/edm
Keywords: containers,docker,terminal,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docker>=7.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: urwid>=2.6.0
Dynamic: license-file

# Easy Docker Manager

<img src="docs/assets/logo.png" alt="Easy Docker Manager logo" width="200">

[![PyPI](https://img.shields.io/pypi/v/easy-docker-manager?logo=pypi&logoColor=white)](https://pypi.org/project/easy-docker-manager/)
[![Python](https://img.shields.io/pypi/pyversions/easy-docker-manager?logo=python&logoColor=white)](https://pypi.org/project/easy-docker-manager/)
[![Quality](https://github.com/arabnejad/edm/actions/workflows/quality.yml/badge.svg?branch=main)](https://github.com/arabnejad/edm/actions/workflows/quality.yml)
[![Package](https://github.com/arabnejad/edm/actions/workflows/package.yml/badge.svg?branch=main)](https://github.com/arabnejad/edm/actions/workflows/package.yml)
[![Security](https://github.com/arabnejad/edm/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/arabnejad/edm/actions/workflows/security.yml)
[![License: MIT](https://custom-icon-badges.demolab.com/github/license/arabnejad/edm?logo=law&logoColor=white)](https://github.com/arabnejad/edm/blob/main/LICENSE)

[![Open issues](https://custom-icon-badges.demolab.com/github/issues-raw/arabnejad/edm?logo=issue-opened&logoColor=white)](https://github.com/arabnejad/edm/issues)
[![Open pull requests](https://custom-icon-badges.demolab.com/github/issues-pr-raw/arabnejad/edm?logo=git-pull-request&logoColor=white)](https://github.com/arabnejad/edm/pulls)

[![Black](https://img.shields.io/badge/code%20style-black-000000?logo=black&logoColor=white)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/badge/linter-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
[![mypy](https://img.shields.io/badge/type%20checked-mypy-2A6DB2?logo=python&logoColor=white)](https://mypy-lang.org/)
[![CodeQL](https://github.com/arabnejad/edm/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/arabnejad/edm/actions/workflows/github-code-scanning/codeql)

Easy Docker Manager (EDM) lets you inspect local Docker containers from a
keyboard-driven terminal interface. It uses Urwid for the screen and the
Docker Python SDK to read container data.

With EDM, you can view:

- a list of running containers
- recent logs with automatic updates
- container environment variables
- a readable summary of Docker inspection data
- the process list returned by Docker top
- live filtering and sorting of the running-container list
- a separate search query for each container tab
- export of the active tab to a local text file
- a local JSON configuration file

## Demo

![Easy Docker Manager demo](docs/assets/edm-demo.gif)

## Requirements

- Python 3.9 or newer
- Docker installed and running
- permission to access the local Docker daemon
- a terminal window of at least 120 columns by 30 rows

EDM currently supports local Docker only. It accepts the platform's default
local connection, Unix sockets, and Windows named pipes. A `DOCKER_HOST` value
using a remote transport such as TCP or SSH is rejected.

> [!WARNING]
> EDM needs access to the local Docker daemon. This is highly privileged access.
> On Linux, membership in the `docker` group grants root-level privileges. Give
> Docker access only to trusted users, and never make the Docker socket
> world-writable. See Docker's
> [Linux post-installation guidance](https://docs.docker.com/engine/install/linux-postinstall/)
> for supported access options.

## Installation

For normal use, install EDM with `pipx`:

```bash
pipx install easy-docker-manager
```

`pipx` keeps EDM in its own environment and makes the `edm` command available
from your terminal.

You can also install EDM with `pip`. Using a virtual environment keeps it
separate from other Python packages:

```bash
python -m venv .venv
```

Activate the environment on Linux or macOS:

```bash
source .venv/bin/activate
```

Activate it in Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

Or activate it in Windows Command Prompt:

```bat
.venv\Scripts\activate.bat
```

Then install the package from PyPI:

```bash
python -m pip install easy-docker-manager
```

For work on the source code, follow the
[development setup](DEVELOPMENT_GUIDE.md#development-setup).

## Running EDM

Run the installed command:

```bash
edm
```

EDM checks the terminal size before it starts. If the window is smaller than
120 columns by 30 rows, EDM prints the current size and exits. Resize the
terminal and run the command again.

Show the available command options or installed version, or start EDM without
terminal colors:

```bash
edm --help
edm --version
edm --no-color
```

You can also run the Python module directly:

```bash
python -m easy_docker_manager
```

## Keyboard Controls

| Key | Action |
| --- | --- |
| `q` | Quit EDM from the normal screen |
| `Up` / `Down` | Move through containers or detail lines |
| `Enter` | Move keyboard focus to the detail panel |
| `Esc` | Return keyboard focus to the container list |
| `[` | Open the previous detail tab |
| `]` | Open the next detail tab |
| `/` | Start editing the search for the current tab |
| `f` | Start editing the container filter while the container panel is active |
| `s` | Open container sorting while the container panel is active |
| `e` | Export the active tab while the detail panel is active |
| `Page Up` / `Page Down` | Move through the detail panel one page at a time |
| `Home` / `End` | Select the first or last detail line |

While entering a search, press `Enter` to keep the query and return to detail
navigation. Press `Esc` to keep the query and return to the container list.

## Container Filtering

Press `f` while the container panel is active, then type part of a container
name, image name, or status. Matching ignores letter case and updates the list
as you type. It uses the container data already loaded in EDM and does not send
another request to Docker.

```text
* localhost (active)
────────────────────────
 f  Filter: off
 s  Sort: Docker order
────────────────────────
> container-one (running)
  container-two (running)
```

Use `Backspace` to remove the last character. Press `Enter` to keep the edited
filter, or press `Esc` to restore the filter that was active before you pressed
`f`. Other navigation and shortcut keys are disabled until editing ends. Every
printable key, including `q`, becomes part of the query.

The filter and match count are shown below `localhost (active)`, next to the
`f` shortcut. The active sort appears on the next line beside `s`. EDM applies
the selected sort before the filter and reapplies both after each
container-list refresh. If the selected container no longer matches, the first
matching container is selected. Filtering only hides list entries; cached tab
data for hidden running containers is kept.

## Container Sorting

Press `s` while the container panel is active to open this menu:

```text
Sort Containers

  Docker order
> Name
  Image
  Status
  Creation time

Direction: Ascending

Up/Down Field   Left/Right Direction
Enter Apply     Esc Cancel
```

Use `Up` and `Down` to choose a field. Use `Left` for ascending order and
`Right` for descending order. `Enter` applies the choice, while `Esc` closes
the menu without changing the list. The active sort is shown above the
container list, directly below the active filter.

Applying a sort does not change the selected container. The sort stays active
after the container list refreshes. Choose Docker order to restore the order
returned by Docker.

EDM currently shows running containers only, so they usually have the same
status. For this reason, sorting by Status may not visibly change the list.

## Exporting Tab Content

Press `e` while the detail panel is active to export the selected container's
Logs, Env, Config, or Top tab. The popup lets you edit the destination path and
choose one of these scopes:

- **Current view** exports the lines currently shown after a Logs filter. Env,
  Config, and Top searches highlight text without hiding lines, so their
  current view contains all loaded text.
- **Full loaded tab** exports all text currently held in EDM's cache. It does
  not request more data or older logs from Docker.

The suggested path starts in the directory where you launched EDM. Logs use a
`.log` extension; the other tabs use `.txt`. Relative paths are also resolved
from that launch directory. When the path is inside your home directory, the
File field shows the home directory as `~` to keep the path shorter.

While File is selected, printable keys, including `q` and `Q`, edit the path.
Use `Left` and `Right` to move its cursor, `Home` or `End` to jump to either
end, and `Backspace` or `Delete` to remove characters. Use `Up`, `Down`, or
`Tab` to move between File and Scope.

Exports may contain passwords, tokens, URLs, command arguments, or other
sensitive values. EDM shows a warning before every export and writes the text
without hiding values. Review exported files before sharing them. EDM never
replaces an existing file without asking for confirmation.

## Detail Tabs

| Tab | Contents |
| --- | --- |
| Logs | Recent container logs followed by new log output |
| Env | Configured environment variables and their values |
| Config | Selected container and image inspection data |
| Top | Processes reported by Docker top |

Each container and tab keeps its own search query:

- Logs treats the query as a case-insensitive regular expression and hides
  lines that do not match.
- Env, Config, and Top use case-insensitive plain-text search. Matches are
  highlighted, but no lines are removed.
- An invalid Logs regular expression leaves the log text visible.
- Log regular expressions are limited to 200 characters.

## Configuration

EDM uses `platformdirs` to place `config.json` in the correct user config
directory for the operating system. The file is stored in an `EDM` folder.
Typical locations are:

| Operating system | Typical path |
| --- | --- |
| Linux | `~/.config/EDM/config.json` |
| macOS | `~/Library/Application Support/EDM/config.json` |
| Windows | `%LOCALAPPDATA%\EDM\config.json` |

EDM creates this file on first use. On later starts, it keeps valid settings,
fills in missing defaults, removes unknown or invalid values, and writes the
cleaned configuration back to the file.

| Setting | Default | Purpose |
| --- | ---: | --- |
| `container_list_refresh_interval_seconds` | `2.0` | Seconds between running-container refreshes |
| `tab_refresh_interval` | `2.0` | Seconds between reloads of the visible Env, Config, or Top tab |
| `initial_log_tail_lines` | `100` | Number of recent lines loaded when Logs first opens |
| `max_log_lines` | `2000` | Maximum log lines kept for one container |
| `max_log_line_chars` | `4000` | Maximum characters kept from one log line (minimum `32`) |
| `tab_content_cache_max_entries` | `50` | Maximum number of cached container tabs |
| `tab_content_cache_max_bytes` | `25000000` | Maximum UTF-8 size of all cached tab text |
| `docker_request_timeout` | `10.0` | Docker SDK request timeout in seconds |
| `max_background_worker_threads` | `4` | Maximum number of background worker threads |
| `colors_enabled` | `true` | Use terminal colors; set to `false` for monochrome output |

`edm --no-color` disables colors for one run without changing `config.json`.

## Application Logs

EDM writes its own application messages to `edm.log` beside `config.json`.
This file contains EDM errors and diagnostic messages, not container logs. It
rotates at 5 MB and keeps three backup files.

These environment variables can change the logging setup:

| Variable | Purpose |
| --- | --- |
| `EDM_LOG_FILE` | Write to a different log file |
| `EDM_LOG_LEVEL` | Set the level, such as `DEBUG` or `WARNING` |
| `EDM_LOG_STDOUT` | Also write logs to standard output when enabled |

`EDM_LOG_STDOUT` is disabled for `0`, `false`, `no`, or `off`. Other values
enable it. If EDM cannot create the log file, it prints a warning to the
terminal and continues to start.

## Development Checks

Run the normal formatting, linting, type, and source-security checks:

```bash
make check
```

Useful individual commands are:

```bash
make black
make black-check
make ruff
make ruff-fix
make mypy
make bandit
make test
make integration-test
make smoke-test
make pre-commit
make audit
make security
make package-check
```

`make audit` checks installed dependencies for known vulnerabilities. It needs
Python 3.10 or newer and network access, so it is not part of `make check`.

`make test` prints statement and branch coverage after the unit tests finish.
`make integration-test` starts a temporary Alpine container and checks container
listing, logs, environment variables, inspection data, and process information.
It requires access to a running local Docker daemon.
`make smoke-test` checks package imports, platform paths, notifier selection,
and basic startup on the current operating system.

GitHub Actions runs Black, Ruff, mypy, and Bandit once on Python 3.12. It runs
the unit tests on Python 3.9 through 3.14, runs the Docker integration tests on
Python 3.12, runs wheel smoke tests on Windows and macOS, and verifies the
minimum supported runtime dependency versions on Python 3.9. It also checks
dependencies and committed secrets, builds the source distribution and wheel,
and installs the wheel on every supported Python version. Dependabot checks
Python packages and GitHub Actions each week.

Workflow actions are pinned to full commit SHAs so CI always runs the exact
reviewed action code instead of a movable version tag. The comment beside each
SHA shows its release version, and Dependabot proposes SHA updates when newer
releases are available.

See [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md) for the code structure,
runtime flow, and instructions for extending EDM.

## Contributing

Bug reports, feature ideas, and code contributions are welcome. Read
[CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

Please report security problems privately by following
[SECURITY.md](SECURITY.md). Do not include sensitive vulnerability details in
a public issue.

## License

Easy Docker Manager is available under the [MIT License](LICENSE).
