178 lines
No EOL
4.4 KiB
Markdown
178 lines
No EOL
4.4 KiB
Markdown
# Maestro
|
|
|
|
[](https://www.docker.com/)
|
|
[](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. |