maestro/README.md

Maestro

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:

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:

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:

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

./composer.py

2. Manual Container Reconstruction

./re_compose.py

3. Interactive Container Management

./basic_management.py

Adding to System Startup

To enable automatic container management on system boot:

Using systemd

1. Create a service file:

sudo nano /etc/systemd/system/docker-composer.service

2. Add the following content:

[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:

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 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 page.