{"id":25493750,"url":"https://github.com/jannishuebl/orchparty","last_synced_at":"2025-04-10T01:11:19.199Z","repository":{"id":23087627,"uuid":"98097571","full_name":"jannishuebl/orchparty","owner":"jannishuebl","description":"Write your own orchestration config with a Ruby DSL that allows you to have mixins, imports and variables.","archived":false,"fork":false,"pushed_at":"2022-04-04T10:24:37.000Z","size":117,"stargazers_count":37,"open_issues_count":4,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-10T01:11:10.756Z","etag":null,"topics":["docker","docker-compose","dsl","mixins","orchestration","orchestration-framework","orchparty","ruby"],"latest_commit_sha":null,"homepage":"https://github.com/jannishuebl/orchparty","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jannishuebl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-23T12:51:00.000Z","updated_at":"2024-01-24T13:19:18.000Z","dependencies_parsed_at":"2022-08-07T10:16:42.924Z","dependency_job_id":null,"html_url":"https://github.com/jannishuebl/orchparty","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannishuebl%2Forchparty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannishuebl%2Forchparty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannishuebl%2Forchparty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannishuebl%2Forchparty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jannishuebl","download_url":"https://codeload.github.com/jannishuebl/orchparty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137886,"owners_count":21053775,"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":["docker","docker-compose","dsl","mixins","orchestration","orchestration-framework","orchparty","ruby"],"created_at":"2025-02-18T23:17:16.362Z","updated_at":"2025-04-10T01:11:19.177Z","avatar_url":"https://github.com/jannishuebl.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Orchparty\n\n[![Build Status](https://travis-ci.org/jannishuebl/orchparty.svg?branch=master)](https://travis-ci.org/jannishuebl/orchparty)\n[![Gem Version](https://badge.fury.io/rb/orchparty.svg)](https://badge.fury.io/rb/orchparty)\n[![Code Climate](https://codeclimate.com/github/jannishuebl/orchparty/badges/gpa.svg)](https://codeclimate.com/github/jannishuebl/orchparty)\n[![Test Coverage](https://codeclimate.com/github/jannishuebl/orchparty/badges/coverage.svg)](https://codeclimate.com/github/jannishuebl/orchparty/coverage)\n\nWrite your own orchestration config with a Ruby DSL that allows you to have mixins, imports and variables.\n\n```ruby\nimport \"../logging.rb\"\n\napplication 'my-cool-app' do\n  variables do\n    var port: 8080\n  end\n\n  service \"api\" do\n    mix \"logging.syslog\"\n    image \"my-cool-image:latest\"\n    commad -\u003e { \"bundle exec rails s -b 0.0.0.0 -p #{port}\" }\n  end\n\nend\n```\n\n## Why the hell?\n\n### 1. Powerfull Ruby DSL as a YAML replacement\n\nYAML is great for configuration, it has a clean syntax that is\nreadable for humans as well as machines. In addition it suites for the most of the\nconfigurations. Furthermore YAML supports features like referencing,\ninheritence and multiline Strings. \n\nIn our company we have a microservice architecture with multiple applications,\nwhich is consisting of multiple services (container types).\nAfter a while we have realized that our orchestration configuration were growing continuously and got\nhell complex, which determine global changes like replacing our logging\ninfrastucture. This changes were quite painfull, because we need to touch every single service.\n\nSome main features for us:\n\n  1. Mixin support\n  1. Import from different files\n  1. Using variables in imported configs e.g. Stack/Service names\n\n\nSome of the features are already included in YAML, unfortunately we are not able to use it, because of there complexity.\n\n\n### 2. Use Ruby instead of Templating engines\n\nMost of the orchestration frameworks are using a derivative of docker-compose.yml.\nBut most of the users realized that yml is not enough for complex\norchestration.\n\nSo most of the framework teams started to allow templating engines in the\ndocker-compose configuration.\n\nBut why keep going with a data serialization language when we want to program\nour own configuration?\n\n### 3. Have one config for multiple orchestration frameworks\n\nHow much effort is it to get a application running on an\norchestration frameworks? Actually we are glad about finding a prebuild docker-compose file\nwhich can be modified by us e.g. for kontena.io, but after modifying for kontena.io we\nhave to redo nearly all the work for rancher, kubernets etc.\n\nIt would be really nice, if people starting to write an opensource application config using\norchparty and we just simply compile the config for all popular orchestration frameworks.\n\n## Installation\n\n### Run via docker\n\n**Currently only relativ path are supported when running via docker.**\n\nAdd to bashrc:\n\n```bash\n  alias orchparty=\"docker run --rm -v /:/rootfs -e ROOT_PWD=$PWD jannishuebl/orchparty:latest\"\n```\n\nAs tag you can use semantic versioning eg X.X.X or X.X or X.\n\nIf you use latest update by running:\n\n    $ docker pull jannishuebl/orchparty:latest\n\n### Install from rubygems.org\n\nSetup a Ruby Enviroment with Ruby 2.2 or higher is necessary for the intallation.\n\n    $ gem install orchparty\n\nUpdate:\n\n    $ gem update orchparty\n\n## Usage\n\n### CLI\n\nSee the commandline usage instrucution by running:\n\n    $ orchparty help\n    \n For generating eg. use:\n\n    \n    $ orchparty generate docker_compose_v2 -f stack.rb -o docker-compose.yml -a my-cool-app\n\n### In your own piece of code\n\n```ruby\nrequire 'orchparty'\n\n# load the generator plugin you want to use\nOrchparty.plugin :docker_compose_v1\n\nOrchparty.generate(:docker_compose_v1,\n                     # all options that are needed for orchparty to transform\n                     # your input to a plain hash for generating\n                    {filename: \"path/to/input_file.rb\",\n                     application: \"application_name_to_generate\" },\n                     # all options that are needed for the plugin\n                    {output: \"path/to/output_file.yml\"})\n```\n\n## DSL spec\n\nSo let us start an example! Let us implement a configuration for a beautiful app called [app_perf](https://github.com/randy-girard/app_perf) with orchparty. This App is an opensource replacement for [New Relic](https://newrelic.com/)!\n\n### Applications\n\napp_perf needs the following components:\n- postgres for data storage \n- redis as queuing system\n- web handler as receiver for all metrics \n- worker for processing the metrics and inserting them to the postgres db.\n\n```ruby\napplication \"app_perf\" do\n\n  service \"web\" do\n    image \"blasterpal/app_perf\"\n    command \"bundle exec rails s -p 5000\"\n    expose 5000\n    links do \n      link \"redis\"\n      link \"postgres\"\n    end\n  end\n\n  service \"worker\" do\n    image \"blasterpal/app_perf\"\n    command \"bundle exec sidekiq\"\n    links do \n      link \"redis\"\n      link \"postgres\"\n    end\n  end\n\n  service \"redis\" do\n    image \"redis\"\n  end\n\n  service \"postgres\" do\n    image \"postgres\"\n  end\n\nend\n```\n\n\n### Applevel Mixins\n\nFor using external services like RDS from AWS we do not want to ship postgres in a production setup.\n\n```ruby\nmixin \"app_perf\" do\n\n  service \"web\" do\n    image \"blasterpal/app_perf\"\n    command \"bundle exec rails s -p 5000\"\n    expose 5000\n    links do \n      link \"redis\"\n    end\n  end\n\n  service \"worker\" do\n    image \"blasterpal/app_perf\"\n    command \"bundle exec sidekiq\"\n    links do \n      link \"redis\"\n    end\n  end\n\n  service \"redis\" do\n    image \"redis\"\n  end\n\nend\n\napplication 'app_perf-dev' do\n  mix \"app_perf\"\n\n  service \"web\" do\n    links do \n      link \"postgres\"\n    end\n  end\n\n  service \"worker\" do\n    links do \n      link \"postgres\"\n    end\n  end\n\n  service \"postgres\" do\n    image \"postgres\"\n  end\n\nend\n\napplication 'app_perf-prod' do\n  mix \"app_perf\"\n\n  service \"web\" do\n    environment do\n      env POSTGRES_HOST: \"rds-domain.amazon.com\"\n    end\n  end\n\n  service \"worker\" do\n    environment do\n      env POSTGRES_HOST: \"rds-domain.amazon.com\"\n    end\n  end\n\nend\n```\n\n### Service level Mixin\n\nBut we might also mixin a logging config in production.\n\n```ruby\nmixin \"logging\" do\n\n  service \"syslog\" do\n    logging do \n      conf driver: \"syslog\"\n      options do\n        opt syslog-address: \"tcp://192.168.0.42:123\"\n      end\n    end\n  end\n\nend\n\n\napplication 'app_perf-prod' do\n  mix \"app_perf\"\n\n  service \"web\" do\n    mix \"logging.syslog\"\n    environment do\n      env POSTGRES_HOST: \"rds-domain.amazon.com\"\n    end\n  end\n\n  service \"worker\" do\n    mix \"logging.fluentd\"\n    environment do\n      env POSTGRES_HOST: \"rds-domain.amazon.com\"\n    end\n  end\n\nend\n```\n\n### Commonblock\n\nUsing the all-block for adding configs to all services in one application. Of course the mix \"logging.syslog\" and environment variables will also added to the redis and postgres service.\n\n```ruby\napplication 'app_perf-prod' do\n  mix \"app_perf\"\n\n  all do\n    mix \"logging.syslog\"\n    environment do\n      env POSTGRES_HOST: \"rds-domain.amazon.com\"\n    end\n  end\n\n  service \"web\" do\n  end\n\n  service \"worker\" do\n  end\n\nend\n```\n\n### Variables\n\nYou want to use variables right? Because \"DRY\" ;) well you can: \n\n```ruby\napplication \"app_perf\" do\n  variables do\n    var image: \"blasterpal/app_perf\"\n  end\n\n  service \"web\" do\n    variables do\n      # service local variables\n    end\n    image -\u003e { image }\n    command -\u003e { \"bundle exec rails s -p #{ service.expose }\" }\n    expose 5000\n    links do \n      link \"redis\"\n      link \"postgres\"\n    end\n  end\n\n  service \"worker\" do\n    image -\u003e { image }\n    command \"bundle exec sidekiq\"\n    links do \n      link \"redis\"\n      link \"postgres\"\n    end\n  end\n\n  service \"redis\" do\n    image \"redis\"\n  end\n\n  service \"postgres\" do\n    image \"postgres\"\n  end\n\nend\n```\n\nspecial variables:\n\n  1. service:\n    - service.name\n  1. application:\n    - application.name\n\n### Import\n\nAbove we assumed that everything is written in one file. If you do not want to, just use the import feature.\n\n```ruby\nimport \"../logging.rb\"\nimport \"./app_perf.rb\"\n\napplication 'app_perf-prod' do\n  mix \"app_perf\"\n\n  all do\n    mix \"logging.syslog\"\n    environment do\n      env POSTGRES_HOST: \"rds-domain.amazon.com\"\n    end\n  end\n\nend\n```\n\n## Plugins\n\nOrchparty allows you to write own generators via a Plugin system. Also the\nbuildin generators like docker_compose_v1 and docker_compose_v2 generators are\nonly plugins. \n\nTo build your own plugin create a ruby gem with a Plugin\nconfiguration under lib/orchparty/plugin/#{plugin_name}.rb\n\n### Available plugins\n\n1. [orchparty-rancher](https://github.com/pschrammel/orchparty-rancher)\n2. [orchparty-env](https://github.com/jannishuebl/orchparty-env)\n\n### Example Plugin:\n```ruby\n\nmodule Orchparty\n  module Plugin\n    class DockerComposeV1\n\n      def self.desc\n        # this description is shown in the cli\n        \"generate docker-compose v1 file\"\n      end\n\n      def self.define_flags(c)\n        # give add all flags that your Generator needs\n        # see [davetron5000/gli](https://github.com/davetron5000/gli) for\n        # documentatino of flags\n        c.flag [:output,:o], required: true, :desc =\u003e 'Set the output file'\n      end\n\n      def self.generate(application, options)\n        # Orchparty will pass the compiled application hash and all options\n        # that you required in define_flags.\n        # Here is the place where you can write your generation logic\n        File.write(options[:output], output(application))\n      end\n\n      private\n      def self.output(ast)\n        ast.services.map do |name, service|\n          service = service.to_h\n          service.delete(:mix)\n          [service.delete(:name), HashUtils.deep_stringify_keys(service.to_h)]\n        end.to_h.to_yaml\n      end\n\n    end\n  end\nend\n\n# register your plugin\nOrchparty::Plugin.register_plugin(:docker_compose_v1, Orchparty::Plugin::DockerComposeV1)\n```\n\n### Plugin Usage:\n\n#### CLI\nThe CLI tries to load all plugins that you have installed as gem by using\nGem::Specification.\n\n\n#### Code\n\nIf you use orchparty as part of a own application load a plugin via:\n\n```ruby\nOrchparty.plugin(:docker_compose_v1)\n```\n\n## Development\n\nAfter checking out the repo:\n1. run `bin/setup` to install dependencies\n2. run `rake spec` to run the tests\nYou can also run `bin/console` for an interactive prompt that will allow you to make some experiments.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\nTo release a new version:\n1. update the version number in `version.rb`\n2. run `bundle exec rake release` which will create a git tag for the version\n3. push git commits and tags and additionally push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/jannishuebl/orchparty.\nThis project is intended to be a safe, welcoming space for collaboration,\nand contributors are expected to adhere to the\n[Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n\n## License\n\nThe gem is available as opensource project under the terms of the [GNU Lesser General Public License v3.0](http://www.gnu.de/documents/lgpl-3.0.en.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjannishuebl%2Forchparty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjannishuebl%2Forchparty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjannishuebl%2Forchparty/lists"}