{"id":13415925,"url":"https://github.com/toscanini/maestro","last_synced_at":"2025-12-18T01:59:59.171Z","repository":{"id":9678369,"uuid":"11622326","full_name":"toscanini/maestro","owner":"toscanini","description":"Container orchestration for Docker environments","archived":false,"fork":false,"pushed_at":"2013-08-21T01:47:01.000Z","size":337,"stargazers_count":617,"open_issues_count":8,"forks_count":45,"subscribers_count":35,"default_branch":"master","last_synced_at":"2024-07-31T21:54:49.486Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toscanini.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-24T00:08:08.000Z","updated_at":"2024-07-31T17:18:21.000Z","dependencies_parsed_at":"2022-09-08T12:31:00.928Z","dependency_job_id":null,"html_url":"https://github.com/toscanini/maestro","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toscanini%2Fmaestro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toscanini%2Fmaestro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toscanini%2Fmaestro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toscanini%2Fmaestro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toscanini","download_url":"https://codeload.github.com/toscanini/maestro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243663459,"owners_count":20327299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T21:00:53.058Z","updated_at":"2025-12-18T01:59:59.116Z","avatar_url":"https://github.com/toscanini.png","language":"Python","funding_links":[],"categories":["Container Operations","Python","Remote Container Manager / Orchestration","others"],"sub_categories":["Container Composition"],"readme":"Maestro\n============\n\nMaestro provides the ability to easily launch, orchestrate and manage mulitple Docker containers as single unit. Container sets are defined in a simple YAML format that allows you to define how the containers should be created and to specify relationships between containers. The intention is to make easy to create and use complex multi-node container envionments for testing and development.\n\nThis is what it currently looks like to use maestro and deploy a multi-tier node.js/mongodb application. All that's required is a maestro.yml in the root of the repository.\n\n```\n$ git clone https://github.com/kstaken/express-todo-example.git\n$ cd express-todo-example \u0026\u0026 maestro build\nBuilding template mongodb\nBuilding template nodejs\nLaunching instance of template mongodb named mongodb\nStarting container mongodb - 144af5ca089d\nStarting nodejs: waiting for service mongodb on ip 172.16.0.61 and port 27017\nFound service mongodb on ip 172.16.0.61 and port 27017\nLaunching instance of template nodejs named nodejs\nStarting container nodejs - 52be61a3242c\nLaunched.\n\n$ maestro ps\nID            NODE               COMMAND                                     STATUS     PORTS\n144af5ca089d  mongodb            /usr/bin/mongod --config /etc/mongodb.conf  Running\n52be61a3242c  nodejs             /usr/bin/node /var/www/app.js               Running    49184-\u003e80\n\n$ maestro stop\nStopping container mongodb - 144af5ca089d\nStopping container nodejs - 52be61a3242c\nStopped.\n\n$ maestro start\nStarting container mongodb - 144af5ca089d\nStarting nodejs: waiting for service mongodb on ip 172.16.0.63 and port 27017\nFound service mongodb on ip 172.16.0.63 and port 27017\nStarting container nodejs - 52be61a3242c\nStarted.\n```\n\nIn this example the app would be accessible on http://localhost:49184/.\n\nStatus\n======\n\nEarly development. It can be useful for testing and development but the feature set and configuration format are changing rapidly.\n\nNote: this project used to be called DockerMix.\n\nFeatures\n========\n\n- Build/start/stop/destroy multi-container docker environments via simple commands\n- Specify dependencies between containers so they start in order and wait for services to become available\n- Automatically configure dependent containers to know where to locate services from other containers in the same environment\n- Easily launch and manage multiple copies of the same environment\n- Declarative YAML format to specify container configurations for the environment\n- Easily launch multiple instances of the same container for testing cluster operations\n- Share data between the host machine and containers running in the environment\n- ... Much more to come\n\nDependencies\n=============\n\n- Docker: https://github.com/dotcloud/docker\n- docker-py: https://github.com/dotcloud/docker-py\n- Python pip package manager\n\nInstallation\n============\n\nInstall Docker as described here: http://www.docker.io/gettingstarted/\n\nNote: Docker 0.5.2 changed from listening on a network socket to listening on a unix socket due to a security issue. At this time, to use Maestro with Docker 0.5.2 you must re-enable the TCP socket in Docker. `/usr/bin/docker -d -H=tcp://127.0.0.1:4243` This is safe if you're running Docker inside a VM dedicated to that purpose but not if you're running Docker directly on your physical computer. This will be fixed in the future.\n\nThen:\n```\n    sudo apt-get install -y python-pip\n    git clone https://github.com/toscanini/maestro.git\n    cd maestro\n    sudo pip install -r requirements.txt \n    sudo python setup.py install\n    docker pull ubuntu\n```\n\nConfiguration File Format\n=========================\n\n**Note:** This format is changing heavily.\n\nThe configuration file defines an environment that is made up of multiple templates that can be used to generate containers. The templates can have relationships defined between them to specify start order and Maestro will handle starting instances of the templates in containers in the correct order and then providing environment configuration to the containers.\n\nThis example will setup two templates, one for nodejs and one for mongodb. The nodejs template depends on mongodb so that when you start the environment no nodejs containers will be started until a mongdb container is fully up and running.\n\nIn this instance the templates are built from repositories stored on Github but there are various ways to set these up.\n\n```\ntemplates:\n  nodejs: \n    config:\n      command: /usr/bin/node /var/www/app.js\n      ports: \n        - '80'  \n      environment:\n        - PORT=80\n    buildspec:\n      url: github.com/toscanini/docker-nodejs\n    require:\n      mongodb: \n        port: '27017'\n  mongodb:     \n    config:\n      command: /usr/bin/mongod --config /etc/mongodb.conf\n    buildspec:\n      url: github.com/toscanini/docker-mongodb\n```\n\nTo build and launch an environment you just place this config in a file named `maestro.yml` then run `maestro build`. It will take a few seconds to start as it waits for MongoDB to initialize. Currently the environment state lives in the current directory but that will have more flexibility in the future.\n\nTemplates also define a basic docker configuration so that you can pre-define the parameters used on docker run.\n\n`base_image` is the Docker container to use to run the command. It must already exist on the system and won't be pulled automatically.\n\n`base_image` and `command` are the only required options if no `buildspec` is provided. If `buildspec` is provided `base_image` can be omitted\n\n`require` is used to specify dependencies between services. The start order will be adjusted and any container that requires a port on a another container will wait for that port to become available before starting.\n\n`mount` allows you to define bind mounts between a directory on the host and a directory in a container. This allows you to share files between the host and the container. \n    Note: if you define a bind mount on a template then every instance of that template will mount the same host directory.\n\nThis example yaml file shows how some of the docker parameters look:\n\n```\n  templates:\n    test_server_1:\n      base_image: ubuntu\n      mount:\n        /host/path: /container/path\n      config:\n        ports: \n          - '8080' \n        command: '/bin/bash -c \"apt-get install netcat ; nc -l 8080 -k\"' \n        hostname: test_server_1 \n        user: root\n        detach: true\n        stdin_open: true\n        tty: true\n        mem_limit: 2560000\n        environment: \n          - ENV_VAR=testing\n        dns: \n          - 8.8.8.8\n          - 8.8.4.4\n        volumes: \n          /var/testing: {}\n```\n\n**Note:** *Command is required by the Docker Python api and having to specify it here can cause problems with images that pre-define entrypoints and commands.*\n\nCommand Line Tools\n===\n\nThe command line tool is called `maestro` and initial enironments are defined in `maestro.yml`. If there is a `maestro.yml` in the current directory it will be automatically used otherwise the `-f` option can be used to specify the location of the file.\n\nThe environment state will be saved to a file named `environment.yml` and commands that manipulate existing environments will look for an `environment.yml` in the current directory or it can be specified by the `-e` option.\n\nIf you want to create a named environment you can use `-n` to set the name and it will be made a global environment that lives either under ~/.maestro or /var/lib/maestro depending on your setup.\n\n`maestro build`\n\nSetup a new environment using a `maestro.yml` specification.\n\n`maestro start [node_name]`\n\nStart an existing environment that had been previously stopped and saved in `environment.yml`. If `node_name` is provided just that node will be stopped.\n\n`maestro stop [node_name]`\n\nStop all containers in an environment and save the state to `environment.yml` If `node_name` is provided just that node will be stopped.\n\n`maestro run template [commandline]`\n\nRun a new instance of the template in the environment. *Limited functionality on this currently*\n\n`maestro destroy`\n\nDestroy all containers defined in an environment. Once destroyed the containers can not be recoved.\n\n`maestro ps`\n\nShow the status of the containers in an environment.\n\nRoadmap\n====\n\n- Bootstrap installer\n- Add the ability to share configuration data between containers. Limited capabilities exist for this currently.\n- ~~Explicitly specify startup order and dependencies~~\n- ~~More powerful Docker Builder support~~ ~~(currently docker-py reimplements Docker Builder and it out of sync with the server implementation)~~\n- ~~Add automatic pulling of base images~~\n- Make it easier to run the full test suite\n- Add the ability to depend on external services\n- ~~Add the ability to have named global environments as well as environments stored in the local directory~~\n- More robust support for running and adding containers to an existing environment\n- Direct build and instantiation of an environment from a git repo\n- ...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoscanini%2Fmaestro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoscanini%2Fmaestro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoscanini%2Fmaestro/lists"}