{"id":13416157,"url":"https://github.com/DevTable/gantryd","last_synced_at":"2025-03-14T23:31:20.647Z","repository":{"id":11313021,"uuid":"13731956","full_name":"DevTable/gantryd","owner":"DevTable","description":"Framework for easy management of docker-based components across machines","archived":true,"fork":false,"pushed_at":"2016-08-01T16:13:12.000Z","size":124,"stargazers_count":265,"open_issues_count":7,"forks_count":28,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-07-31T21:55:19.881Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DevTable.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-10-21T03:14:02.000Z","updated_at":"2023-12-04T18:08:29.000Z","dependencies_parsed_at":"2022-09-18T05:36:03.909Z","dependency_job_id":null,"html_url":"https://github.com/DevTable/gantryd","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/DevTable%2Fgantryd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevTable%2Fgantryd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevTable%2Fgantryd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevTable%2Fgantryd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DevTable","download_url":"https://codeload.github.com/DevTable/gantryd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243663487,"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:54.835Z","updated_at":"2025-03-14T23:31:20.219Z","avatar_url":"https://github.com/DevTable.png","language":"Python","readme":"# gantryd\n\nA framework built on top of [Docker](http://docker.io) that allows for easy deployment and management of project components, with a focus on:\n\n* Easy management of components of a project across multiple machines\n* Single command updating of components with **automatic draining** and **progressive rollout**\n* Ability to manage components locally, when necessary (see **gantry** below)\n\n## Overview\n\n**gantryd** is a distributed, etcd-based system for running, updating, monitoring and managing various Docker images (known as \"components\") across\nmultiple machines.\n\n![gantryd overview](https://docs.google.com/drawings/d/1S0P8XE9H6lxUZNyQkfAXW9uYfKnXxUrzwA23oihwXlQ/pub?w=596\u0026amp;h=349)\n\n**gantryd** manages the running, monitoring and draining of containers, automatically updating machines *progressively* on update, and *draining* the old containers\nas it goes along. A container is only shutdown when *all connections* to it have terminated (or it is manually killed). This, combined with progressive\nupdate, allows for *continuous deployment* by simply pushing a new docker image to a repository and running `update` via `gantryd.py`.\n\n**gantryd** also automatically monitors the containers of a component, running checks periodically to ensure they are healthy. If a container goes bad, a new one is automatically started in its place, with traffic being moved over.\n\n## Getting Started\n\n### Getting etcd\n\nThe latest etcd release is available as a binary at [Github][github-release].\nInstallation instructions can be found at [Etcd README][etcd-readme].\n\n[github-release]: https://github.com/coreos/etcd/releases/\n[etcd-readme]: https://github.com/coreos/etcd/blob/master/README.md\n\n\n### Cloning the source\n\n```sh\ngit clone https://github.com/DevTable/gantryd.git\n```\n\n### Installing dependencies\n\n#### Debian or Ubuntu\n```sh\n# Install apt-get dependencies.\ncat requirements.system | xargs sudo apt-get install -y\n\n# Install python dependencies.\nsudo pip install -r requirements.txt\n```\n\n#### RHEL or Centos\n```sh\n# Install yum dependencies.\ncat requirements.system.rhel | xargs sudo yum install -y\n\n# Install python dependencies.\nsudo pip install -r requirements.txt\n```\n\n### Setting up\n\nAll settings for gantryd are defined in a JSON format. A project's configuration is stored in etcd but is set initially from a local file (see `setconfig` below).\n\nThe configuration defines the various components of the project you want to manage:\n```json\n{\n  \"components\": [\n    {\n       \"name\": \"someexamplecomponent\",\n       \"repo\": \"my/localrepo\",\n       \"tag\": \"latest\",\n       \"command\": [\"/usr/bin/python\", \"/somedir/myapplication.py\"],\n       \"ports\": [\n\t         {\"external\": 8888, \"container\": 8888}\n       ],\n       \"readyChecks\": [\n         { \"kind\": \"http\", \"port\": 8888 }\n       ],\n       \"healthChecks\": [\n         { \"kind\": \"http\", \"port\": 8888, \"path\": \"/some/path\" }\n       ],\n       \"volumesFrom\": [\n         \"somedatacontainer\"\n       ],\n       \"bindings\": [\n         { \"external\": \"/an/external/path\", \"volume\": \"/some/container/path\"}\n       ],\n       \"defineComponentLinks\": [\n         { \"port\": 8888, \"name\": \"mycoolserver\", \"kind\": \"tcp\" }\n       ],\n       \"requireComponentLinks\": [\n         { \"name\": \"anotherserver\", \"alias\": \"serveralias\" }\n       ],\n       \"environmentVariables\": [\n         { \"name\": \"FOO\", \"value\": \"somevalue\" }\n       ]\n    }\n  ]\n}\n```\n\n| Field                 | Description                                                                       | Default     |\n| --------------------- | --------------------------------------------------------------------------------- | ----------- |\n| name                  | The name of the component                                                         |             |\n| repo                  | The docker image to use for the component                                         |             |\n| tag                   | The tag of the docker image to use                                                | latest      |\n| user                  | The user under which to run the command in the container                          | (in image)  |\n| command               | The command to run inside the container                                           | (in image)  |\n| ports                 | Mappings of container ports to external ports                                     |             |\n| readyChecks           | The various checks to run to ensure the container is ready (see below for list)   |             |\n| healthChecks          | The various checks to run to ensure the container is healthy (see below for list) |             |\n| terminationSignals    | Signals which should be sent to a specific container when it should be shut down  |             |\n| terminationChecks     | The various checks to run to ensure that the container is ready to be shut down   | connections |\n| volumesFrom           | Container(s), by name, whose volume(s) should be mounted into the container       |             |\n| bindings              | Mapping between external hosts paths and the corresponding container volumes      |             |\n| defineComponentLinks  | Defines the component links exported by this component                            |             |\n| requireComponentLinks | Defines the component links imported/required by this component                   |             |\n| readyTimeout          | Timeout in milliseconds that we will wait for a container to pass a ready check   | 10,000      |\n| environmentVariables  | Environment variables to set when running the component's containers              |             |\n| privileged            | Whether the container should run in privileged mode                               | False       |\n\n### Terminology\n\n**Project**: Namespace that contains configuration for a set of components, as well as any metadata associated\nwhen those components are running. For example: 'frontend', 'backend', 'someproduct'.\n\n**Component**: A named component that runs a specific docker image in a container. For example: 'elasticsearch', 'mongodb'.\n\n**Component Link**: Similar to a Docker link: An exposed port by one *component* that is imported by one or more other \ncomponents. Unlike a Docker link, a component link is managed by gantry and automatically updated via the proxy just link\nnormal exposed ports. When a component link is required/imported by a container, the following environment variables are\nadded into the containers for that component:\n\n| Environment Variable              | Example Name                        | Example Value                                     |\n| --------------------------------- | ----------------------------------- | ------------------------------------------------- |\n| {ALIAS}_CLINK                     | SERVERALIAS_CLINK                   | tcp://172.17.42.1:53852                           |\n| {ALIAS}\\_CLINK\\_{PORT}\\_{KIND}       | SERVERALIAS_CLINK_8888_TCP          | tcp://172.17.42.1:53852                           |\n| {ALIAS}\\_CLINK\\_{PORT}\\_{KIND}\\_PROTO | SERVERALIAS_CLINK_8888_TCP_PROTO    | tcp                                               |\n| {ALIAS}\\_CLINK\\_{PORT}\\_{KIND}\\_ADDR  | SERVERALIAS_CLINK_8888_TCP_ADDR     | 172.17.42.1                                       |\n| {ALIAS}\\_CLINK\\_{PORT}\\_{KIND}\\_PORT  | SERVERALIAS_CLINK_8888_TCP_PORT     | 53852                                             |\n\n\n### Setting up a project\n\n- [Gantryd commands](#gantryd-commands) - distributed management\n- [Gantry commands](#gantry-commands) - local management\n\n### \u003ca name=\"gantryd\"\u003e\u003c/a\u003eGantryd commands\n\n#### Creating/updating the project's configuration\n\nTo setup a gantryd project, make sure that etcd is running, and gantry configuration is avaliable in some file.\n\nRun the following to update the configuration for project `myprojectname` in gantryd:\n```sh\nsudo ./gantryd.py setconfig myprojectname myconfigfile\n```\n\nResponse:\n```sh\nConfiguration updated\n```\n\n#### Setup components by 'updating' them\n\nTo mark one or more components as ready for deployment, execute the following from a machine with the latest images:\n```sh\nsudo ./gantryd.py update myprojectname -c firstcomponent secondcomponent\n```\n\nResponse:\n```sh\nUpdating the image IDs on components\nComponent firstcomponent -\u003e 4ae76210a4fe\nComponent secondcomponent -\u003e 0cf0c034fc89\n```\n\nThis sets the status of the components to 'ready' and associates them with the image IDs listed. Once run, any followup\n`gantryd run` commands on this machine (or any other machines in the etcd cluster) will update and start those components\nwith those images.\n\n#### Running components on machine(s)\n\nOnce components have been marked as ready, they can be run by executing `gantryd run` on one or more machines:\n\n```sh\nsudo ./gantryd.py run myprojectname -c firstcomponent secondcomponent\n```\n\nThis command will start a daemon (and block), starting the components and monitoring them, until it is shutdown.\n\n#### Updating a component across all listening machines\n\nTo tell components to update themselves in response to an image change, execute:\n\n```sh\nsudo ./gantryd.py update myprojectname -c firstcomponent secondcomponent\n```\n\nResponse:\n```sh\nUpdating the image IDs on components\nComponent firstcomponent -\u003e 4ae76210a4fe\nComponent secondcomponent -\u003e 0cf0c034fc89\n```\n\nThe first machine running the gantryd daemon will start the update within 30 seconds.\n\n### Listing the status of all components\n```sh\nsudo ./gantryd.py list myprojectname\n```\n\nResponse:\n```sh\nCOMPONENT            STATUS               IMAGE ID\nfirstcomponent       ready                4ae76210a4fe\nsecondcomponent      stopped              0cf0c034fc89\n```\n\n#### Stopping a component on all machines\n\nTo tell components to stop themselves on all machines, execute:\n\n```sh\nsudo ./gantryd.py stop myprojectname -c firstcomponent secondcomponent\n```\n\nResponse:\n```sh\nMarking components as stopped\n```\n\nAll components specified will start the shutdown process within 30 seconds.\n\n#### Killing a component on all machines\n\nTo order components to kill themselves immediately on all machines, execute:\n\n```sh\nsudo ./gantryd.py kill myprojectname -c firstcomponent secondcomponent\n```\n\nResponse:\n```sh\nMarking components as killed\n```\n\nAll components specified will be killed within 30 seconds.\n\n\n### Gantryd health checks\n\nGantryd supports a number of built-in checks for verifying that a container is properly started, running and healthy.\n\n#### http Health Check\n\n```json\n{ \"kind\": \"http\", \"port\": 8888, \"path\": \"/somepath\" }\n```\n\nAttempts to connect and download the HTTP page located at the given port and path. Fails if the HTTP response is not 2XX. \n\nNote that \"path\" is **optional**.\n\n#### tcp Health Check\n\n```json\n{ \"kind\": \"tcp\", \"port\": 8888 }\n```\n\nAttempts to connect to the given port via TCP. Fails if the connection cannot be established.\n\n\n###\u003ca name=\"gantry\"\u003e\u003c/a\u003eGantry commands\n\n**gantry** is the **local** version of gantry, intended for starting, stopping and updating of components on a **single** machine. Please note that you don't need etcd to be installed (or running) to use **gantry**.\n\n#### Listing all containers running on a local machine for a component\n```sh\nsudo ./gantry.py myconfigfile list firstcomponent\n```\n\nResponse:\n```sh\nCONTAINER ID         UPTIME               IMAGE ID             STATUS              \n39d59e26ee64         Up 17 seconds        my/image:latest      running\n18182e07ade1         Up 2 minutes         0cf0c034fc89         draining\n87b14f60b220         Up 4 minutes         26c8cb358b9d         draining\n```\n\n#### Performing a *local* update of a component\n\n*Note*: This will occur outside of the gantryd event loop, so this should *only* be used for **single machine** or **canary** images.\n\n```sh\nsudo ./gantry.py myconfigfile update firstcomponent\n```\n\nResponse:\n```sh\nStarting container 39d59e26ee64\nWaiting for health checks...\nRunning health check: http\nChecking HTTP address: http://localhost:49320\nRedirecting traffic to new container\nChecking container statuses...\nUpdating proxy...\nStarting monitoring...\nMonitor check started\n```\n\n*Note*: If the `-m` flag is specified, then gantry will remain running and actively monitor the component's container, restarting it automatically if it becomes unhealthy.\n\n#### Stopping all containers running on a local machine for a component\n\n*Note*: This will *drain* containers in a safe way, so the process will block until all containers are free from incoming connections\n\n```sh\nsudo ./gantry.py myconfigfile stop firstcomponent\n```\n\nResponse:\n```sh\nDraining all containers...\nChecking container statuses...\nUpdating proxy...\nStarting monitoring...\nMonitor check started\nShutting down container: 39d59e26ee64\nProxy updated\n```\n\n#### Killing all containers running on a local machine for a component\n```sh\nsudo ./gantry.py myconfigfile kill firstcomponent\n```\n\nResponse:\n```sh\nDraining all containers...\nKilling container d05d73bc6c3\nChecking container statuses...\nShutting down proxy...\n```\n","funding_links":[],"categories":["Container Operations"],"sub_categories":["Orchestration"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDevTable%2Fgantryd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDevTable%2Fgantryd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDevTable%2Fgantryd/lists"}