{"id":13517239,"url":"https://github.com/strongloop/node-foreman","last_synced_at":"2025-05-14T05:12:03.966Z","repository":{"id":5148108,"uuid":"6315537","full_name":"strongloop/node-foreman","owner":"strongloop","description":"A Node.js Version of Foreman","archived":false,"fork":false,"pushed_at":"2024-08-19T05:59:49.000Z","size":1070,"stargazers_count":1274,"open_issues_count":12,"forks_count":117,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-05-03T01:44:19.454Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://strongloop.github.io/node-foreman/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jlord/sheetsee.js","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strongloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-10-21T01:06:00.000Z","updated_at":"2025-04-24T19:43:05.000Z","dependencies_parsed_at":"2024-11-19T00:07:09.026Z","dependency_job_id":"45f7fdce-fd2f-4250-bb2f-4f80b8e30ac4","html_url":"https://github.com/strongloop/node-foreman","commit_stats":{"total_commits":325,"total_committers":33,"mean_commits":9.848484848484848,"dds":0.5507692307692308,"last_synced_commit":"782cf090d4917ff137e9980a36803b93df818b96"},"previous_names":["nodefly/node-foreman"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fnode-foreman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fnode-foreman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fnode-foreman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fnode-foreman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strongloop","download_url":"https://codeload.github.com/strongloop/node-foreman/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252550556,"owners_count":21766571,"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-08-01T05:01:31.513Z","updated_at":"2025-05-14T05:11:58.952Z","avatar_url":"https://github.com/strongloop.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"# Node Foreman [![Build Status](https://travis-ci.org/strongloop/node-foreman.svg)](https://travis-ci.org/strongloop/node-foreman)\n\nNode Foreman is a Node.js version of the popular\n[Foreman](http://ddollar.github.com/foreman/) tool,\nwith a few Node specific changes.\n\n\u003e Foreman is a manager for Procfile-based applications.\n\u003e Its aim is to abstract away the details of the Procfile\n\u003e format, and allow you to either run your application\n\u003e directly or export it to some other process management format.\n\n## Install\n\nInstall the command line tool\n\n    npm install -g foreman\n\nGet usage\n\n    nf --help\n\n## Deviations from the original Foreman\n\n* Each worker has an additional automatic environment variable,\n  `FOREMAN_WORKER_NAME`, that contains the process name and worker number.\n  * example: `web.1`, `worker.1`\n\n### How to Contribute\n\nI encourage anyone and everyone to help.\nIf you have a specific change in mind, open an issue; we can talk about it there.\n\nIf you would like to make a code change, go ahead.\nFork the repository, open a pull request.\nDo this early, and talk about the change you want to make.\nMaybe we can work together on it.\n\nRefactor Refactor Refactor!\nYou are free to add features, or just help clean things up.\n\n## Usage\n\nNode Foreman can be run with as little as `nf start`, as long as `npm start` has been defined.\nFor more complicated applications you will want to define a `Procfile` for your various server\nprocesses and an `.env` file to pre-load environmental variables.\n\nYour module directory should end up looking like the following:\n\n![List Foreman Directory](https://raw.github.com/strongloop/node-foreman/master/assets/foreman-ls.png)\n\nOnce your `Procfile` is defined, run your application with `nf start`:\n\n![Start Foreman](https://raw.github.com/strongloop/node-foreman/master/assets/foreman-start.png)\n\nNode Foreman _always_ starts in the foreground and expects your applications\nto do the same. If your processes exit, Node Foreman will assume an error\nhas occurred and shut your application down.\n\nInstead of daemonizing, you should use `nf export` to ready your application\nfor production.\n\nFor more information try any of the following:\n\n\t$ nf --help\n\t$ nf start --help\n\t$ nf run --help\n\t$ nf export --help\n\n### Procfile\n\nThe `Procfile` format is a simple `key : command` format:\n\n    web: node web_server.js\n    api: node api_server.js\n    log: node log_server.js\n\nEach line should contain a separate process.\n\n### Environmental Variables\n\nCreate a `.env` file to pre-load environmental variables with the format:\n\n    MYSQL_NAME=superman\n    MYSQL_PASS=cryptonite\n\nThe equivalent `.env` file may alternatively be a valid JSON document:\n\n    {\n        \"mysql\":{\n            \"name\": \"superman\",\n            \"pass\": \"cryptonite\"\n        }\n    }\n\nThe above JSON document will be flattened into env variables by\nconcatenating the nested values with an underscore.\nEnvironmental variables are passed in fully capitalized.\n\n    {\n        \"mysql\":{\n            \"name\": \"superman\",     # =\u003e MYSQL_NAME=superman\n            \"pass\": \"cryptonite\"    # =\u003e MYSQL_PASS=cryptonite\n        }\n    }\n\nThere is no need to specify which type of file you wish to use.\n\n#### The PATH environment variable\n\nThe `PATH` variable is given special treatment and is always read\nfrom the environment that the `nf` command has been executed from,\nrather than your `.env` file.  To set a different `PATH` execute\n`nf` with the `PATH` variable set appropriately.\n\n```bash\nPATH=/opt/foo:/opt/bar:$PATH nf export\n```\n\n#### Best Practices\n\nGenerally you should not check your `.env` file into version control.\nThe `.env` file contain _only_ parameters that depend on where the application\ngets deployed. It should not contain anything related to _how_ the application\nis deployed.\n\nFor example, good candidates for the `.env` file are MySQL connection information,\nport bindings, and other passwords.\n\n### The Run Command\n\nTasks or commands that require the environment variables from the `.env` file\ncan be initiated by using `nf run \u003ccommand\u003e`.\n\n### Advanced Usage\n\nNode Foreman lets you start multiple jobs of the same type:\n\n    $ nf start web=5\n\n    18:51:12: web.1     |  Web Server started listening on 0.0.0.0:5000\n    18:51:12: web.2     |  Web Server started listening on 0.0.0.0:5001\n    18:51:12: web.3     |  Web Server started listening on 0.0.0.0:5002\n    18:51:12: web.4     |  Web Server started listening on 0.0.0.0:5003\n    18:51:12: web.5     |  Web Server started listening on 0.0.0.0:5004\n\nEach job will be started as its own process, receiving a different `PORT`\nenvironmental variable.\nThe port number for processes of the same type will be offset by 1.\nThe port number for processes of different types will be offset by 100.\n\n    $ nf start web=2,api=2\n\n    18:51:12: web.1     |  Web Server started listening on 0.0.0.0:5000\n    18:51:12: web.2     |  Web Server started listening on 0.0.0.0:5001\n    18:51:12: api.1     |  Api Server started listening on 0.0.0.0:5100\n    18:51:12: api.2     |  Api Server started listening on 0.0.0.0:5101\n\n## Export to Production\n\nNode Foreman is designed to be in a development environment,\nhowever it can export an Upstart job for use in production.\nThe Upstart file has _no_ dependency on Node Foreman.\n\n    $ nf export\n    Loaded ENV .env File as JSON Format\n    Wrote  :  ./foreman-web-1.conf\n    Wrote  :  ./foreman-web.conf\n    Wrote  :  ./foreman-api-1.conf\n    Wrote  :  ./foreman-api.conf\n    Wrote  :  ./foreman-log-1.conf\n    Wrote  :  ./foreman-log.conf\n    Wrote  :  ./foreman.conf\n\nYou can inspect your upstart files before placing them in the right\ndirectory, or have foreman do it for you:\n\n    $ sudo nf export -o /etc/init\n    Loaded ENV .env File as JSON Format\n    Wrote  :  /etc/init/foreman-api-1.conf\n    Wrote  :  /etc/init/foreman-web.conf\n    Wrote  :  /etc/init/foreman-api.conf\n    Wrote  :  /etc/init/foreman-log.conf\n    Wrote  :  /etc/init/foreman-log-1.conf\n    Wrote  :  /etc/init/foreman-web-1.conf\n    Wrote  :  /etc/init/foreman.conf\n\nStart and stop your jobs with\n\n    $ sudo start foreman\n    Starting foreman... ok\n    $ sudo stop foreman\n\nThe export will occur with whatever environmental variables are\nlisted in the .env file.\n\n### systemd Support\n\n_This section is beta_\n\nOptionally specify a type `-t systemd` during export for [systemd](http://www.freedesktop.org/wiki/Software/systemd) support.\n\n### Supervisord Support\n\nYou can also use a type `-t supervisord` during export for [supervisord](http://www.supervisord.org) support.\n\nThis will generate a `APP.conf` file grouping the application processes and a `APP-PROCESS-N.conf` file for each process.\n\n    $ nf export --type supervisord\n    Loaded ENV .env File as JSON Format\n    Wrote  :  ./foreman-web-1.conf\n    Wrote  :  ./foreman-api-1.conf\n    Wrote  :  ./foreman-log-1.conf\n    Wrote  :  ./foreman.conf\n\nYou can start / stop / restart individual processes.\n\n    $ sudo supervisorctl start 'foreman:foreman-web-1'\n    $ sudo supervisorctl stop 'foreman:foreman-web-1'\n    $ sudo supervisorctl restart 'foreman:foreman-web-1'\n\nOr the entire group of processes\n\n    $ sudo supervisorctl start 'foreman:*'\n    $ sudo supervisorctl stop 'foreman:*'\n    $ sudo supervisorctl restart 'foreman:*'\n\n### Advanced Exports\n\nYou can specify the type and number of processes exported using\nthe `type=num` syntax:\n\n    $ nf export web=2,api=2\n\nUse `-u \u003cUSER\u003e` to have the exported job run as `USER`.\nNote that if you need to bind to privileged ports, you _must_\nstart as `root`. In such a case, we advise you to drop user\npermissions after binding.\n\nIf you want to call your upstart job something other than foreman,\nuse `-a \u003cJOBNAME\u003e` and manage your jobs with `sudo start \u003cJOBNAME\u003e`.\n\n## Reverse Proxy\n\nNode.js processes are supposed to be stateless.\nApplications scale by starting multiple processes that either share a socket,\nor sit behind a load balancer.\nNode Foreman can help you test the parallel capabilities of your application\nby spawning multiple processes behind a round-robin proxy.\n\n    $ nf start -x 8888 web=5\n    [OKAY] Starting Proxy Server 8888 -\u003e 5000-5004\n\nAccess your application from port `8888` and the connections will be balanced\nacross the servers started from ports `5000` - `5004`.\n\nIf your application gets its port number from `process.env.PORT` the proxy\nsetup will happen automatically.\n\n### Multiple Reverse Proxies\n\nIf you have multiple processes in your `Procfile` you can start multiple proxies.\n\n    $ nf start -x 8888,8080,9090\n\nThis will start 3 separate proxies and bind each to a separate process group.\nProxies are bound based on their order specified, their order in the Procfile,\nor by their order on the command line.\n\n    $ nf start -x 8888,9999 web,api\n\n### Privileged Ports\n\nNode Foreman disallows applications from starting on privileged ports.\nIt does however allow proxies to be bound to lower ports, such as port 80.\n\nIf you require access to a privileged port, start Node Foreman with `sudo`:\n\n    $ sudo nf start -x 80 web=5\n    [OKAY] Starting Proxy Server 80 -\u003e 5000-5004\n\nYour application will then be accessible via port 80, but it will be running as root.\n\n## Forward Proxy\n\nLocal development and testing has huge advantages,\nbut sometimes one needs to test web applications against their real-world domain name.\nEditing `/etc/hosts` is a pain however, and error prone.\n\nNode Foreman can start up an HTTP forward proxy which your browser can route requests through.\nThe forward proxy will intercept requests based on domain name, and route them to the local application.\n\n    $ nf start -f 9999 -i nodefly.com\n    [OKAY] Forward Proxy Started in Port 9999\n    [OKAY] Intercepting requests to nodefly.com through forward proxy\n\nA forward proxy is useful when testing OAuth, or other external services with application callbacks.\n\nFor users with Google Chrome, this can be paired with [FelisCatus SwitchyOmega](https://github.com/FelisCatus/SwitchyOmega) for great results.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Fnode-foreman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrongloop%2Fnode-foreman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Fnode-foreman/lists"}