{"id":15393382,"url":"https://github.com/andrewrk/naught","last_synced_at":"2025-04-08T09:06:56.384Z","repository":{"id":4469142,"uuid":"5607969","full_name":"andrewrk/naught","owner":"andrewrk","description":"Zero downtime deployment for your Node.js server using builtin cluster API","archived":false,"fork":false,"pushed_at":"2022-10-26T14:37:28.000Z","size":808,"stargazers_count":793,"open_issues_count":34,"forks_count":69,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-04-01T08:32:16.010Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/andrewrk.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}},"created_at":"2012-08-29T23:16:17.000Z","updated_at":"2025-03-05T16:06:47.000Z","dependencies_parsed_at":"2022-09-13T20:53:33.150Z","dependency_job_id":null,"html_url":"https://github.com/andrewrk/naught","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewrk%2Fnaught","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewrk%2Fnaught/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewrk%2Fnaught/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewrk%2Fnaught/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewrk","download_url":"https://codeload.github.com/andrewrk/naught/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809964,"owners_count":20999816,"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-01T15:19:07.856Z","updated_at":"2025-04-08T09:06:56.341Z","avatar_url":"https://github.com/andrewrk.png","language":"JavaScript","readme":"# naught\n\n[![Build Status](https://secure.travis-ci.org/andrewrk/naught.png)](http://travis-ci.org/andrewrk/naught)\n\n## Features:\n\n * Zero downtime code deployment\n * Resuscitation - when a worker dies it is restarted\n * Redirect worker stdout and stderr to rotating gzipped log files\n * Runs as daemon, providing ability to start and stop\n * Clustering - take advantage of multiple CPU cores\n * Properly handles SIGTERM and SIGHUP for integration with service wrappers\n * Ability to gracefully handle uncaught exceptions\n * Supports POSIX operating systems (does not support Windows)\n\n## Usage:\n\nTo use naught, your node.js server has 2 requirements.\n\n1. Once the server is fully booted and is readily accepting connections,\n\n   ```js\n   process.send('online');\n   ```\n\n   Usually this is done in the `listening` event for a node server, for\n   example:\n\n   ```js\n   server = http.createServer(...);\n   server.listen(80, function () {\n     if (process.send) process.send('online');\n   });\n   ```\n\n2. Listen to the `shutdown` message and shutdown gracefully. This message\n   is emitted after there is already a newer instance of your server\n   online and taking care of business:\n\n   ```js\n   process.on('message', function(message) {\n     if (message === 'shutdown') {\n       performCleanup();\n       process.exit(0);\n     }\n   });\n   ```\n\n   If your server has no long-lived connections, you may skip this step.\n   However, note that most node.js apps do have long lived connections.\n   In fact, by default, the connection: keep-alive header is sent with\n   every request.\n\n   When you receive the `shutdown` message, either close all open\n   connections or call `process.exit()`.\n\n## Gracefully Handling Exceptions\n\nAnother way you can use naught is to gracefully handle exceptions that would\nnormally cause errors for users other than the one that triggered the\nexception.\n\nIt is common practice to allow an uncaught exception to crash the Node.js\nprocess. In the case of a web server, that forcefully ends the execution\nof all other connections, resulting in more than a single user getting an\nerror.\n\nUsing naught a worker can use the 'offline' message to announce that it is\ndying. At this point, naught prevents it from accepting new connections and\nspawns a replacement worker, allowing the dying worker to finish up with\nits current connections and do any cleanup necessary before finally perishing.\n\nTo take advantage of this, you need a way of catching the uncaught exceptions\nthat cause crashes. There are two ways:\n\n * [Domains](http://nodejs.org/api/domain.html)\n * [uncaughtException](http://nodejs.org/api/process.html#process_event_uncaughtexception)\n\nThe documentation says to use Domains, so use that unless you have a better\nreason.\n\n## Authbind\n\nIf you want to deploy on a restricted port such as 80 or 443 without sudo, try\n[authbind](http://www.debian-administration.org/articles/386).\n\nNote that there are 3 layers of process spawning between the naught CLI\nand your server. So you'll want to use the `--deep` option with authbind.\n\n## Using a service wrapper\n\nIt may make sense to use naught with other process monitoring software.\nFor this reason, naught supports listening to SIGTERM to do a `stop`\noperation, and SIGHUP to do a `deploy` operation. You may also run\nin the foregroun with `--daemon-mode false`.\n\nWhen you run with `--daemon-mode true` (the default), the process tree looks\nlike this:\n\n * CLI process, spawns the following (detached) and then exits:\n   * daemon process, listens for SIGTERM/SIGHUP, spawns the following and\n     stays running:\n     * cluster master process, spawns the following and stays running:\n         * worker 1\n         * worker 2\n         * etc\n\nWhen you run with `--daemon-mode false`, the process tree looks like this:\n\n * CLI process, listens for SIGTERM/SIGHUP, spawns the following and stays\n   running:\n   * cluster master process, spawns the following and stays running:\n     * worker 1\n     * worker 2\n     * etc\n\n## CLI\n\n    naught start [options] server.js [script-options]\n    \n        Starts server.js as a daemon passing script-options as command\n        line arguments.\n    \n        Each worker's stdout and stderr are redirected to a log files\n        specified by the `stdout` and `stderr` parameters. When a log file\n        becomes larger than `max-log-size`, the log file is renamed using the\n        current date and time, and a new log file is opened.\n    \n        With naught, you can use `console.log` and friends. Because naught\n        pipes the output into a log file, node.js treats stdout and stderr\n        as asynchronous streams.\n    \n        If you don't want a particular log, use `/dev/null` for the path. Naught\n        special cases this filename and disables that log altogether.\n    \n        When running in `daemon-mode` `false`, naught will start the master\n        process and then block. It listens to SIGHUP for restarting and SIGTERM\n        for stopping. In this situation you may use `-` for `stderr` and/or\n        `stdout` which will redirect the respective streams to naught's output\n        streams instead of a log file.\n    \n        Creates an `ipc-file` which naught uses to communicate with your\n        server once it has started.\n    \n        Available options and their defaults:\n    \n        --worker-count 1\n        --ipc-file naught.ipc\n        --pid-file naught.pid\n        --log naught.log\n        --stdout stdout.log\n        --stderr stderr.log\n        --max-log-size 10485760\n        --cwd .\n        --daemon-mode true\n        --remove-old-ipc false\n        --node-args ''\n    \n    \n    naught stop [options] [ipc-file]\n    \n        Stops the running server which created `ipc-file`.\n        Uses `naught.ipc` by default.\n    \n        This sends the 'shutdown' message to all the workers and waits for\n        them to exit gracefully.\n    \n        If you specify a timeout, naught will forcefully kill your workers\n        if they do not shut down gracefully within the timeout.\n    \n        Available options and their defaults:\n    \n            --timeout none\n            --pid-file naught.pid\n    \n    \n    naught status [ipc-file]\n    \n        Displays whether a server is running or not.\n        Uses `naught.ipc` by default.\n    \n    \n    naught deploy [options] [ipc-file]\n    \n        Replaces workers with new workers using new code and optionally\n        the environment variables from this command.\n    \n        Naught spawns all the new workers and waits for them to all become\n        online before killing a single old worker. This guarantees zero\n        downtime if any of the new workers fail and provides the ability to\n        cleanly abort the deployment if it hangs.\n    \n        A hanging deploy happens when a new worker fails to emit the 'online'\n        message, or when an old worker fails to shutdown upon receiving the\n        'shutdown' message. A keyboard interrupt will cause a deploy-abort,\n        cleanly and with zero downtime.\n    \n        If `timeout` is specified, naught will automatically abort the deploy\n        if it does not finish within those seconds.\n    \n        If `override-env` is true, the environment varibables that are set with\n        this command are used to override the original environment variables\n        used with the `start` command. If any variables are missing, the\n        original values are left intact.\n    \n        `worker-count` can be used to change the number of workers running. A\n        value of `0` means to keep the same number of workers.\n        A value of 'auto', will set value as per the number of available CPUs.\n    \n        `cwd` can be used to change the cwd directory of the master process.\n        This allows you to release in different directories. Unfortunately,\n        this option doesn't update the script location. For example, if you\n        start naught `naught start --cwd /release/1 server.js` and deploy\n        `naught deploy --cwd /release/2` the script file will not change from\n        '/release/1/server.js' to '/release/2/server.js'. You have to create\n        a symlink and pass the full symlink path to naught start\n        '/current/server.js'. After creating the symlink naught starts the\n        correct script, but the cwd is still old and require loads files from\n        from the old directory. The cwd option allows you to update the cwd\n        to the new directory. It defaults to naught's cwd.\n    \n        Uses `naught.ipc` by default.\n    \n        Available options and their defaults:\n    \n            --worker-count 0\n            --override-env true\n            --timeout none\n            --cwd .\n    \n    \n    naught deploy-abort [ipc-file]\n    \n        Aborts a hanging deploy. A hanging deploy happens when a new worker\n        fails to emit the 'online' message, or when an old worker fails\n        to shutdown upon receiving the 'shutdown' message.\n    \n        When deploying, a keyboard interrupt will cause a deploy-abort,\n        so the times you actually have to run this command will be few and\n        far between.\n    \n        Uses `naught.ipc` by default.\n    \n    \n    naught version\n    \n        Prints the version of naught and exits.\n    \n    \n    naught help [cmd]\n    \n        Displays help for cmd.\n","funding_links":[],"categories":["Packages","Number"],"sub_categories":["Process management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewrk%2Fnaught","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewrk%2Fnaught","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewrk%2Fnaught/lists"}