shell/docker-manager/README.md

Docker Manager

A Python command-line application to manage Docker containers defined in subdirectories of ~/docker/.

Features

• Rich UI: Beautiful terminal output using the rich library, including tables, panels, and colored status indicators.
• List: View currently running containers across all your projects.
  • Diun Integration: Automatically detects if Diun is running and displays image versions and update availability directly in the list.
• Describe: Show detailed information about containers in a specific project, including descriptions, ports, and a formatted table of volumes.
• Volumes: List all volumes used by a specific project with source and destination details.
• Logs: View logs for a project, with options to follow, tail, and filter by specific container/service.
• Stop: Stop containers for a specific project or all projects.
• Update: Pull the latest images and recreate containers (equivalent to docker compose pull && docker compose up -d).
• Restart: Restart containers for a specific project or all projects.

Prerequisites

• Python 3
• Docker and Docker Compose (plugin) installed.
• The rich Python library:

  pip install rich
  

• A ~/docker/ directory containing subdirectories for each of your projects.
• Each project subdirectory must contain a docker-compose.yml, docker-compose.yaml, compose.yml, or compose.yaml file.

Installation

1. Ensure the script is executable:

   chmod +x ~/shell/docker-manager/docker-manager.py
   

2. Make it accessible from anywhere: You can create a symbolic link to a directory in your $PATH (e.g., ~/.local/bin or /usr/local/bin), or add an alias.

   Option A: Symbolic Link (Recommended)

   mkdir -p ~/.local/bin
   ln -s ~/shell/docker-manager/docker-manager.py ~/.local/bin/dm
   

   Note: Ensure ~/.local/bin is in your $PATH.

   Option B: Alias Add the following to your ~/.zshrc or ~/.bashrc:

   alias dm='~/shell/docker-manager/docker-manager.py'
   

Usage

Run the application using the command name you set up (e.g., dm).

List Running Containers

Displays a table with Project, Container Name, State, Image, Version, and Update Status.

dm list

Describe Project

Show detailed info (Service, Image, State, Ports, Description, Volumes) for a project.

dm describe project_name

List Volumes

Show a table of all volumes (Bind mounts and named volumes) for a project.

dm volumes project_name

View Logs

View logs for a project.

dm logs project_name

Options:

• Follow output: dm logs project_name -f
• Tail specific number of lines: dm logs project_name --tail 100
• Filter by container: dm logs project_name container_name
  • Example: dm logs media gluetun --tail 50

Stop Containers

Stop a specific project:

dm stop project_name

Stop all projects:

dm stop --all

Update Containers

Pull latest images and recreate containers for a specific project:

dm update project_name

Update all projects:

dm update --all

Restart Containers

Restart a specific project:

dm restart project_name

Restart all projects:

dm restart --all

Directory Structure Example

The tool expects a structure like this:

~/docker/
├── media-server/
│   └── docker-compose.yml
├── web-app/
│   └── compose.yml
└── database/
    └── docker-compose.yml

In this example, the project names are media-server, web-app, and database.