{"id":28629771,"url":"https://github.com/fibjs/fib-runner","last_synced_at":"2025-06-12T12:13:33.855Z","repository":{"id":57235130,"uuid":"398853042","full_name":"fibjs/fib-runner","owner":"fibjs","description":"process manager developed using fibjs","archived":false,"fork":false,"pushed_at":"2024-05-31T07:30:24.000Z","size":83,"stargazers_count":5,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-22T23:41:10.938Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fibjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-08-22T16:59:44.000Z","updated_at":"2024-05-31T07:30:28.000Z","dependencies_parsed_at":"2024-05-31T08:45:08.397Z","dependency_job_id":"c6851ce1-88ea-4149-9fda-d69ea65e8e0f","html_url":"https://github.com/fibjs/fib-runner","commit_stats":{"total_commits":71,"total_committers":2,"mean_commits":35.5,"dds":"0.014084507042253502","last_synced_commit":"27cf26292eeb997a36d36ecd820881e0f1389ad3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fibjs/fib-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fibjs","download_url":"https://codeload.github.com/fibjs/fib-runner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-runner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259462578,"owners_count":22861514,"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":"2025-06-12T12:13:33.151Z","updated_at":"2025-06-12T12:13:33.825Z","avatar_url":"https://github.com/fibjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# process manager developed using fibjs\nfib-runner is a process manager developed using fibjs, it runs in client/server mode, it allows the server to run in a secure user, keeps the processes safe and secure, allows the client to manage the processes, view the output logs of the processes and monitor the process resource usage.\n\n## Install\n\n```sh\nfibjs --install fib-runner [--save]\n```\n\n## Running runnerd\n\nExecute the following command:\n```sh\nfibjs runnerd\n```\nwill start the `runnerd` daemon. The daemon will run in the background and you can continue other work in the terminal or log out without suspending the daemon.\n\n## Run as a console\n\nRuns in console mode:\n```sh\nfibjs runnerd --console\n```\nWhen running in console mode, `runnerd` will enter the `runnerctl` console immediately after startup, and you can manipulate child processes from the console. This is useful when starting `runnerd` within docker.\n\n## Install runnerd as a service\n\nUsing `runnerctl`, `runnerd` can be installed as a system service and run automatically at system startup.\n```sh\nsudo fibjs runnerctl install\nsudo fibjs runnerctl uninstall\n```\n## Configuration File\n\nThe configuration file name is ``runner.json`` and needs to be stored in the current directory of the operating system when running `runnerd`. `runnerd` will automatically load the configuration file and start the specified process according to the configuration file.\n\nThe configuration file is a json formatted file that must contain an array of fields named `\"apps\"` that specify the configuration of the process.\n\nThe basic format of the configuration file is as follows:\n```JavaScript\n{\n    \"name\": \"fib-runner\",\n    \"description\": \"fibjs service runner\",\n    \"listen\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": 1123\n    },\n    \"apps\": [\n        {\n            \"name\": \"exec_name\",\n            \"exec\": \"/path/to/app\"\n        },\n        {\n            \"name\": \"script_name\",\n            \"script\": \"/path/to/app.js\"\n        },\n        {\n            \"name\": \"prj_name\",\n            \"runner\": \"/project/path/to\"\n        },\n    ]\n}\n```\n\nEach process is configured with the following parameters:\n| Name      | Description | Default |\n| ----------- | ----------- | --- |\n| name | process name | undefined |\n| description | description of the process | 'app_description' |\n| exec | exec file, `runnerd` will start the program directly | undefined |\n| script | script file, `runnerd` will use fibjs to start the script program | undefined |\n| runner | external runner folder, `runnerd` will load `runner.json` from this directory as a subproject | undefined |\n| cwd | the working directory when the process starts | undefined |\n| arg | the list of parameters when the process is started | [] |\n| env | the environment variables when the process starts | {} |\n| autostart | If true, this program will start automatically when `runnerd` is started. | true |\n| startsecs | Number of seconds between retries | 1 |\n| startretries | Number of consecutive failures allowed before abandonment, set to -1 for unlimited retries | 3 |\n| autorestart | Specify whether to automatically restart | true |\n| savelog | Automatically save logs when a process exits abnormally | false |\n| signal | SIGTERM, SIGHUP, SIGINT, SIGQUIT, SIGKILL, SIGUSR1, or SIGUSR2 | \"SIGTERM\" |\n\nThe simplest process configuration must contains at least `name` and one of `exec` and `script`. When both `exec` and `script` are specified, `runnerd` will ignore the `script` configuration.\n\n## Sub project\n\nBy configuring the property runner in `runner.json` , `runnerd` can manage external projects. For example, we have a runner project, which is stored under the directory `ext-app`, and the content of `runner.json` is as follows:\n```JavaScript\n{\n    \"apps\": [\n        {\n            \"name\": \"app5\",\n            \"script\": \"app5.js\"\n        }\n    ]\n}\n```\nIn the main `runner.json` configuration, add the sub project as follows:\n```JavaScript\n{\n    \"apps\": [\n        {\n            \"name\": \"ext\",\n            \"runner\": \"ext-app\"\n        }\n    ]\n}\n```\nAfter running `runnerd` we will get a process list like this:\n| (index)  |  pid  | status  | retries | uptime | user  |  sys  |   rss    |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n| ext.app5 | 50026 | RUNNING |    0    |  5.8s  | 0.02% | 0.01% | 28.41 MB |\n\n## Remote management\n\nBy default, `runnerd` does not allow remote control, and the control interface is bound to ip `127.0.0.1`. If you want to control the `runnerd` service remotely, you need to manually modify `runner.json` to enable remote management. \n\nstep 1, you need to allow external ip access control interface:\n```JavaScript\n{\n    \"listen\": {\n        \"address\": \"0.0.0.0\",\n        \"port\": 1123\n    }\n}\n```\nstep 2, check `runner.json` in an admin node to find your public key, if `runner.json` does not exist, you can run `runnerctl` to generate it automatically:\n```JavaScript\n{\n    \"key\": {\n        \"pub\": \"AmqJ_fkfQxKnuoG3-fkgNs51jVMj6oS9-XvPGw7Np4ZJ\",\n        \"key\": \"wHo9IdgYD-XattkLC8uj85T0G1a-ZPob0PELQVUv2aE\",\n        \"admin\": []\n    },\n}\n```\nstep 3, add your public key `\"AmqJ_fkfQxKnuoG3-fkgNs51jVMj6oS9-XvPGw7Np4ZJ\"` to the admin list of `runner.json` in the worker node::\n```JavaScript\n{\n    \"key\": {\n        \"pub\": \"A8Vw0C1U0nEkXLQBQ0GzC8WIPZyyt-UtNsVMvnMuSJaX\",\n        \"key\": \"6u3vfP8yRMgePxcDqPBZVNrOKD2iSAKKdN8SA6iKCXk\",\n        \"admin\": [\n            \"AmqJ_fkfQxKnuoG3-fkgNs51jVMj6oS9-XvPGw7Np4ZJ\"\n        ]\n    }\n}\n```\nNow you can control the `runnerd` service in the worker node from the admin node:\n```sh\nfibjs runnerctl -s ip:port\n```\n\n## Running runnerctl\n\nTo start `runnerctl`, run:\n```sh\nfibjs runnerctl [-s ip:port] [command] [...args]\n```\nA shell will be presented that will allow you to control the processes that are currently managed by `runnerd`. Type “help” at the prompt to get information about the `runnerd` commands. `runnerctl` supports the following commands:\n| Command      | Description |\n| ----------- | ----------- |\n| help              | Print this help message |\n| install           | Install runnerd as a service |\n| uninstall         | Uninstall runnerd service |\n| list              | Display all processes status |\n| reload            | Reload runner.json |\n| stop name         | Stop specific process name |\n| start name        | Start specific process name |\n| restart name      | Restart specific process name |\n| log name [80]     | Monitor output log of specific process name |\n| attach name [80]  | Attach output log of specific process name, ctrl+z to exit |\n| .{stat} name [1]  | Monitor {stat} statistics of specific process name\u003cbr\u003e{stat} will be rss, cpu, user, sys etc.  |\n| exit              | Exit runnerctl |\n\nThe `runnerctl` command can also be executed from the command line, such as:\n```sh\nfibjs runnerctl list\n```\n\n## Security control\n\nIn order to avoid security issues caused by illegal users using `runnerd` to elevate runtime privileges, only control and monitor operations are allowed in `runnerctl`, and there is no permission to modify or add processes. If you want to modify or add processes, you need to modify `runner.json` manually and reload the processes using the `reload` command. The administrator needs to ensure that `runner.json` is not allowed to be modified by anyone.\n\n## Unexpected exit log\n\nWhen the managed child process exits, if `runnerd` detects that this is an unexpected termination, it will automatically save the output of the child process to a log file named `log_${pid}.txt`.\n\n## Used as a module\n\nYou can also use `fib-runner` as a module, allowing more flexibility to customize process management to your needs by programming the `fib-runner` api directly.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffibjs%2Ffib-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffibjs%2Ffib-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffibjs%2Ffib-runner/lists"}