{"id":17188246,"url":"https://github.com/jclem/teamster","last_synced_at":"2025-04-13T19:14:11.093Z","repository":{"id":20486275,"uuid":"23764389","full_name":"jclem/teamster","owner":"jclem","description":"Unix-y cluster manager","archived":false,"fork":false,"pushed_at":"2015-06-09T18:06:48.000Z","size":330,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"development","last_synced_at":"2025-04-10T17:31:12.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://npm.im/teamster","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/jclem.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":"2014-09-07T16:21:16.000Z","updated_at":"2023-10-28T21:47:22.000Z","dependencies_parsed_at":"2022-07-31T21:38:01.896Z","dependency_job_id":null,"html_url":"https://github.com/jclem/teamster","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fteamster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fteamster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fteamster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fteamster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jclem","download_url":"https://codeload.github.com/jclem/teamster/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766751,"owners_count":21158301,"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-15T01:08:29.873Z","updated_at":"2025-04-13T19:14:11.064Z","avatar_url":"https://github.com/jclem.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# teamster [![Circle CI](https://circleci.com/gh/jclem/teamster/tree/master.svg?style=svg)](https://circleci.com/gh/jclem/teamster/tree/master)  [![Code Climate](https://codeclimate.com/github/jclem/teamster/badges/gpa.svg)](https://codeclimate.com/github/jclem/teamster) [![Test Coverage](https://codeclimate.com/github/jclem/teamster/badges/coverage.svg)](https://codeclimate.com/github/jclem/teamster)\n\n\u003e **The twelve-factor app's [processes][processes] are *disposable*, meaning\n\u003e they can be started or stopped at a moment's notice.** This facilitates fast\n\u003e elastic scaling, rapid deployment of [code][code] or [config][config]\n\u003e changes, and robustness of production deploys.\n\u003e\n\u003e Processes **shut down gracefully when they receive a [SIGTERM][sigterm]**\n\u003e signal from the process manager. For a web process, graceful shutdown is\n\u003e achieved by ceasing to listen on the service port (thereby refusing any new\n\u003e requests), allowing any current requests to finish, and then exiting.\n\n*— [The Twelve-Factor App][twelve-factor]*\n\nTeamster is a Twelve-Factor-compliant, Unix-y worker process manager for Node.\nIts primary use is to facilitate the painless running and graceful shutdown of\nHTTP servers, but it has many other potential use cases.\n\nClusters running with teamster listen for the Unix signal `SIGTERM`, and then\nattempt to shut down their worker processes gracefully. This is useful in both\nsingle-worker and multiple-worker situations, as in both cases it's desirable\nfor an HTTP server to finish serving any requests in progress before exiting.\n\nWhen a teamster master process receives the `SIGTERM` signal, it tells all of\nthe worker processes to stop accepting new connections, serve their requests\nalready in progress, and then exit.\n\n## Install\n\n```sh\nnpm install teamster --save\n```\n\n## Usage\n\n### Run a function\n\nTeamster can run a single function for you in a worker or workers. Simply pass\n`#run` a function as the first argument.\n\n```javascript\nrequire('teamster').run(function work() {\n  console.log('I am a worker!');\n}, options);\n```\n\n### Run an HTTP server\n\nAlthough you could easily do this with `#run`, teamster can also run an HTTP\nserver for you with `#runServer`. The first argument to `#runServer`\nshould be a function with the standard Node request handler signature, which\nincludes Express apps.\n\n```javascript\nrequire('teamster').runServer(function handleRequest(req, res) {\n  res.end('I am served from a worker!');\n}, options);\n```\n\nNote that `#runServer` will either run on a `port` specified in the optional\n`options` object argument, or any available port.\n\n### Options\n\nBoth `#run` and `#runServer` accept an optional second `options` argument.\n\n| Option       | Type            | Default     | Description                                                                               | `#run` | `#runServer` |\n| ------------ | --------------- | ----------- | ----------------------------                                                              | ------ | ------------ |\n| `verbose`    | boolean         | `true`      | Whether or not to include verbose logging of fork/disconnect/exit events                  |   ✓    |      ✓       |\n| `numWorkers` | number          | # cpus      | The number of workers to fork                                                             |   ✓    |      ✓       |\n| `timeout`    | number          | `5000`      | The number of seconds to wait after attempting graceful shutdown to forcibly kill workers |   ✓    |      ✓       |\n| `hostname`   | string          | `undefined` | The hostname that the server should bind to                                               |        |      ✓       |\n| `port`       | number, string  | `undefined` | The port that the server should listen on                                                 |        |      ✓       |\n| `fork`       | boolean         | `true`      | Whether or not to actually fork a child process (useful for development)                  |   ✓    |      ✓       |\n\n## Signals\n\nTeamster works by responding to [Unix signals][unix_signals]. Typically, you'll\nonly want to send signals to teamster's master process, and it will forward\nsignals onto the worker processes as appropriate.\n\n| Signal    | Trap all or once?       | Effect                                                                                                                                                                                                 |\n| --------- | ----------------------- | ----------------------------                                                                                                                                                                           |\n| `SIGTERM` | all                     | If not already shutting down, begin to attempt a graceful shutdown of all workers. If a worker does not shut down after `timeout`, the worker is killed immediately. If already shutting down, ignore. |\n| `SIGINT`  | once                    | Log the signal and then forward it again, which will immmediately kill the master and all worker processes.                                                                                            |\n| `SIGTTIN` | all                     | Fork an additional worker unless shutting down.                                                                                                                                                        |\n| `SIGTTOU` | all                     | Disconnect a worker unless shutting down. When the number of workers reaches 0, the master process will exit.                                                                                          |\n\n## Caveat\n\nNode is very fast, and it's unlikely that you need to be run a process for each\nCPU. It's more likely you'll have unused workers and unnecessarily high memory\nusage, unless you've done testing and are sure you'll benefit from running more\nthan a single worker process. Even with a single worker, however, teamster is\nuseful, as it will take care of graceful worker shutdowns for you.\n\n## Thanks, Heroku\n\nWhile I created and maintain this project, it was done while I was an employee\nof [Heroku][heroku] on the Human Interfaces Team, and they were kind enough to\nallow me to open source the work. Heroku is awesome.\n\n[unix_signals]: http://en.wikipedia.org/wiki/Unix_signal\n[sigterm]: http://en.wikipedia.org/wiki/SIGTERM\n[processes]: http://12factor.net/processes\n[code]: http://12factor.net/codebase\n[config]: http://12factor.net/config\n[twelve-factor]: http://12factor.net/disposability\n[heroku]: https://www.heroku.com/home\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjclem%2Fteamster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjclem%2Fteamster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjclem%2Fteamster/lists"}