Local development workflow orchestrator

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.

• cartel
  • Table of contents
  • Features
    • Deploying services
    • Viewing logs
    • Running tasks
    • Viewing service status
    • Stopping / restarting a service
    • Opening a REPL shell
    • Executing a command within a service folder
  • Getting started configuration
  • Installation
    • macOS
    • Linux
    • Windows
  • Reference manual
    • Service definition
      • Example
    • Task definition
      • Example
    • Shell definition
      • Example
    • Group definition
      • Example
    • Check definition
      • Example
    • Environment sets
    • Readiness and Liveness probes
      • Net probe
      • Executable probe
      • Log line probe
    • Suggested fix for checks

While cartel is still in development (see CHANGELOG) it has a feature set rich enough to cover most use-cases.

Some of the features included are:

• Deploy services and orchestrate dependencies / tasks that need to be performed before or after a service is deployed.
• Tail and manage logs of services.
• Monitor the health of services.
• Running tasks ad-hoc.
• Convienient access to REPL shells for services.
• Perform checks to ensure a machine is set up in a correct state.

cartel revolves around modules which are used to codify your local services setup. There are currently five different kinds of modules which are:

• Task - A task is a module with a limited lifetime, used to perform some temporary operation or some setup.
• Service - A service is a longer running module. Its lifetime will be managed and can be started, stopped independently.
• Group - A group is a module which serves as a grouping of other modules that need to be deployed together.
• Shell - A shell is a module which allows for a quick way to open a REPL shell for some service.
• 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.

To deploy a service (or group):

$ cartel deploy -f <name>

To deploy more than one service (or group):

$ cartel deploy -f <one> <two> <three> ...

The -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.

To tail the logs of a service/task:

$ cartel logs <name>

To view all the logs of a service/task:

$ cartel logs -a <name>

To run an ad-hoc task:

$ cartel run <task-name>

To view services and their status:

$ cartel ps

To start / stop a service:

$ cartel stop <name>
$ cartel restart <name>

To open a REPL shell to some service. Since services can define multiple types of REPL shells -t can distinguish between them based on type.

$ cartel shell <service_name>
$ cartel shell -t <type> <service_name>

To execute a command within a service's folder use:

$ cartel exec <service_name> -- <cmd>

Here 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).

kind: Service
name: backend
checks: ["backend:check-a"]
shell: make local-run
working_dir: ./api/backend
dependencies: ["postgres:docker-up"]
environment:
    PORT: 8080
readiness_probe:
  type: net
  host: localhost
  port: 8080
liveness_probe:
  type: net
  host: localhost
  port: 8080
---
kind: Task
name: postgres:docker-up
shell: docker-compose up -d postgres
---
kind: Check
name: backend:check-a
about: some check
shell: echo "always succeed"
help: Instructions on how to fix

Run cartel deploy -f backend to try it out.

brew tap xdrop/homebrew-tap
brew install cartel

and add the following to ~/.zshrc and ~/.bashrc:

[ -f /usr/local/opt/cartel/launch-daemon.sh ] && . /usr/local/opt/cartel/launch-daemon.sh

Linux users will need to compile manually (ensure Rust Nightly is installed).

$ git clone https://github.com/xdrop/cartel.git
$ cd cartel
$ cargo build --release --all
$ mv target/release/client /usr/local/bin/cartel
$ mv target/release/daemon /usr/local/bin/cartel-daemon
$ chmod +x /usr/local/bin/cartel*
$ mkdir -p ~/.cartel
$ cp launch-daemon.sh ~/.cartel

and add the following to ~/.zshrc and ~/.bashrc:

[ -f ~/.cartel/launch-daemon.sh ] && . ~/.cartel/launch-daemon.sh

Windows is not supported.

Use Service for running long running processes that can be started, stopped and managed by the daemon.

kind: Service
name: backend
shell: make run
checks: ["backend:image_is_built"]
environment:
  PYTHONUNBUFFERED: "1"
  VSCODE_DEBUG: "true"
environment_sets:
  prod:
    DJANGO_SETTINGS_MODULE: "settings.prod"
  debug:
    DJANGO_LOG_LEVEL: DEBUG
working_dir: ./api/backend
ordered_dependencies: ["backing-services", "backend:poetry_install", "backend:run_migrations"]
readiness_probe:
  type: net
  retries: 18
  host: localhost
  port: 5000
liveness_probe:
  type: net
  host: localhost
  port: 5000
post_up: ["backend:refresh_cache"]

Use Task for short lived processes used to perform some temporary operation or setup.

kind: Task
name: backend:run_migrations
environment:
  PYTHONUNBUFFERED: "1"
shell: poetry run python manage.py migrate
working_dir: ./api/backend

Use Shell to define a shortcut for getting a REPL shell for some service.

kind: Shell
name: backend:shell
service: backend
command: [poetry, run, ipython]
working_dir: ./api/backend

Use Group for groupping sets of dependencies that need to be deployed together.

kind: Group
name: backing-services
checks: ["backing_services:hosts_file_entries"]
dependencies:
 - "kafka:docker_up"
 - "postgres:docker_up"
 - "nginx:docker_up"

Use Check to enforce a condition before a service is run (eg. to ensure some local configuration has been performed on the system).

kind: Check
name: backing_services:postgres_host_file
about: postgres host file entry
shell: cat /etc/hosts | grep postgres
help: |+
  The following entry is missing from your hosts file:
    127.0.0.1 postgres
suggested_fix:
  shell: cat fixed > /tmp/fixed
  message: Details about how this is going to be fixed

Environment sets are sets of environment variables that can be toggled on or off. They are by default off and have to be explicitly activated.

For example we can define two environment sets debug and production.

kind: Service
name: my_service
environment:
    SOME_ENV: 1
    LOG_LEVEL: INFO
environment_sets:
    debug:
        DEBUG_MODE: 1
        LOG_LEVEL: DEBUG
    production:
        LOG_LEVEL: ERROR

Then we can activate one or more environment sets using the -e <env_set_name> option.

$ cartel deploy my_service
# will deploy `my_service` with:
SOME_ENV=1
LOG_LEVEL=INFO

$ cartel deploy -e debug my_service
# will deploy `my_service` with:
SOME_ENV=1
DEBUG_MODE=1
LOG_LEVEL=DEBUG

$ cartel deploy -e debug -e production my_service
# will deploy `my_service` with:
SOME_ENV=1
DEBUG_MODE=1
LOG_LEVEL=ERROR

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.

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.

There are three types network probes, executable probes, and log_line probes. Together they should cover most means for checking the health of a service.

Attempt 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.

readiness_probe:
    type: net
    # number of failures before considered failed.
    retries: 10
    # The host to connect to
    host: localhost
    # The port to connect to 
    port: 8301

Run a command to determine the health of the service. If the command exits with 0 status code then the service is considered healthy.

readiness_probe:
    type: exec
    # number of failures before considered failed.
    retries: 10
    # The command to execute as the probe. Exit code zero is considered healthy.
    command: ["bash", "-c", "exit 0"]
    # Alternatively execute a command in a shell instead of a command array
    shell: exit 0
    # The working directory where the command is performed from.
    working_dir: ./my_service

Wait for a specific regex to match before considering the service as healthy. Only suitable as a readiness check.

readiness_probe:
    type: log_line
    # number of failures before considered failed.
    retries: 10
    # The regex to attempt to match on a log line.
    line_regex: Listening...

A suggested fix may be defined for a check that a user may optionally apply.

suggested_fix:
  # The command to execute to fix the issue.
  command: ["bash", "-c", "echo example"]
  # Alternatively execute a command in a shell instead of a command array.
  shell: echo example
  # A message explaining to the user what the fix will do.
  message: Will add `127.0.0.1` to your /etc/hosts file.
  # The working directory where the command is performed from.
  working_dir: ./my_service