{"id":19932754,"url":"https://github.com/mixmaxhq/custody","last_synced_at":"2025-05-03T11:32:53.487Z","repository":{"id":32168033,"uuid":"131771487","full_name":"mixmaxhq/custody","owner":"mixmaxhq","description":"A developer-oriented frontend for Supervisor","archived":false,"fork":false,"pushed_at":"2023-11-28T16:16:46.000Z","size":1478,"stargazers_count":2,"open_issues_count":15,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-15T15:42:54.661Z","etag":null,"topics":["custody","supported","tooling"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/mixmaxhq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-05-01T22:55:59.000Z","updated_at":"2023-07-18T09:08:41.000Z","dependencies_parsed_at":"2023-11-28T17:43:12.249Z","dependency_job_id":null,"html_url":"https://github.com/mixmaxhq/custody","commit_stats":{"total_commits":134,"total_committers":7,"mean_commits":"19.142857142857142","dds":0.4328358208955224,"last_synced_commit":"d0c70575bc3e9fde5e5ef451d57603b643f51c7a"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fcustody","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fcustody/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fcustody/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmaxhq%2Fcustody/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mixmaxhq","download_url":"https://codeload.github.com/mixmaxhq/custody/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224360219,"owners_count":17298319,"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":["custody","supported","tooling"],"created_at":"2024-11-12T23:11:27.285Z","updated_at":"2024-11-12T23:11:27.931Z","avatar_url":"https://github.com/mixmaxhq.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# custody\n\nSupervisor is great for running a bunch of processes but not for running a local, microservices\ndevelopment environment, where\n\n* services frequently become unstable due to quirks of developers' setups or bugs in Supervisor\nitself ([Mixmax-internal link](https://docs.google.com/document/d/1H37o4X51M5dWzrF5q_bOuZNaaag8iQYMebTEwjhJWBk/edit#heading=h.5tsycreyssqn))\n* the processes monitored by Supervisor may be build e.g. `gulp` processes, not the services whose\nstates change i.e. webservers\n* developers need to rapidly toggle between views of the environment's overall status and logs from\nindividual services\n\n`supervisorctl status`' is too high-level and static for such an environment, and toggling between\nthat view and individual process logs is cumbersome.\n\nEnter custody, which gives you a _realtime_ view of both the environment's overall status and\nindividual services' logs with _minimum keystrokes_.\n\n## Installation\n\n```sh\nnpm install -g @custody/cli\n```\n\n## Configuration\n\nBy default, custody uses `/usr/local/var/custody` to store information and to enable [probe](https://github.com/mixmaxhq/custody-probe)-\u003ecustody communication. You can override this directory by specifying the `CUSTODY_PROC_DIR` environment variable.\n\n**Caution:** Read https://github.com/mixmaxhq/custody/issues/80 to see how to properly configure this variable, if you choose\nto set it.\n\n## Usage\n\n\u003e Node 10.16.0 shipped [a regression](https://github.com/mixmaxhq/custody/issues/82#issuecomment-533348756)\nin file watching that may degrade performance when custody is tailing log files. If you experience\nhigh CPU utilization while using custody, please try running custody under an older version of Node\ne.g. using [`nvm`](https://github.com/nvm-sh/nvm).\n\nMake sure that Supervisor is running. Then run\n\n```sh\ncustody-cli\n```\n\nIf you're running Supervisor on a port other than 9001 (Mixmax engineers: your default),\npass that using the `--port` flag.\n\nThis will show a view like `supervisorctl status`--except real-time and color-coded:\n\n![](docs/status.png)\n\nIf the programs shown here are build processes, that in turn run server processes,\nyou can use [custody-probe](https://github.com/mixmaxhq/custody-probe)\nto report the states of the servers.\n\nScroll through the list using your arrow keys or the mouse--or type to filter to a service of interest:\n\n![](docs/filter.png)\n\nHit enter or double-click on a service to open its logs:\n\n![](docs/logs.png)\n\nWithin this view, you can stop/start/restart the service using the keyboard shortcuts in the bottom toolbar.\n\n### Notifications\n\nIf you run `custody-cli` with `--notifications`, it will show desktop notifications when the\nservices' states change. You can click the \"Show\" button on the notification to activate the Terminal\nand open custody to the corresponding service's logs. This feature is experimental--please contribute\nUX feedback!\n\nIf you'd like notifications to stay on the screen until dismissed, go to System Preferences -\u003e\nNotifications, look for \"terminal-notifier\" in the list at left, and change its alert style from\nBanners to Alerts. We can't do this for you, unfortunately.\n\n## Automatic error recovery\n\nIf you've added [probes](https://github.com/mixmaxhq/custody-probe) to any of your servers,\ncustody can automatically recover certain errors reported by those probes. In particular, if a\nserver reports an EADDRINUSE error (see https://github.com/mixmaxhq/custody/issues/3), custody will\nautomatically fix the port conflict by killing the process listening to your desired port, then\nrestarting your process.\n\n## Contributing / Roadmap\n\nWe welcome bug reports and feature suggestions. PRs are even better!\n\nCheck out the issues and milestones to see what you could tackle to get this project to v1 and\nbeyond.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixmaxhq%2Fcustody","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmixmaxhq%2Fcustody","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixmaxhq%2Fcustody/lists"}