{"id":13415929,"url":"https://github.com/ashmckenzie/percheron","last_synced_at":"2025-03-14T23:31:12.017Z","repository":{"id":27664840,"uuid":"31150661","full_name":"ashmckenzie/percheron","owner":"ashmckenzie","description":"Organise your Docker containers with muscle and intelligence","archived":true,"fork":false,"pushed_at":"2018-04-11T00:00:24.000Z","size":723,"stargazers_count":157,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-23T21:34:25.263Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashmckenzie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-22T03:12:02.000Z","updated_at":"2024-01-13T23:53:24.000Z","dependencies_parsed_at":"2022-08-31T20:00:46.794Z","dependency_job_id":null,"html_url":"https://github.com/ashmckenzie/percheron","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmckenzie%2Fpercheron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmckenzie%2Fpercheron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmckenzie%2Fpercheron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmckenzie%2Fpercheron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashmckenzie","download_url":"https://codeload.github.com/ashmckenzie/percheron/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.093Z","updated_at":"2025-03-14T23:31:11.298Z","avatar_url":"https://github.com/ashmckenzie.png","language":"Ruby","funding_links":[],"categories":["Container Operations"],"sub_categories":["Container Composition"],"readme":"# Percheron\n\n[![Gem Version](https://badge.fury.io/rb/percheron.svg)](http://badge.fury.io/rb/percheron)\n[![Build Status](https://travis-ci.org/ashmckenzie/percheron.svg?branch=master)](https://travis-ci.org/ashmckenzie/percheron)\n[![Code Climate GPA](https://codeclimate.com/github/ashmckenzie/percheron/badges/gpa.svg)](https://codeclimate.com/github/ashmckenzie/percheron)\n[![Test Coverage](https://codeclimate.com/github/ashmckenzie/percheron/badges/coverage.svg)](https://codeclimate.com/github/ashmckenzie/percheron)\n[![Dependency Status](https://gemnasium.com/ashmckenzie/percheron.svg)](https://gemnasium.com/ashmckenzie/percheron)\n\n![Percheron logo](./percheron-logo.png)\n\n### Organise your Docker containers with muscle and intelligence.\n\n## Why?\n\nPercheron aims to address the following challenges when working with Docker images and containers:\n\n* Managing multiple containers and mutiple sets (stacks) of containers\n* Building images and containers with support for dependencies\n* Versioning of images and containers\n\nPercheron is like Vagrant but instead of managing VM's, it manages Docker images and containers.\nIt is a very handy tool when you wish to create a basic or complex stack without the need to run\nmultiple VMs.\n\nIt is intended to be used in a test, development or prototyping scenario.\n\n## Features\n\n* Single, easy to write `.percheron.yml` describes your stack(s)\n* Build, create and start units and their dependencies\n* Build units using a Dockerfile or by pulling Docker images from Docker Hub\n* Build 'bare/base' images and build new images on top of them\n* Support for pre-build and post-start scripts when generating images and starting units\n* Version control of images and units\n* Partial template (liquid) support within `.percheron.yml`\n* Generate Graphviz dependency graphs dynamically based purely on your `.percheron.yml`\n* Support for userdata key/value pairs\n* Support for secrets in YML format\n* Written in Ruby :)\n\n## Supported platforms\n\n* Linux\n* MacOS 10.9+\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'percheron'\n```\n\nAnd then execute:\n\n```shell\n$ bundle install\n```\n\nOr install it yourself as:\n\n```shell\n$ gem install percheron\n```\n\n## Requirements\n\n* Ruby 2.x\n* [Docker 1.6.x](https://docs.docker.com/installation/) / [Boot2Docker v1.6.x+](https://docs.docker.com/installation)\n* [Docker client](https://docs.docker.com/installation) (nice to have)\n\n## Usage\n\n```\nUsage:\n    percheron [OPTIONS] SUBCOMMAND [ARG] ...\n\nParameters:\n    SUBCOMMAND                    subcommand\n    [ARG] ...                     subcommand arguments\n\nSubcommands:\n    list, status                  List stacks and its units\n    start                         Start a stack\n    stop                          Stop a stack\n    restart                       Restart a stack\n    build, rebuild                (Re)build image(s) for a stack\n    create, recreate              (Re)build image(s) and (re)create units for a stack\n    purge                         Purge a stack\n    shell                         Shell into a unit\n    logs                          Show logs for a unit\n    graph                         Generate a stack graph\n\nOptions:\n    -h, --help                    print help\n    -c, --config_file CONFIG      Config file (default: \".percheron.yml\")\n    --version                     show versionn\n```\n\n## Demo (using boot2docker)\n\n1) Get boot2docker up and running\n\nFollow the directions at https://docs.docker.com/installation\n\n```bash\nboot2docker up \u0026\u0026 eval $(boot2docker shellinit) \u0026\u0026 export BOOT2DOCKER_IP=$(boot2docker ip)\n```\n\n2) Install percheron\n\n```bash\ngem install percheron\n```\n\n3) Create a `.percheron.yml` file describing the stack, in this case [consul](https://consul.io/):\n\n```yaml\n---\nstacks:\n  - name: consul-stack\n    description: A demo consul stack with one master and two agents\n    units:\n      - name: master\n        version: 1.0.0\n        docker_image: gliderlabs/consul-server:0.5\n        start_args: [ \"-bootstrap\", \"-client\", \"0.0.0.0\", \"-data-dir\", \"/data\", \"-ui-dir\", \"/ui\" ]\n        ports:\n          - \"8500:8500\"\n          - \"8600:53/udp\"\n      - name: agent\n        version: 1.0.0\n        instances: 2\n        docker_image: gliderlabs/consul-agent:0.5\n        start_args: [ \"-join\", \"master\" ]\n        needed_unit_names:\n          - master\n```\n\n4) Start it up!\n\n```bash\npercheron start consul-stack\n\nI, [2015-08-06T22:36:46.536424 #45026]  INFO -- : Creating 'consul-stack:master' unit\nI, [2015-08-06T22:36:46.851682 #45026]  INFO -- : Starting 'consul-stack:master' unit\nI, [2015-08-06T22:36:47.861800 #45026]  INFO -- : Creating 'consul-stack:agent1' unit\nI, [2015-08-06T22:36:48.221852 #45026]  INFO -- : Starting 'consul-stack:agent1' unit\nI, [2015-08-06T22:36:48.929909 #45026]  INFO -- : Creating 'consul-stack:agent2' unit\nI, [2015-08-06T22:36:49.378310 #45026]  INFO -- : Starting 'consul-stack:agent2' unit\n```\n\n5) Show the status\n\n```bash\npercheron status consul-stack\n\n+--------+--------------+----------+------------+------------------------+---------+---------+\n|                                        consul-stack                                        |\n+--------+--------------+----------+------------+------------------------+---------+---------+\n| Unit   | ID           | Running? | IP         | Ports                  | Volumes | Version |\n+--------+--------------+----------+------------+------------------------+---------+---------+\n| master | 0acd1e2cfbc0 | yes      | 172.17.0.1 | 8500:8500, 8600:53/udp |         | 1.0.0   |\n| agent1 | d70495c1c62b | yes      | 172.17.0.2 |                        |         | 1.0.0   |\n| agent2 | 458ad3ba0890 | yes      | 172.17.0.3 |                        |         | 1.0.0   |\n+--------+--------------+----------+------------+------------------------+---------+---------+\n```\n\n6) Ensure consul is running\n\n```bash\ncurl http://${BOOT2DOCKER_IP}:8500/v1/catalog/nodes\n\n[{\"Node\":\"agent1\",\"Address\":\"172.17.0.5\"},{\"Node\":\"agent2\",\"Address\":\"172.17.0.6\"},{\"Node\":\"master\",\"Address\":\"172.17.0.4\"}]\n```\n\n7) Perform some DNS lookups using consul\n\n```bash\ndig @${BOOT2DOCKER_IP} -p 8600 master.node.consul agent1.node.consul agent2.node.consul +short\n\n172.17.0.7\n172.17.0.8\n172.17.0.9\n```\n\n8) Bring up the consul UI\n\n```bash\nopen http://${BOOT2DOCKER_IP}:8500/ui\n```\n\n9) Purge it!\n\n```bash\npercheron purge consul-stack\n\nI, [2015-05-21T19:28:23.925205 #35710]  INFO -- : Stopping 'agent2' unit\nI, [2015-05-21T19:28:24.269218 #35710]  INFO -- : Deleting 'agent2' unit\nI, [2015-05-21T19:28:24.452320 #35710]  INFO -- : Stopping 'agent1' unit\nI, [2015-05-21T19:28:24.811764 #35710]  INFO -- : Deleting 'agent1' unit\nI, [2015-05-21T19:28:24.965680 #35710]  INFO -- : Stopping 'master' unit\nI, [2015-05-21T19:28:25.246578 #35710]  INFO -- : Deleting 'master' unit\n```\n\n## Dependency graph\n\nNote: Requires [Graphviz](http://graphviz.org/) installed.\n\n```bash\npercheron graph consul-stack\n```\n\n![consul-stack](https://raw.githubusercontent.com/ashmckenzie/percheron-consul/master/assets/stack.png)\n\n## Debugging\n\nTo perform debugging you will need to install the `pry-byebug` gem:\n\n```bash\ngem install pry-byebug\n```\n\nTo debug Percheron, set the `DEBUG=true` environment variable.\n\nTo debug Percheron and Docker, set the `DOCKER_DEBUG=true` environment variable.\n\n## Examples\n\n* [consul](https://github.com/ashmckenzie/percheron-consul) - consul server + UI and two agents\n* [Rails](https://github.com/ashmckenzie/percheron-rails#quickstart) - Rails 4.2, PostgreSQL, redis, HAProxy and postfix\n* [Redis](https://github.com/ashmckenzie/percheron-redis#quickstart) - Redis cluster + sentinel, master, two slaves and tools\n* [Torrent](https://github.com/ashmckenzie/percheron-torrent#quickstart) - Tracker (chihaya), seeder (aria2) and three peers (aria2)\n* [SaltStack](https://github.com/ashmckenzie/percheron-saltstack#quickstart) - SaltStack with master and two minions\n\n## Testing\n\nAll (cane, RuboCop, unit and integration):\n\n```shell\nbundle exec rake test\n```\n\nStyle (cane and RuboCop):\n\n```shell\nbundle exec rake test:style\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/ashmckenzie/percheron/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Run `bundle exec rake test`\n5. Push to the branch (`git push origin my-new-feature`)\n6. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashmckenzie%2Fpercheron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashmckenzie%2Fpercheron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashmckenzie%2Fpercheron/lists"}