{"id":21888685,"url":"https://github.com/swisscom/dopi","last_synced_at":"2025-07-21T10:31:16.849Z","repository":{"id":18691800,"uuid":"85068018","full_name":"swisscom/dopi","owner":"swisscom","description":"Deployment Orchestrator for Puppet - inner Orchestrator","archived":false,"fork":false,"pushed_at":"2023-04-07T12:02:03.000Z","size":471,"stargazers_count":8,"open_issues_count":2,"forks_count":3,"subscribers_count":23,"default_branch":"master","last_synced_at":"2023-08-04T09:23:16.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swisscom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-15T12:09:32.000Z","updated_at":"2022-04-28T11:33:13.000Z","dependencies_parsed_at":"2022-07-25T23:17:27.053Z","dependency_job_id":null,"html_url":"https://github.com/swisscom/dopi","commit_stats":null,"previous_names":[],"tags_count":49,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2Fdopi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2Fdopi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2Fdopi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swisscom%2Fdopi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swisscom","download_url":"https://codeload.github.com/swisscom/dopi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226902943,"owners_count":17700619,"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-11-28T11:16:38.486Z","updated_at":"2024-11-28T11:16:39.041Z","avatar_url":"https://github.com/swisscom.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!NOTE]\n\u003e DEPRECATED - no longer maintained!\n\n# Dopi\n\nDOPi is the \"inner\" part of the Deployment Orchestrater for Puppet (DOP).\nIt is the part that connects into your nodes and runs commands in a defined\norder.\n\nThe main purpose of DOPi is to get your nodes into a state where they can\nrun Puppet or any other config management. It will also allows you to\norchestrate this Puppet runs so you can setup your nodes in the desired order.\n\nDOPi orchestrates puppet runs, mco calls and custom commands over different nodes\n\nDOPi uses a DOP plan file to find out what it has to run in what order on\nwhich nodes. To learn more about the syntax of this DOP plan file make sure\nyou checkout the Documentation in [dop_common](https://github.com/swisscom/dop_common).\n\nIf you are new to DOPi make sure you check out the [getting started guide](doc/getting_started.md).\n\n## Change Log\n\nDopi is currently under heavy development and should not be considered stable. If you are\nupgrading make sure you carefully ready the [Change Log](CHANGELOG.md)\n\n## DOPi as a library\n\n### Install \n\nAdd this line to your application's Gemfile:\n\n    gem 'dopi'\n\nAnd then execute:\n\n    $ bundle\n\n### Usage Example\n\n    require 'dopi'\n\n    Dopi.configure do |config|\n      config.role_variable = 'my_role'\n      config.role_default  = 'base'\n    end\n\n    plan_parser = DopCommon::Plan.new(YAML.load_file(plan_file))\n    plan = Dopi::Plan.new(plan_parser)\n    plan.run\n\n    puts \"Plan status: #{plan.state.to_s}\"\n    plan.steps.each do |step|\n      puts \"[#{step.state.to_s}] #{step.name}\"\n      step.commands.each do |command|\n        puts \"  [#{command.state.to_s}] #{command.node.fqdn}\"\n      end\n    end\n\n#### With DOP plan cache\n\nThis will persist the plan in the DOP plan cache.\n\n    require 'dopi'\n\n    Dopi.configure do |config|\n      config.role_variable = 'my_role'\n      config.role_default  = 'base'\n    end\n\n    plan = Dopi.add_plan(plan_file)\n    Dopi.run_plan(plan)\n\n    puts \"Plan status: #{plan.state.to_s}\"\n    plan.steps.each do |step|\n      puts \"[#{step.state.to_s}] #{step.name}\"\n      step.commands.each do |command|\n        puts \"  [#{command.state.to_s}] #{command.node.fqdn}\"\n      end\n    end\n    \n### DOPi as a CLI\n\n### Install\n\nInstall the gem\n\n    $ gem install dopi\n\nHelp on all available options\n\n    $ dopi help\n\n### Usage Example\n\nFirst you have to add a plan to the plan cache:\n\n    $ dopi add spec/data/plan/example_deploment_plan_test.yaml \n    example_deploment_plan_test \n\nThis will return the plan name which can be used to run other\ncommands on that plan. You can get a list of all the plans in the\ncache by running:\n\n    $ dopi list\n    example_deploment_plan_test\n\nYou can get information about the state of a plan with the show command\nand the name of the plan:\n\n    $ dopi show example_deploment_plan_test\n    [ready] test_run\n      [ready] mysql01.example.com\n      [ready] web01.example.com\n      [ready] web02.example.com\n      [ready] haproxy01.example.com\n      [ready] haproxy02.example.com\n    [ready] Make sure we can login to all nodes\n      [ready] mysql01.example.com\n      [ready] web01.example.com\n      [ready] web02.example.com\n      [ready] haproxy01.example.com\n      [ready] haproxy02.example.com\n    [ready] ssh_test_run\n      [ready] mysql01.example.com\n    [ready] run_puppet\n      [ready] mysql01.example.com\n      [ready] web01.example.com\n      [ready] web02.example.com\n      [ready] haproxy01.example.com\n      [ready] haproxy02.example.com\n    [ready] run_puppet2\n      [ready] mysql01.example.com\n      [ready] web01.example.com\n      [ready] web02.example.com\n      [ready] haproxy01.example.com\n      [ready] haproxy02.example.com\n\nYou can run the plan with the run command and the name:\n\n    $ dopi run example_deploment_plan_test\n\n\n## Plan File Format\n\nFor a general description of the DOP plan file format, please see the\n[dop_common](https://github.com/swisscom/dop_common/blob/master/README.md)\ndocumentation. The documentation in this gem will focus on the command hashes for all\nthe basic plugins which are shipped with DOPi and on how to create your own custom plugins.\n\n### How to use Plugins\n\nDOPi uses plugins to run commands on the nodes. Each step in the plan has one\ncommand and as many verify_commands as needed. DOPi will run all the verify_commands\nbefore the command and will run the command only if one of them fails.\n\nIn general a plugin is specified like this:\n\n```YAML\n    - name \"My new Step\"\n      nodes: 'all'\n      command:\n        plugin: 'my_plugin_name'\n        parameter1: 'foo'\n        parameter2: 'bar'\n```\n\nSome of the Plugins don't actually need parameters, so they can be called with the short form:\n\n```YAML\n    - name \"My new Step\"\n      nodes: 'all'\n      command: 'my_simple_plugin'\n```\n\n### Verify Commands\n\nIt is usually a good idea to check if a step is required to run. This way you can make your\nplans idempotent. You can define any number of verify commands. If they all are successful\nDOPi will skip the run. There are a hand full of plugins who are written exactly for this\npurpose.\n\n```YAML\n    - name \"Create file if it does not exist\"\n      command:\n        verify_commands:\n          - plugin; 'ssh/file_exists'\n            file: '/tmp/somefile'\n        plugin: 'ssh/custom'\n        exec: 'echo'\n        arguments: \"'Hello World' \u003e /tmp/somefile\"\n```\n\n### Generic Plugin Parameters\n\nThere are some generic parameters every plugin supports:\n\n#### plugin_timeout (optional)\n\n`default: 300`\n\nThe time in seconds after which DOPi will kill the thread and mark the step as failed.\n\n#### verify_after_run (optional)\n\n`default: false`\n\nThe verify commands will be executed again after the command run and the step will\nonly succeed if the verify commands all successful.\n\n### Command Execution Plugins\n\nThis are the plugins generally used in steps as commands\n\n[custom](doc/plugins/custom.md)\n\n[ssh/custom](doc/plugins/ssh/custom.md)\n\n[ssh/wait_for_login](doc/plugins/ssh/wait_for_login.md)\n\n[ssh/reboot](doc/plugins/ssh/reboot.md)\n\n[ssh/puppet_agent_run](doc/plugins/ssh/puppet_agent_run.md)\n\n[ssh/file_replace](doc/plugins/ssh/file_replace.md)\n\n[ssh/file_deploy](doc/plugins/ssh/file_deploy.md)\n\n[mco/rpc](doc/plugins/mco/rpc.md)\n\n[winrm/cmd](doc/plugins/winrm/cmd.md)\n\n[winrm/powershell](doc/plugins/winrm/powershell.md)\n\n[winrm/wait_for_login](doc/plugins/winrm/wait_for_login.md)\n\n[winrm/reboot](doc/plugins/winrm/reboot.md)\n\n[winrm/puppet_agent_run](doc/plugins/winrm/puppet_agent_run.md)\n\n### Verification Plugins\n\nThis are some helper plugins that check stuff on the nodes. They are\nusefull for verify_commands. However, every normal plugin can be used\nas a verify_command and vice versa.\n\n[ssh/file_contains](doc/plugins/ssh/file_contains.md)\n\n[ssh/file_exists](doc/plugins/ssh/file_exists.md)\n\n[winrm/file_contains](doc/plugins/winrm/file_contains.md)\n\n[winrm/file_exists](doc/plugins/winrm/file_exists.md)\n\n## Example Plans\n\nThere are some examples for DOPi in the sources which are also used for tests\n\n[DOPi test environment setup](spec/integration/dopi/build_dop_test_environment.yaml)\n\nMore can be found in the plans directory.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n### Run the test suit\n\nMost of the tests depend on Vagrant to create an actual test environment where the DOPi\nplugins can be tested under real conditions.\n\nTo setup the test suit you need a working vagrant (https://www.vagrantup.com/) installation\nwith the dop_common gem added as a plugin:\n\n    cd /tmp\n    git clone https://github.com/swisscom/dop_common.git\n    cd dop_common\n    gem build dop_common.gemspec\n    vagrant plugin install ./dop_common-*.gem\n\nAfter you install the plugin you have to setup the test machines with the rake task:\n\n    cd /path/to/dopi/\n    bundle install --path .bundle\n    bundle exec rake spec:prep\n\nYou should always rerun 'spec:prep' to make sure your test environment is started\nand setup correctly.\n\nThe tests will connect to the machines and for now you require some hosts file entries\nto work correctly. Add the following lines to your /etc/hosts:\n\n    # Host entries for DOPi test environment\n    192.168.56.101 puppetmaster.example.com\n    192.168.56.102 broker.example.com\n    192.168.56.103 linux01.example.com\n    192.168.56.104 linux02.example.com\n    192.168.56.105 linux03.example.com\n    192.168.56.106 windows01.example.com\n\nNow you are ready to run the test suit:\n\n    bundle exec rake\n\nIf you reboot your machine or stop the test machines you can make sure the test\nenvironment is ready and built by simply running the setup again:\n\n    bundle exec rake testenv:setup\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswisscom%2Fdopi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswisscom%2Fdopi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswisscom%2Fdopi/lists"}