docker-actions

docker-actions is a lightweight CLI tool to manage multiple Docker Compose services in a directory tree using a single command.

It is designed for self-hosted servers and homelabs where many independent services are organized into folders and need to be started, stopped, or inspected cleanly and consistently.

The tool focuses on clarity, safety, and clean terminal output, while preserving Docker Compose’s native colored UI.

---

Features

• Recursively discovers Docker Compose services
• Supports compose.yml and docker-compose.yml
• Stops traversal at service boundaries (prevents dev/test leakage)
• Preserves Docker Compose’s colored, dynamic output
• Clean separation between services in terminal output
• Prints compose file location per service
• Final summary of succeeded and failed services
• Supports any docker compose command
• Dry-run mode
• Parallel execution
• Structured JSON output for automation
• Safe absolute path resolution
• directories having .docker-actions-ignore will be ignored
• Works when installed as a global command

---

Installation

chmod +x /path/to/docker-actions.sh
sudo ln -s /path/to/docker-actions.sh /usr/local/bin/docker-actions

---

Usage

docker-actions <directory> <docker compose arguments> [options]

Examples

docker-actions . up -d
docker-actions ./apps down
docker-actions ./apps restart
docker-actions ./apps pull
docker-actions ./apps status
docker-actions ./apps up -d --dry-run
docker-actions ./apps up -d --parallel
docker-actions ./apps up -d --json

---

Directory Argument

The <directory> argument may be:

• . (current working directory)
• A relative path
• An absolute path

All paths are resolved internally to absolute paths. The script refuses to operate on / for safety.

---

Supported Docker Compose Commands

Any valid docker compose subcommand is supported, including:

• up
• down
• restart
• pull
• ps
• logs
• config

Shortcut

docker-actions ./apps status

Is equivalent to:

docker compose ps

---

Service Discovery Rules

• A directory is treated as a service root if it contains:

  • compose.yml or
  • docker-compose.yml

• Once a service root is found:

  • Subdirectories are not traversed

• This prevents accidentally running nested dev/test compose files

---

Ignoring Directories

To skip a directory and everything under it, create a file:

.docker-actions-ignore

Typical use cases:

• Deprecated services
• Archived stacks
• Experimental folders
• Trash directories

---

Output Behavior

For each service, the tool prints:

• Service name
• Location of the compose file
• Docker Compose’s native colored output
• Final status (SUCCESS or FAILED)
• Execution time

Docker Compose fully controls the terminal while it runs, preventing overlapping or broken output.

---

Final Summary

At the end of execution, a summary is printed:

============================================================
SUMMARY
------------------------------------------------------------
Successful (3):
  ✓ immich
  ✓ uptime-kuma
  ✓ linkding

Failed (1):
  ✗ any-sync-dockercompose
============================================================

This gives an immediate overview without scrolling back through logs.

---

Dry-Run Mode

Preview actions without executing anything:

docker-actions ./apps up -d --dry-run

No containers are started, stopped, or modified.

---

Parallel Execution

Run services concurrently:

docker-actions ./apps up -d --parallel

Useful for large stacks with independent services.

---

JSON Output

Enable structured, machine-readable output:

docker-actions ./apps up -d --json

Example

{
  "target": "/home/docker/sisyphus/apps",
  "command": "docker compose up -d",
  "results": [
    {
      "service": "immich",
      "status": "success",
      "duration": 4.12
    },
    {
      "service": "any-sync-dockercompose",
      "status": "failed",
      "duration": 5.23
    }
  ]
}

When --json is enabled:

• Human-readable output is suppressed
• Output is suitable for scripts, CI, or monitoring tools

---

Exit Codes

• 0 — all services succeeded
• 1 — one or more services failed
• >1 — invalid usage or fatal error

---

Design Philosophy

This tool intentionally avoids:

• Health-check heuristics
• Dependency graphs
• YAML configuration layers
• Kubernetes-style abstractions

Instead, it aims to be:

• Explicit
• Predictable
• Easy to reason about
• Pleasant to use in a terminal

It behaves like a sharp Unix utility, not a platform.

---

Intended Use

• Self-hosted servers
• Homelabs
• Single-node Docker environments
• Internal infrastructure tooling

If you need clustering, autoscaling, or orchestration across nodes, this tool is intentionally not designed for that.

---

Requirements

• Bash
• Docker
• Docker Compose v2 (docker compose)
• realpath
• bc

---

License

This project is open-source and available under the MIT License.