{"id":19969311,"url":"https://github.com/vmarchaud/servicectl","last_synced_at":"2025-10-12T04:10:35.453Z","repository":{"id":100263549,"uuid":"179763927","full_name":"vmarchaud/servicectl","owner":"vmarchaud","description":"Servicectl is a opinionated process manager that aim to simplify native init systems for developers.","archived":false,"fork":false,"pushed_at":"2020-11-24T08:24:32.000Z","size":255,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-04T01:31:55.842Z","etag":null,"topics":["init-system","launchd","manager","node","nodejs","process","process-manager","production","systemd"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmarchaud.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-04-05T22:42:54.000Z","updated_at":"2024-03-29T00:58:59.000Z","dependencies_parsed_at":"2023-05-13T06:45:29.374Z","dependency_job_id":null,"html_url":"https://github.com/vmarchaud/servicectl","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/vmarchaud/servicectl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmarchaud%2Fservicectl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmarchaud%2Fservicectl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmarchaud%2Fservicectl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmarchaud%2Fservicectl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmarchaud","download_url":"https://codeload.github.com/vmarchaud/servicectl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmarchaud%2Fservicectl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010249,"owners_count":26084718,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["init-system","launchd","manager","node","nodejs","process","process-manager","production","systemd"],"created_at":"2024-11-13T02:49:33.452Z","updated_at":"2025-10-12T04:10:35.448Z","avatar_url":"https://github.com/vmarchaud.png","language":"TypeScript","readme":"\n## Servicectl\n\nServicectl is a optionated process manager that aim to simplify native init systems for developers.\n\nCurrently it only support **linux** distribution with `systemd`, if you really need it to support **windows** or **macos** please open an issue. \n\n### Getting started\n\n```bash\n# Install the CLI first\nnpm install -g servicectl\n# or\nyarn global add servicectl\n\n# start your app\nsudo servicectl create myapp.js --name myapp\n# or with the cluster mode (see under for explaination) \nsudo servicectl create myapp.js --instances 2 --port 8080\n\n# get your logs\nservicectl logs myapp --lines 100\n\n# restart your app\nsudo servicectl restart myapp\n\n# see the status of your app\nservicectl status\n\n# remove the application from your system\nsudo servicectl delete myapp\n```\n\n\n## Why Yet Another Process Manager?\n\nI believe most process manager implementations focus on delivering a good experience for developers by re-implementing a daemon and a CLI from scratch (ex: pm2, forever, nodemon, supervisor).\n\nWhile it help for developers to run their apps, they generally are reinventing the wheel because popular OS already have a process manager builtin: [systemd](https://www.freedesktop.org/wiki/Software/systemd/) for most linux distributions, [launchd](https://www.launchd.info/) for macOS and [Service Control Manager](https://docs.microsoft.com/fr-fr/windows/win32/services/service-control-manager) for Windows.\n\nIn theory it should not be a problem but in practive you will often find bugs that doesn't exist in native init systems because they are generally older, well tested and handle a larger scope of use-case.\n\nAnoter argument would be that using the native init system cost less in terms of resources, embed environment like raspberry-pi like system are an example where it could help a lot.\n\n#### Why not use the native init system of my OS then?\n\nYou are right, in a perfect world this tool would be *almost* useless because everyone would be leveraging their already-present init systems. However the existence of simpler process manager means (in my opinion at least) that some people find them too difficult to use or configure.\n\nServicectl aim to help those people, people who aren't system administrator but still need to deploy their applications in production.\nHowever it can also help sysadmin since you can use native CLI (`systemctl` on linux for exemple) after starting the app with `servicectl`.\n\n#### If I use containers I don't see the point of using your tool!\n\nThat's because there are no point (*expect some rare cases (ex: coreos)*) of using init systems if you use containers. You should have a scheduler like `kubernetes`, `nomad` or `rancher` (etc.) to manage them. I have no plans to allow to manage them via `servicectl`.\n\n#### What servicectl is not:\n\n- A development process manager: I don't plan to support a `watch` mode for example or any feature that is not used in production.\n- A way to manage containers: as said above, you should be using more mature tools to do that.\n\n## Features\n\n### Start an application\n\nTo start an application, you need to use `servicectl create` which will register it to your init system:\n\n```bash\n# note that you must use sudo on linux\nsudo servicectl create app.js\n```\n\nThe configuration is **immutable** which means that to update it, you will need to delete the app and re-create it.\nTo see all the flag that you can use, use `servicectl create -h`.\nBy default the app will be launched in `exec` mode, which means it will only exist one instance of your app. If you want to launch different instances, use the `cluster` mode.\n\n#### Environment variables\n\nThe advised way to pass them is to have a `.env` file on your filesystem and to give it as argument with the flag `--env-file \u003cpath\u003e`.\nYou can also use `-e KEY=VALUE` or `--env KEY=VALUE` but again, a env file is generally better.\nIf you want to import your current shell environment into the application use `--import-env`.\n\n#### Permissions\n\nBy default the application will run with the same user as the one you are using to interact with the CLI, but can modify it using `--as=value`:\n- `--as=user`: default behavior, use the current user.\n- `--as=nobody`: best options, it will create a temporary user/group that got almost no permissions.\n- `--as=root`: really really not advised (please only use it if you know what you are doing) run the application as root.\n\n### Get a list of applications running\n\nDifferent aliases are available (ls, ps, status) will give you this ouput:\n```bash\nservicectl ps\n\nName   State  Mode    Uptime     CPU (%) Memory (MB) \nhttp@1 active cluster 7 sec. ago 0       7.66        \nhttp@0 active cluster 8 sec. ago 0       7.63 \n```\n\nYou also have different flag to sort, filter and format the list, please refer to `servicectl ps -h`.\nThe name also contains the number of the instance for a given app (in the format `\u003cname\u003e@\u003cnumber\u003e`) if you are using the cluster mode.\n\n### Cluster mode\n\nIf you used PM2 before, there is a mode called `cluster` which allows to automatically load balance requests to multiple instances of your app. You can do that with `servicectl` too:\n\n```bash\n# you need to specify the port that the application listen on\n# otherwise it will not work.\nservicectl create app.js --instances 2 --port 3000\n```\n\nLike PM2, the cluster mode is **supported out of the box using Node.js**. However you can use it anything, please read how to setup socket-enabled systemd service with your language (it's easy as listening on a specific file descriptor):\n- Go: https://github.com/coreos/go-systemd/blob/master/examples/activation/httpserver/httpserver.go\n- Python: https://github.com/liutec/python-systemd-socket-activated/blob/master/server.py#L13\n- Rails: https://www.stderr.nl/Blog/Software/Rails/RailsSocketActivation.html\n\nAfter changing your code to use the custom file descriptor, just launch your app like above and it should works.\n\nNote that if you are using the cluster mode, you can bind to port under 1000 (without having your app running as root).\n\n### Logs\n\nLog of each service are stored inside `/var/log/servicectl/` for linux, you can retrieve them using:\n```bash\n\n# fetch the 15th last lines\nservicectl logs \u003cname\u003e\n\n# follow new log\nservicectl logs \u003cname\u003e -f\n\n# get n last lines\nservicectl logs \u003cname\u003e -n count\n```\n\n### Restart \n\nYou can restart one or multiple applications like this:\n\n```bash\nservicectl restart \u003cname\u003e | all\n```\n\n### Delete \n\nAs said in the *Create* section, you need to delete your application to update its config, to do that you can use:\n```bash\n# note that you need to use sudo on linux\nsudo servicectl delete \u003cname\u003e | all\n```\n\n## API\n\n`servicectl` defines a common service definition as well as common init system API ([here](https://github.com/vmarchaud/servicectl/tree/master/src/types)) and implements them for each backend ([here](https://github.com/vmarchaud/servicectl/tree/master/src/backends/)).\nYou could totally use it as an API, I would advise to check how the CLI commands are interacting with it [here](https://github.com/vmarchaud/servicectl/tree/master/src/cli/)\n\nNote that the initial version of `servicectl` only includes support for `systemd`, if you need to use it on another init system please open an issue if your use-case.\n\n## Versioning\n\nThis library follows [Semantic Versioning](http://semver.org/).\n\nBefore the 1.0.0 release, any minor update can have breaking changes.\n\n## LICENSE\n\nApache License 2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmarchaud%2Fservicectl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmarchaud%2Fservicectl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmarchaud%2Fservicectl/lists"}