{"id":18430651,"url":"https://github.com/trivago/chapi","last_synced_at":"2025-10-04T01:32:00.397Z","repository":{"id":35548792,"uuid":"39820349","full_name":"trivago/chapi","owner":"trivago","description":"chronos \u0026 marathon console client - Manage your jobs like a git repository","archived":false,"fork":false,"pushed_at":"2023-04-19T18:38:34.000Z","size":752,"stargazers_count":15,"open_issues_count":12,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2023-10-22T15:46:50.758Z","etag":null,"topics":["api-client","chronos","git","marathon","mesos","mesosphere"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/trivago.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-28T07:48:05.000Z","updated_at":"2023-09-10T00:52:48.000Z","dependencies_parsed_at":"2024-11-06T05:36:59.405Z","dependency_job_id":null,"html_url":"https://github.com/trivago/chapi","commit_stats":{"total_commits":382,"total_committers":15,"mean_commits":"25.466666666666665","dds":"0.24869109947643975","last_synced_commit":"40b6bb04e32f969bf3d79a15fb938fba9b084c08"},"previous_names":[],"tags_count":13,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivago%2Fchapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivago%2Fchapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivago%2Fchapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trivago%2Fchapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trivago","download_url":"https://codeload.github.com/trivago/chapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247698168,"owners_count":20981312,"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":["api-client","chronos","git","marathon","mesos","mesosphere"],"created_at":"2024-11-06T05:21:50.082Z","updated_at":"2025-10-04T01:32:00.345Z","avatar_url":"https://github.com/trivago.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chapi [![Build Status](https://travis-ci.org/trivago/chapi.svg?branch=master)](http://travis-ci.org/trivago/chapi) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/trivago/chapi/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/trivago/chapi/?branch=master) [![Code Coverage](https://scrutinizer-ci.com/g/trivago/chapi/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/trivago/chapi/?branch=master)\nChronos and marathon api client for your console. \n\n## Description\nManage your [Chronos](https://github.com/mesos/chronos) and [Marathon](https://github.com/mesosphere/marathon) tasks like a git repository in your console:\n\n* Prepare your tasks before you send them to Remote\n* Manage a separate git repository for task backups and history\n* Quickly check your tasks' status\n\nIt is possible to use either of the systems independently or both at once.\n\n## Requirements\n\n* php \u003e= 5.6\n\n## Installation / Configuration\n\nTo install chapi you can download the latest [release](https://github.com/trivago/chapi/releases) or clone this repository.\nIf you clone the repository you need to run a `composer install` to install all necessary dependencies:\n\n```Shell\ncomposer install\n``` \n\nBefore you use chapi the first time you have to setup your chronos api url and the path to your local task repository.\nYou can use the `configure` command to setup your global settings:\n\n```Shell\nbin/chapi configure \n```\n\n### Configuration file locations\nChapi attempts to read a global and a local configuration file, at least one of which must exist. \nShould both files exist, values found in the local configuration override those defined in the global one.\n\nThe global configuration file's location is\n\n- `~/.chapi/.chapiconfig`\n  if $CHAPI_HOME is not set\n\n- `${CHAPI_HOME}/.chapiconfig`, \n  if $CHAPI_HOME is set\n\nThe local configuration searched for in your current working directory.\n\n- `${PWD}/.chapiconfig`,\n\n### Profiles\nYou can switch between different profiles by using the global\n`--profile[=PROFILE]` option.\n\nIf no profile is set chapi will use `default` as active profile.\n\n\n### Configuration file contents\nBoth configuration files are in the [yaml](http://yaml.org/) format. \n\nThe configuration is located in the `profiles` property. \nThere you will find the `parameters` for each set profile.\n\n`default` will be used if you don't use a explicit profile.\n\n```yaml\nprofiles:\n    default:\n        parameters:\n            chronos_url: http://your.chronos.url:chronos_api_port/\n            chronos_http_username: username\n            chronos_http_password: password\n            repository_dir: /path/to/your/local/task/repository\n        \n            marathon_url: http://your.marathon.url:marathon_api_port/\n            marathon_http_username: username\n            marathon_http_password: password\n            repository_dir_marathon: /path/to/your/local/marathon/apps/repository\n        \n            cache_dir: /path/to/chapi/cache/dir\n            \n        ignore:\n          - *-dev\n          - !my-active-job-dev\n    develop:\n       parameters:\n           chronos_url: http://your.chronos.url:chronos_api_port/\n           chronos_http_username: ''\n           chronos_http_password: ''\n           repository_dir: /path/to/your/local/task/repository\n      \n           marathon_url: ''\n           marathon_http_username: ''\n           marathon_http_password: ''\n           repository_dir_marathon: ''\n      \n           cache_dir: /path/to/chapi/cache/dir_dev\n```\n\n#### `chronos_url`\nThe chronos api url (inclusive port). See also [configure command](#configure) option `-u`.\n\n#### `chronos_http_username`\nThe chronos http username. See also [configure command](#configure) option `-un`.\n\nNecessary if the setting `--http_credentials` is activated in your Chronos instance.\n\n#### `chronos_http_password`\nThe chronos http password. See also [configure command](#configure) option `-un`.\n\nNecessary if the setting `--http_credentials` is activated in your Chronos instance.\n\n#### `repository_dir`\nRoot path to your job files. See also [configure command](#configure) option `-r`.\n\n#### `marathon_url`\nThe marathon api url (inclusive port). See also [configure command](#configure) option `-mu`.\n\n#### `marathon_http_username`\nThe marathon http username. See also [configure command](#configure) option `-mun`.\n\n#### `marathon_http_password`\nThe marathon http password. See also [configure command](#configure) option `-mp`.\n\n#### `repository_dir_marathon`\nRoot path to your tasks folder. See also [configure command](#configure) option `-mr`.\n\n#### `cache_dir`\nPath to cache directory. See also [configure command](#configure) option `-d`.\n\n### Update notes\n\n#### v0.9.0\n\nBecause of the new marathon support with v0.9.0 you need to update your configurations.\nThe `parameters.yml` structure changed and renamed to `.chapiconfig`.\n\nYou need to recreate your config settings: \n\n```sh\nbin/chapi configure\n```\n\n### Disabling services\n\nTo disable Chronos support and only use Marathon, set all the \nChronos parameters to `''`:\n\n```yaml\nprofiles:\n    default:\n        parameters:\n            # [....]\n            chronos_url: ''\n            chronos_http_username: ''\n            chronos_http_password: ''\n            repository_dir: ''\n```\n\n## Ignoring jobs\n\nYou can specify pattern for each profile in your `.chapiconfig` file(s) and add a file to your job repositories to untrack jobs you want chapi to ignore.\n\n* The matching pattern according to the rules used by the libc [glob()](https://en.wikipedia.org/wiki/Glob_(programming)) function, which is similar to the rules used by common shells.\n* An optional prefix \"`!`\" which negates the pattern; any matching job excluded by a previous pattern will become included again.\n\nExample content:\n```yaml\nprofiles:\n    default:\n        ignore:\n          - *-dev\n          - !my-active-job-dev\n    dev:\n        ignore:\n          - \"*\"\n          - \"!*-dev\"\n```\n\n## Usage\n\n### list\nDisplay your tasks and filter them by failed\n\n```Shell\nbin/chapi list [options] \n```\n\n    Options:\n      -f, --onlyFailed      Display only failed jobs\n      -d, --onlyDisabled    Display only disabled jobs\n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n### info\nDisplay your task information from remote system\n\n```Shell\nbin/chapi info \u003cjobName\u003e \n```\n\n    Arguments:\n      jobName               selected job\n      \n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n      \nThe task name in case of marathon would be the full id for the task.\n\n### status\nShow the working tree status\n\n```Shell\nbin/chapi status\n```\n\n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n### diff\nShow changes between tasks and working tree, etc\n\n```Shell\nbin/chapi diff [\u003cjobName\u003e]\n```\n\n    Arguments:\n      jobName               Show changes for specific job\n      \n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n### add\nAdd task contents to the index\n\n```Shell\nbin/chapi add [\u003cjobnames\u003e]...\n```\n\n    Arguments:\n      jobnames              Jobs to add to the index\n      \n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n \n### reset \nRemove tasks from the index\n\n```Shell\nbin/chapi reset [\u003cjobnames\u003e]...\n```\n\n    Arguments:\n      jobnames              Jobs to add to the index\n      \n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n### pull\nPull tasks from remote system and add them to local repository\n\n```Shell\nbin/chapi pull [options] [--] [\u003cjobnames\u003e]...\n```\n\n    Arguments:\n      jobnames              Jobnames to pull\n    \n    Options:\n      -f, --force           Force to overwrite local jobs \n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n### commit\nSubmit changes to chronos or marathon\n\n```Shell\nbin/chapi commit\n```\n\n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n### scheduling\nDisplay upcoming jobs in a specified timeframe\n\n```Shell\nbin/chapi scheduling [options]\n```\n\n    Options:\n      -s, --starttime[=STARTTIME]  Start time to display the jobs\n      -e, --endtime[=ENDTIME]      End time to display the jobs\n      --profile[=PROFILE]  Use a specific profile from your config file.\n      \n**Note: Not applicable to marathon**\n\n### configure\nConfigure application and add necessary configs\n\n```Shell\nbin/chapi configure\n```\n\n    Options:\n      -u, --chronos_url[=CHRONOS_URL]        The chronos url (inclusive port)\n      -un, --chronos_http_username[=CHRONOS_HTTP_USERNAME]  The chronos username (HTTP credentials) [default: \"\"]\n      -p, --chronos_http_password[=CHRONOS_HTTP_PASSWORD]   The chronos password (HTTP credentials) [default: \"\"]\n      -d, --cache_dir[=CACHE_DIR]            Path to cache directory\n      -r, --repository_dir[=REPOSITORY_DIR]  Root path to your job files\n      --profile[=PROFILE]  Use a specific profile from your config file.\n      \n### validate\nValidate local jobs\n\n```Shell\nbin/chapi validate [\u003cjobmames\u003e]...\n```\n\n    Arguments:\n      jobmames              Jobs to validate\n      \n    Options:\n      --profile[=PROFILE]  Use a specific profile from your config file.\n\n## Example workflows\n\n### Add a new job to chronos\nA typical workflow to add a new cronjob to your Chronos server via chapi can be:\n\n1. A pull request for a new cronjob (json definition) comes in a git repository (created by a colleague of you)\n2. Accept the pull request and switch to your local clone via `cd ~/my/clone`\n3. Update your local repository via `git pull`\n4. Check the current status via `chapi status`\n5. Validate everything via `chapi validate .`\n6. Add the new job via `chapi add jobXy`\n7. Apply the changes and update the Chronos server via `chapi commit`\n\n### Move jobs from chronos cluster A to cluster B successively\nChapi is able to support you if you need to move your tasks from a chronos cluster to another one.\n\n1. Setup your normal chapi config and local job repository\n\n2. Create a new empty folder which stands for your second chronos cluster repository:\n```Shell\nmkdir clusterBjobs\n```\n\n3. Add a local `.chapiconfig` file (see [configuration](#installation_configuration)) to the new folder:\n```Shell\ntouch clusterBjobs/.chapiconfig\n```\n\n4. Edit the file and add the `chronos_url` and `repository_dir` parameters for your second chronos cluster:\n```yml\nparameters:\n    chronos_url: http://your.second.chronos.url:chronos_api_port/\n    repository_dir: /path/to/clusterBjobs\n```\n\n5. Open a second console and switch to the new folder where the `.chapiconfig` file is located:\n```Shell\ncd clusterBjobs\n```\n\n6. Now you are able to move job for job from your normal repository to the new repository:\n```Shell\nmv clusterAjobs/jobXy.json clusterBjobs/jobXy.json\n```\n\n7. Chapi in console 1 will delete the jobs from the \"old\" cluster and chapi in the second console 2 will add the moved jobs to the new one.\n\n\n## Supported commands for either system\n|            | chronos            | marathon           |\n|------------|--------------------|--------------------|\n| list       | :white_check_mark: | :white_check_mark: |\n| info       | :white_check_mark: | :white_check_mark: |\n| status     | :white_check_mark: | :white_check_mark: |\n| diff       | :white_check_mark: | :white_check_mark: |\n| add        | :white_check_mark: | :white_check_mark: |\n| reset      | :white_check_mark: | :white_check_mark: |\n| pull       | :white_check_mark: | :white_check_mark: |\n| commit     | :white_check_mark: | :white_check_mark: |\n| scheduling | :white_check_mark: | n.a.               |\n| configure  | :white_check_mark: | :white_check_mark: |\n| validate   | :white_check_mark: |                    |\n\n\n## Special cases in marathon:\n* Pulling a task from marathon will dump the json object with default values.\n    This is the choice for now because calling marathon for app info sends\n    the default values set as well. Logic to check this could be implemented in future.\n* Group apps cannot be pulled from marathon in the configuration with which\n    it was posted. This is because once an app is in marathon, the group\n    specific config is lost.\n* The marathon App id should be be prefixed by `/`.\n    This is a good practice. The reason this needs to be forced is because\n    the local configuration with `myapp` will be seen in marathon as `/myapp`\n    and by chapi as two different apps.\n\nIf you find any further issues or edge case, please create an issue.\n\n\n## Supported Chronos versions\n* v2.5\n\n## Supported Marathon versions\n* v1.6.322\n\n## Docker\n\nYou can run chapi also in a docker container.\nYou will find the laster releases under [dockerhub](https://hub.docker.com/r/msiebeneicher/chapi-client/).\n\n### Prepare a config file for docker\n\nCreate a `.chapiconfig_docker` file with the following content:\n\n```yaml\nprofiles:\n    default:\n        parameters:\n            cache_dir: /root/.chapi/cache\n            chronos_url: 'http://your.chronos.url:4400/'\n            chronos_http_username: YOUR_CHRONOS_USER\n            chronos_http_password: YOUR_CHRONOS_PASS\n            repository_dir: /chronos-jobs\n            marathon_url: 'http://your.marathon.url:8080/'\n            marathon_http_username: YOUR_MARATHON_USER\n            marathon_http_password: YOUR_MARATHON_PASS\n            repository_dir_marathon: /marathon-jobs\n```\n\n### Run docker\n\n```sh\ndocker pull msiebeneicher/chapi-client:latest\n\ndocker run -it \\\n    -v ~/.chapiconfig_docker:/root/.chapi/.chapiconfig \\\n    -v /your/local/checkout/chronos-jobs:/chronos-jobs \\\n    -v /your/local/checkout/marathon-jobs:/marathon-jobs \\\n    msiebeneicher/chapi-client:latest \u003cCOMMAND\u003e\n```\n\n### Run docker for development\n\n```sh\ndocker pull msiebeneicher/chapi-client:latest\n\ndocker run -it \\\n    -v ~/.chapiconfig_docker:/root/.chapi/.chapiconfig_docker \\\n    -v /your/local/checkout/chronos-jobs:/chronos-jobs \\\n    -v /your/local/checkout/marathon-jobs:/marathon-jobs \\\n    -v /your/local/checkout/chapi:/chapi \\\n    --entrypoint /bin/bash \\\n    msiebeneicher/chapi-client:latest\n```\n\n## Todos:\n\n### Marathon\n- [ ] The validate command for marathon is not yet implemented.\n- [ ] The list command has status set as `ok` for marathon entities. This could show the last status of the app.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrivago%2Fchapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrivago%2Fchapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrivago%2Fchapi/lists"}