{"id":16101459,"url":"https://github.com/xdrop/cartel","last_synced_at":"2025-06-14T17:33:16.446Z","repository":{"id":96237363,"uuid":"325559514","full_name":"xdrop/cartel","owner":"xdrop","description":"Local development orchestrator. Process \u0026 dependency management to run development playgrounds","archived":false,"fork":false,"pushed_at":"2025-05-03T16:44:14.000Z","size":1194,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-03T17:38:12.482Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xdrop.png","metadata":{"files":{"readme":"docs/README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2020-12-30T13:36:09.000Z","updated_at":"2025-05-03T16:44:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"0f9d40d0-70f6-4bc2-9800-0f4936f345f8","html_url":"https://github.com/xdrop/cartel","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/xdrop/cartel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdrop%2Fcartel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdrop%2Fcartel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdrop%2Fcartel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdrop%2Fcartel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xdrop","download_url":"https://codeload.github.com/xdrop/cartel/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdrop%2Fcartel/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259854961,"owners_count":22922187,"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-10-09T18:50:00.605Z","updated_at":"2025-06-14T17:33:16.425Z","avatar_url":"https://github.com/xdrop.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cartel\n\n\u003e Local development workflow orchestrator\n\n`cartel` is an orchestration tool aimed at making local development easier for complex systems with multiple services. It allows for codifying the steps required to run some system locally, and providing an easy consistent interface for managing that system. It was heavily inspired by `docker-compose`, `k8s`, and `garden`, but instead works without containers, with both the benefits and drawbacks this approach entails.\n\n[![screencap](./img/screencap.png)](https://asciinema.org/a/bkdw92453mljdVJIcq8bm1LmW)\n\n## Table of contents\n\n- [cartel](#cartel)\n - [Table of contents](#table-of-contents)\n - [Features](#features)\n - [Deploying services](#deploying-services)\n - [Viewing logs](#viewing-logs)\n - [Running tasks](#running-tasks)\n - [Viewing service status](#viewing-service-status)\n - [Stopping / restarting a service](#stopping--restarting-a-service)\n - [Opening a REPL shell](#opening-a-repl-shell)\n - [Executing a command within a service folder](#executing-a-command-within-a-service-folder)\n - [Getting started configuration](#getting-started-configuration)\n - [Installation](#installation)\n - [macOS](#macos)\n - [Linux](#linux)\n - [Windows](#windows)\n - [Reference manual](#reference-manual)\n - [Service definition](#service-definition)\n - [Example](#example)\n - [Task definition](#task-definition)\n - [Example](#example-1)\n - [Shell definition](#shell-definition)\n - [Example](#example-2)\n - [Group definition](#group-definition)\n - [Example](#example-3)\n - [Check definition](#check-definition)\n - [Example](#example-4)\n - [Environment sets](#environment-sets)\n - [Readiness and Liveness probes](#readiness-and-liveness-probes)\n - [Net probe](#net-probe)\n - [Executable probe](#executable-probe)\n - [Log line probe](#log-line-probe)\n - [Suggested fix for checks](#suggested-fix-for-checks)\n\n## Features\n\nWhile `cartel` is still in development (see [CHANGELOG](../CHANGELOG.md)) it has a feature set rich enough to cover most use-cases.\n\nSome of the features included are:\n\n- Deploy services and orchestrate dependencies / tasks that need to be performed before or after a service is deployed.\n- Tail and manage logs of services.\n- Monitor the health of services.\n- Running tasks ad-hoc.\n- Convienient access to REPL shells for services.\n- Perform checks to ensure a machine is set up in a correct state.\n\n`cartel` revolves around modules which are used to codify your local services setup. There are currently _five_ different kinds of modules which are:\n\n- **Task** - A task is a module with a limited lifetime, used to perform some temporary operation or some setup.\n- **Service** - A service is a longer running module. Its lifetime will be managed and can be started, stopped independently.\n- **Group** - A group is a module which serves as a grouping of other modules that need to be deployed together.\n- **Shell** - A shell is a module which allows for a quick way to open a REPL shell for some service.\n- **Check** - A check is a module which defines some condition which must evaluate to true before some service can be operated. This is used to give hints/solutions for common issues that occur during setting up a machine for local development for the first time.\n\n### Deploying services\n\nTo deploy a service (or group):\n\n```\n$ cartel deploy -f \u003cname\u003e\n```\n\nTo deploy more than one service (or group):\n\n```\n$ cartel deploy -f \u003cone\u003e \u003ctwo\u003e \u003cthree\u003e ...\n```\n\nThe `-f` flag always forces deployment of all modules/tasks. If you don't want services in the correct state to be redeployed you can omit it.\n\n### Viewing logs\n\nTo tail the logs of a service/task:\n\n```\n$ cartel logs \u003cname\u003e\n```\n\nTo view _all_ the logs of a service/task:\n\n```\n$ cartel logs -a \u003cname\u003e\n```\n\n### Running tasks\n\nTo run an ad-hoc task:\n\n```\n$ cartel run \u003ctask-name\u003e\n```\n\n### Viewing service status\n\nTo view services and their status:\n\n```\n$ cartel ps\n```\n\n### Stopping / restarting a service\n\nTo start / stop a service:\n\n```\n$ cartel stop \u003cname\u003e\n$ cartel restart \u003cname\u003e\n```\n\n### Opening a REPL shell\n\nTo open a REPL shell to some service. Since services can define multiple types of REPL shells `-t` can distinguish between them based on `type`.\n\n```\n$ cartel shell \u003cservice_name\u003e\n$ cartel shell -t \u003ctype\u003e \u003cservice_name\u003e\n```\n\n### Executing a command within a service folder\n\nTo execute a command within a service's folder use:\n\n```\n$ cartel exec \u003cservice_name\u003e -- \u003ccmd\u003e\n```\n\n## Getting started configuration\n\nHere is a sample configuration that defines one service (`backend`) and one task (`postgres:docker-up`) as a dependency of backend, along with one check (`backend:check-a`).\n\n```\nkind: Service\nname: backend\nchecks: [\"backend:check-a\"]\nshell: make local-run\nworking_dir: ./api/backend\ndependencies: [\"postgres:docker-up\"]\nenvironment:\n PORT: 8080\nreadiness_probe:\n type: net\n host: localhost\n port: 8080\nliveness_probe:\n type: net\n host: localhost\n port: 8080\n---\nkind: Task\nname: postgres:docker-up\nshell: docker-compose up -d postgres\n---\nkind: Check\nname: backend:check-a\nabout: some check\nshell: echo \"always succeed\"\nhelp: Instructions on how to fix\n```\n\nRun `cartel deploy -f backend` to try it out.\n\n## Installation\n\n#### macOS\n\n```\nbrew install xdrop/tap/cartel\n```\n\nand add the following to `~/.zshrc` or `~/.bashrc`:\n\n```\n[ -f $(brew --prefix cartel)/launch-daemon.sh ] \u0026\u0026 . $(brew --prefix cartel)/launch-daemon.sh\n```\n\n#### Linux\n\nLinux users will need to compile manually.\n\n```\n$ git clone https://github.com/xdrop/cartel.git\n$ cd cartel\n$ cargo build --release --all\n$ mv target/release/client /usr/local/bin/cartel\n$ mv target/release/daemon /usr/local/bin/cartel-daemon\n$ chmod +x /usr/local/bin/cartel*\n$ mkdir -p ~/.cartel\n$ cp launch-daemon.sh ~/.cartel\n```\n\nand add the following to `~/.zshrc` or `~/.bashrc`:\n\n```\n[ -f ~/.cartel/launch-daemon.sh ] \u0026\u0026 . ~/.cartel/launch-daemon.sh\n```\n\n#### Windows\n\nWindows is not supported.\n\n## Reference manual\n\n### Service definition\n\nUse `Service` for running long running processes that can be started, stopped and managed by the daemon.\n\n| Property | Description | Values | Example |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------- |\n| kind | Type of the module. Use `Service` for services. | Service | `Service` |\n| name | The name of the service. Only **unique** names allowed. | String | `backend` |\n| command | A command with which to launch the service. This has to be an array of the path to the program and its arguments. This does not invoke a shell so things like pipes (`\\|`) and other shell operators will not work unless explicitly run within a shell (eg. in `bash -c`). The `shell` option described below will always run the command in a shell and should be preferred if use of shell features is required. | String[] | `[\"bash\", \"-c\", \"echo hi\"]` |\n| shell | A shell command with which to launch the service. Unlike `command` this is a cmd line string which is evaluated in a shell context (`bash`). Only **one of** `command`/`shell` must be present. | String | `echo \"This support shell operations\" \u003e myfile` |\n| termination_signal | The termination signal to use when stopping the service (for UNIX based OS). Use `KILL` for `SIGKILL`, `TERM` for `SIGTERM`, and `INT` for `SIGINT`. (Optional) | KILL \\| TERM \\| INT | `\"KILL\"` |\n| environment | The environment variables to pass to the service. (Optional) | Map[String, String] | `HOST: localhost` \u003cbr/\u003e `PORT: 8921` |\n| environment_sets | Sets of environment variables that can be toggled on or off. See example for more details. (Optional) | Map[String, Map[String, String]] | [Environment Sets](#environment-sets) |\n| log_file_path | Path to the log file where stdout and stderr is written. (Optional) | String | `/tmp/my_service.log` |\n| dependencies | A list of module names that have to be deployed _before_ this service runs. (Optional) | String[] | `[\"task-a\", \"service-a\"]` |\n| ordered_dependencies | Same as `dependencies` but each dependency also depends on the previous one. For example in the case of `[a,b,c]` the dependencies are deployed in the following order: `a` then `b` then `c`. This guarantee is not provided by `dependencies`. Ordered dependencies can co-exist with dependencies. (Optional) | String[] | `[\"task-a\", \"service-a\"]` |\n| after | A service or task that should always be deployed _after_ this service, but not a strict dependency of this service. (Optional) | String[] | `[\"task-a\", \"service-a\"]` |\n| post | A list of tasks to perform after the service has been deployed. (Optional) | String[] | `[\"task-a\", \"task-b\"]` |\n| post_up | A list of tasks to perform after the service has been deployed **and** had its readiness probe pass. (Optional) | String[] | `[\"task-a\", \"task-b\"]` |\n| working_dir | The working directory all commands and paths are relative to. Relative directories are allowed and they are relative to the location of the `cartel.yml` file. (Optional) | String | `./services/my-service` |\n| checks | A list of checks to perform before the service is allowed to run. (Optional) | String[] | `[\"check-a\", \"check-b\"]` |\n| readiness_probe | A probe to run with which to determine if the service is healthy. This is used when deploying to wait for the service to come up. (Optional) | Probe | [Readiness \u0026 Liveness Probes](#readiness-and-liveness-probes) |\n| liveness_probe | A probe to run with which to determine if the service is healthy. This is used **after** the service has been deployed to monitor its ongoing health status. This affects things like `cartel ps` and skipping deploying a module if it is already in the correct state and has a passing liveness probe. (Optional) | Probe | [Readiness \u0026 Liveness Probes](#readiness-and-liveness-probes) |\n\n#### Example\n\n```\nkind: Service\nname: backend\nshell: make run\nchecks: [\"backend:image_is_built\"]\nenvironment:\n PYTHONUNBUFFERED: \"1\"\n VSCODE_DEBUG: \"true\"\nenvironment_sets:\n prod:\n DJANGO_SETTINGS_MODULE: \"settings.prod\"\n debug:\n DJANGO_LOG_LEVEL: DEBUG\nworking_dir: ./api/backend\nordered_dependencies: [\"backing-services\", \"backend:poetry_install\", \"backend:run_migrations\"]\nreadiness_probe:\n type: net\n retries: 18\n host: localhost\n port: 5000\nliveness_probe:\n type: net\n host: localhost\n port: 5000\npost_up: [\"backend:refresh_cache\"]\n```\n\n### Task definition\n\nUse `Task` for short lived processes used to perform some temporary operation or setup.\n\n| Property | Description | Values | Example |\n| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------- |\n| kind | Type of the module. Use `Task` for tasks. | Task | `Task` |\n| name | The name of the task. Only **unique** names allowed. | String | `backend:run-migrations` |\n| command | A command with which to launch the task. This has to be an array of the path to the program and its arguments. This does not invoke a shell so things like pipes (`\\|`) and other shell operators will not work unless explicitly run within a shell (eg. in `bash -c`). The `shell` option described below will always run the command in a shell and should be preferred if use of shell features is required. | String[] | `[\"bash\", \"-c\", \"echo hi\"]` |\n| shell | A shell command with which to launch the task. Unlike `command` this is a cmd line string which is evaluated in a shell context (`bash`). Only **one of** `command`/`shell` must be present. | String | `echo \"This support shell operations\" \u003e myfile` |\n| environment | The environment variables to pass to the task. (Optional) | Map[String, String] | `HOST: localhost` \u003cbr/\u003e `PORT: 8921` |\n| log_file_path | Path to the log file where stdout and stderr is written. (Optional) | String | `/tmp/my_service.log` |\n| working_dir | The working directory all commands and paths are relative to. Relative directories are allowed and they are relative to the location of the `cartel.yml` file. (Optional) | String | `./services/my-service` |\n| timeout | Number of seconds without completion before the task is considered failed. If left unspecified this will default to `180` seconds. (Optional) | u64 | 180 |\n\n#### Example\n\n```\nkind: Task\nname: backend:run_migrations\nenvironment:\n PYTHONUNBUFFERED: \"1\"\nshell: poetry run python manage.py migrate\nworking_dir: ./api/backend\n```\n\n### Shell definition\n\nUse `Shell` to define a shortcut for getting a REPL shell for some service.\n\n| Property | Description | Values | Example |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------ |\n| kind | Type of the module. Use `Shell` for shells. | `Shell` | `Shell` |\n| name | The name of the shell. Only **unique** names allowed. | String | `backend:shell` |\n| service | The service this shell is for. This has to match the module name of a service and is **required**. It is what `cartel shell` uses to determine which shell to open. | String | `myservicename` |\n| command | A command with which to launch the shell. This has to be an array of the path to the program and its arguments. This does not invoke a shell so things like pipes (`\\|`) and other shell operators will not work unless explicitly run within a shell (eg. in `bash -c`). | String[] | `[\"bash\", \"-c\", \"echo hi\"]` |\n| shell | A shell command with which to launch the shell. Unlike `command` this is a cmd line string which is evaluated in a shell context (`bash`). Only **one of** `command`/`shell` must be present. | String | `python3 $(get-shell)` |\n| shell_type | The type of the shell. Used to choose between multiple shell options for a service when specifying the `-t` option (eg. `cartel shell -t ipython myservice`) | String | `ipython` |\n| environment | The environment variables to pass to the shell. (Optional) | Map[String, String] | `HOST: localhost` \u003cbr/\u003e `PORT: 8921` |\n| working_dir | The working directory all commands and paths are relative to. Relative directories are allowed and they are relative to the location of the `cartel.yml` file. (Optional) | String | `./services/my-service` |\n\n#### Example\n\n```\nkind: Shell\nname: backend:shell\nservice: backend\ncommand: [poetry, run, ipython]\nworking_dir: ./api/backend\n```\n\n### Group definition\n\nUse `Group` for groupping sets of dependencies that need to be deployed together.\n\n| Property | Description | Values | Example |\n| ------------ | --------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- |\n| kind | Type of the module. Use `Group` for groups. | Group | `Group` |\n| name | The name of the group. Only **unique** names allowed. | String | `groupname` |\n| dependencies | A list of module names that consist this group. When the group is deployed all these dependencies are deployed. | String[] | `[\"task-a\", \"service-a\"]` |\n| checks | A list of checks to perform before the group is allowed to run. (Optional) | String[] | `[\"check-a\", \"check-b\"]` |\n\n#### Example\n\n```\nkind: Group\nname: backing-services\nchecks: [\"backing_services:hosts_file_entries\"]\ndependencies:\n - \"kafka:docker_up\"\n - \"postgres:docker_up\"\n - \"nginx:docker_up\"\n```\n\n### Check definition\n\nUse `Check` to enforce a condition before a service is run (eg. to ensure some local configuration has been performed on the system).\n\n| Property | Description | Values | Example |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------- |\n| kind | Type of the module. Use `Check` for checks. | Check | `Check` |\n| name | The name of the check. Only **unique** names allowed. | String | `service:checkname` |\n| about | A human readable short description of the task. | String | `checks host file for postgres` |\n| command | A command with which to launch the check. This has to be an array of the path to the program and its arguments. This does not invoke a shell so things like pipes (`\\|`) and other shell operators will not work unless explicitly run within a shell (eg. in `bash -c`). The `shell` option described below will always run the command in a shell and should be preferred if use of shell features is required. **The check is only successful if this command exits with zero-code** | String[] | `[\"bash\", \"-c\", \"check-something \\|\\| exit 1\"]` |\n| shell | A shell command with which to launch the check. Unlike `command` this is a cmd line string which is evaluated in a shell context (`bash`). Only **one of** `command`/`shell` must be present. **The check is only successful if this command exits with zero-code** | String | `check-something \\|\\| exit 1` |\n| help | An detailed error message to display the user instructing how to fix the issue the check is concerned with. | String | `Instructional text` |\n| suggested_fix | A command that the user will get asked to run, that can fix the issue this check tests for. (Optional) | SuggestedFix | [Suggested Fix](#suggested-fix-for-checks) |\n| working_dir | The working directory all commands and paths are relative to. Relative directories are allowed and they are relative to the location of the `cartel.yml` file. (Optional) | String | `./services/my-service` |\n\n#### Example\n\n```\nkind: Check\nname: backing_services:postgres_host_file\nabout: postgres host file entry\nshell: cat /etc/hosts | grep postgres\nhelp: |+\n The following entry is missing from your hosts file:\n 127.0.0.1 postgres\nsuggested_fix:\n shell: cat fixed \u003e /tmp/fixed\n message: Details about how this is going to be fixed\n```\n\n### Environment sets\n\nEnvironment sets are sets of environment variables that can be toggled on or off. They are by default **off** and have to be explicitly activated.\n\nFor example we can define two environment sets `debug` and `production`.\n\n```\nkind: Service\nname: my_service\nenvironment:\n SOME_ENV: 1\n LOG_LEVEL: INFO\nenvironment_sets:\n debug:\n DEBUG_MODE: 1\n LOG_LEVEL: DEBUG\n production:\n LOG_LEVEL: ERROR\n```\n\nThen we can activate one or more environment sets using the `-e \u003cenv_set_name\u003e` option.\n\n```\n$ cartel deploy my_service\n# will deploy `my_service` with:\nSOME_ENV=1\nLOG_LEVEL=INFO\n\n$ cartel deploy -e debug my_service\n# will deploy `my_service` with:\nSOME_ENV=1\nDEBUG_MODE=1\nLOG_LEVEL=DEBUG\n\n$ cartel deploy -e debug -e production my_service\n# will deploy `my_service` with:\nSOME_ENV=1\nDEBUG_MODE=1\nLOG_LEVEL=ERROR\n```\n\n### Readiness and Liveness probes\n\n**Readiness probes** are used to determine when a service is **ready** while deploying. This means services that depend on it won't deploy until its readiness checks pass.\n\n**Liveness probes** are used to determine when a service is **healthy** after deploying. This is useful to determine the service status in `cartel ps`, or to skip deploying the service if it is already healthy.\n\nThere are three types **net**work probes, **exec**utable probes, and **log_line** probes. Together they should cover most means for checking the health of a service.\n\n#### Net probe\n\nAttempt to connect to the following host/port. If connection succeeds, the service is considered healthy. For more complex setups look at `exec` prob below combined with `curl`.\n\n```\nreadiness_probe:\n type: net\n # number of failures before considered failed.\n retries: 10\n # The host to connect to\n host: localhost\n # The port to connect to\n port: 8301\n```\n\n#### Executable probe\n\nRun a command to determine the health of the service. If the command exits with `0` status code then the service is considered healthy.\n\n```\nreadiness_probe:\n type: exec\n # number of failures before considered failed.\n retries: 10\n # The command to execute as the probe. Exit code zero is considered healthy.\n command: [\"bash\", \"-c\", \"exit 0\"]\n # Alternatively execute a command in a shell instead of a command array\n shell: exit 0\n # The working directory where the command is performed from.\n working_dir: ./my_service\n```\n\n#### Log line probe\n\nWait for a specific regex to match before considering the service as healthy. Only suitable as a **readiness** check.\n\n```\nreadiness_probe:\n type: log_line\n # number of failures before considered failed.\n retries: 10\n # The regex to attempt to match on a log line.\n line_regex: Listening...\n```\n\n### Suggested fix for checks\n\nA **suggested fix** may be defined for a check that a user may optionally apply.\n\n```\nsuggested_fix:\n # The command to execute to fix the issue.\n command: [\"bash\", \"-c\", \"echo example\"]\n # Alternatively execute a command in a shell instead of a command array.\n shell: echo example\n # A message explaining to the user what the fix will do.\n message: Will add `127.0.0.1` to your /etc/hosts file.\n # The working directory where the command is performed from.\n working_dir: ./my_service\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdrop%2Fcartel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdrop%2Fcartel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdrop%2Fcartel/lists"}