# Maestro

[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![Python](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)

Maestro is an elegant and lightweight solution for Docker container orchestration that simplifies the complex symphony of container deployments. Like a conductor leading an orchestra, Maestro harmoniously manages your Docker containers with precision and grace.ent.

## Features

- Automated container management and orchestration
- Boot-time container recomposition
- On-demand container reconstruction
- Interactive container management interface
- Selective container exclusion
- Compatible with any Docker environment

## Prerequisites

- Python 3.6 or higher
- Docker Engine
- Docker Compose
- Appropriate Docker permissions for the executing user

## Installation

1. Clone the repository:
```bash
git clone https://git.hhf.technology/hhf/maestro.git
cd maestro
```

2. Configure your environment by editing `docker-composer.conf` (see Configuration section below)

3. Ensure scripts have executable permissions:
```bash
chmod +x *.py
```

## Configuration

### docker-composer.conf

The `docker-composer.conf` file contains essential configuration parameters:

| Parameter | Description | Example |
|-----------|-------------|---------|
| `compose-path` | Directory containing Docker container folders | `/opt/docker/containers` |
| `exclude-containers` | List of containers to exclude from management | `["container1", "container2"]` |

Example configuration:
```yaml
compose-path: /opt/docker/containers
exclude-containers:
  - monitoring
  - internal-proxy
```

### Directory Structure

Your container directory structure should follow this format:
```
compose-path/
├── container1/
│   └── docker-compose.yml
├── container2/
│   └── docker-compose.yml
└── container3/
    └── docker-compose.yml
```

## Usage

### Available Scripts

| Script | Description | Use Case |
|--------|-------------|----------|
| `composer.py` | Main orchestration script | Automated container management on system boot |
| `re_compose.py` | Manual reconstruction tool | On-demand container rebuild and reconfiguration |
| `basic-management.py` | Interactive management interface | Basic container operations (start, stop, remove) |

### Running the Scripts

All scripts must be executed from the same directory as `docker-composer.conf`.

1. **Automated Boot Management**
```bash
./composer.py
```

2. **Manual Container Reconstruction**
```bash
./re_compose.py
```

3. **Interactive Container Management**
```bash
./basic_management.py
```

### Adding to System Startup

To enable automatic container management on system boot:

#### Using systemd

1. Create a service file:
```bash
sudo nano /etc/systemd/system/docker-composer.service
```

2. Add the following content:
```ini
[Unit]
Description=Maestro Docker Container Orchestration
After=docker.service
Requires=docker.service

[Service]
Type=simple
ExecStart=/path/to/composer.py
WorkingDirectory=/path/to/maestro
User=your-user
Group=docker

[Install]
WantedBy=multi-user.target
```

3. Enable and start the service:
```bash
sudo systemctl enable docker-composer
sudo systemctl start docker-composer
```

## Security Considerations

- Ensure proper file permissions on configuration files
- Run scripts with minimal required privileges
- Regularly audit excluded containers list
- Monitor container logs for unexpected behavior

## Troubleshooting

Common issues and solutions:

1. **Permission Denied**
   - Ensure the executing user is in the docker group
   - Check file permissions on scripts and configuration

2. **Configuration Not Found**
   - Verify script execution from correct directory
   - Check `docker-composer.conf` exists and is readable

3. **Container Exclusion Issues**
   - Verify container names match exactly
   - Check for whitespace in configuration

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by Umbrel's container management approach
- Built with Python and Docker
- Community contributions and feedback

---

For bug reports and feature requests, please use the [Forum Comments](https://forum.hhf.technology/t/maestro-docker-container-orchestration-made-simple) page.