🌊 dockerwave

CLI tool to manage multi-container Docker environments using declarative YAML manifests — spin up full stacks with a single command.

---

📐 Architecture

┌─────────────────────────────────────────────────────┐
│               wave.yaml manifest                    │
│         services │ volumes │ env vars               │
└──────────────────────┬──────────────────────────────┘
                       │
         ┌─────────────▼─────────────┐
         │     Manifest Loader       │
         │  env interpolation        │
         │  depends_on topo sort     │
         └─────────────┬─────────────┘
                       │
         ┌─────────────▼─────────────┐
         │      Docker SDK           │
         │  networks │ volumes       │
         │  containers               │
         └──────┬──────────┬─────────┘
                │          │
   ┌────────────▼──┐  ┌────▼──────────────┐
   │  Rich Status  │  │  Health Checker   │
   │    Table      │  │  (HTTP polling)   │
   └───────────────┘  └───────────────────┘

📁 Project Structure

dockerwave/
├── dockerwave/
│   ├── commands/
│   │   ├── up.py             # Start all services
│   │   ├── down.py           # Stop and remove services
│   │   ├── status.py         # Rich status table
│   │   ├── logs.py           # Multiplexed log streaming
│   │   └── init_cmd.py       # Init from template
│   ├── templates/
│   │   ├── web-stack/        # Nginx + API + Postgres
│   │   ├── data-stack/       # Postgres + Redis + Adminer
│   │   └── monitoring-stack/ # Prometheus + Grafana + Node Exporter
│   ├── utils/
│   │   ├── manifest.py       # wave.yaml loader + env interpolation
│   │   ├── docker_client.py  # Docker SDK wrapper
│   │   └── healthcheck.py    # HTTP health polling
│   └── cli.py                # Click CLI entrypoint
├── tests/
│   └── test_manifest.py
├── conftest.py
├── pyproject.toml
├── requirements.txt
└── README.md

🚀 Quick Start

# 1. Clone
git clone https://github.com/hugpaim/dockerwave.git
cd dockerwave

# 2. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install
pip install -r requirements.txt
pip install -e .

# 4. Create a new environment from template
dockerwave init --template data-stack my-app
cd my-app

# 5. Start everything
dockerwave up

⚙️ Commands

Command	Description
dockerwave init --template <name> <dir>	Create environment from template
dockerwave up	Start all services
dockerwave down	Stop and remove containers
dockerwave down --volumes	Stop and remove containers + volumes
dockerwave restart	Restart all services
dockerwave status	Show running containers table
dockerwave logs --follow	Tail logs from all services

📄 wave.yaml Example

name: my-app
version: "1.0"

env_file: .env

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    healthcheck:
      url: http://localhost:8080
      retries: 5

  db:
    image: postgres:16-alpine
    env:
      POSTGRES_USER: ${DB_USER:-app}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

📦 Built-in Templates

Template	Services
web-stack	Nginx + Python API + Postgres
data-stack	Postgres + Redis + Adminer
monitoring-stack	Prometheus + Grafana + Node Exporter

🧪 Running Tests

source .venv/bin/activate
pytest tests/ -v

tests/test_manifest.py::test_interpolate_simple               PASSED
tests/test_manifest.py::test_interpolate_default              PASSED
tests/test_manifest.py::test_interpolate_override_default     PASSED
tests/test_manifest.py::test_interpolate_missing_required     PASSED
tests/test_manifest.py::test_interpolate_dict_recursive       PASSED
tests/test_manifest.py::test_validate_manifest_ok             PASSED
tests/test_manifest.py::test_validate_manifest_missing_name   PASSED
tests/test_manifest.py::test_validate_manifest_missing_image  PASSED
tests/test_manifest.py::test_topo_sort_respects_depends_on    PASSED

9 passed

🛠️ Tech Stack

Layer	Tool
CLI	Click
Terminal UI	Rich
Container management	Docker SDK for Python
Config	YAML + dotenv
Health checking	HTTP polling (requests)

---

Part of @hugpaim DevOps portfolio