{"id":13509289,"url":"https://github.com/DarthSim/overmind","last_synced_at":"2025-03-30T13:31:54.838Z","repository":{"id":40989730,"uuid":"77292025","full_name":"DarthSim/overmind","owner":"DarthSim","description":"Process manager for Procfile-based applications and tmux","archived":false,"fork":false,"pushed_at":"2025-03-12T14:31:55.000Z","size":2190,"stargazers_count":3054,"open_issues_count":43,"forks_count":83,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-27T06:00:17.544Z","etag":null,"topics":["procfile"],"latest_commit_sha":null,"homepage":"","language":"Go","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/DarthSim.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}},"created_at":"2016-12-24T16:47:07.000Z","updated_at":"2025-03-26T21:07:07.000Z","dependencies_parsed_at":"2024-06-18T17:10:46.361Z","dependency_job_id":"6dae7c1b-aa7e-42fc-8118-e8845910ee97","html_url":"https://github.com/DarthSim/overmind","commit_stats":{"total_commits":221,"total_committers":30,"mean_commits":7.366666666666666,"dds":"0.16289592760180993","last_synced_commit":"1f96fb0073b8cc8fb51734ebc7d76f7abcaf2fcd"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarthSim%2Fovermind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarthSim%2Fovermind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarthSim%2Fovermind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarthSim%2Fovermind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DarthSim","download_url":"https://codeload.github.com/DarthSim/overmind/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246323947,"owners_count":20759054,"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":["procfile"],"created_at":"2024-08-01T02:01:05.734Z","updated_at":"2025-03-30T13:31:54.819Z","avatar_url":"https://github.com/DarthSim.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"logo-dark.svg\" /\u003e\n    \u003cimg src=\"logo.svg\" alt=\"Overmind\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/DarthSim/overmind/releases/latest\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/release/DarthSim/overmind.svg?style=for-the-badge\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/DarthSim/overmind/actions\"\u003e\u003cimg alt=\"GH Build\" src=\"https://img.shields.io/github/actions/workflow/status/DarthSim/overmind/build.yml?branch=master\u0026label=Build\u0026style=for-the-badge\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/DarthSim/overmind/actions\"\u003e\u003cimg alt=\"GH Lint\" src=\"https://img.shields.io/github/actions/workflow/status/DarthSim/overmind/lint.yml?branch=master\u0026label=Lint\u0026style=for-the-badge\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nOvermind is a process manager for Procfile-based applications and [tmux](https://tmux.github.io/). With Overmind, you can easily run several processes from your `Procfile` in a single terminal.\n\nProcfile is a simple format to specify types of processes your application provides (such as web application server, background queue process, front-end builder) and commands to run those processes. It can significantly simplify process management for developers and is used by popular hosting platforms, such as Heroku and Deis. You can learn more about the `Procfile` format [here](https://devcenter.heroku.com/articles/procfile).\n\nThere are some good Procfile-based process management tools, including [foreman](https://github.com/ddollar/foreman) by David Dollar, which started it all. The problem with most of those tools is that processes you want to manage start to think they are logging their output into a file, and that can lead to all sorts of problems: severe lagging, and losing or breaking colored output. Tools can also add vanity information (unneeded timestamps in logs). Overmind was created to fix those problems once and for all.\n\nSee this article for a good intro and all the juicy details! [Introducing\nOvermind and Hivemind](https://evilmartians.com/chronicles/introducing-overmind-and-hivemind)\n\n\u003ca href=\"https://evilmartians.com/?utm_source=opensource\"\u003e\n  \u003cpicture\u003e\n    \u003csource\n      media=\"(prefers-color-scheme: dark)\"\n      srcset=\"https://evilmartians.com/badges/sponsored-by-evil-martians_v2.0_for-dark-bg@2x.png\"\n    \u003e\n    \u003cimg\n      src=\"https://evilmartians.com/badges/sponsored-by-evil-martians_v2.0@2x.png\"\n      alt=\"Sponsored by Evil Martians\"\n      width=\"236\"\n      height=\"54\"\n    \u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n## Overmind features\n\nYou may know several Procfile process management tools, but Overmind has some unique, _extraterrestrial_ powers others don't:\n\n* Overmind starts processes in a tmux session, so you can easily connect to any process and gain control over it;\n* Overmind can restart a single process on the fly — you don't need to restart the whole stack;\n* Overmind allows a specified process to die without interrupting all of the other ones;\n* Overmind can restart specified processes automatically when they die;\n* Overmind uses tmux's control mode to capture process output — so it won't be clipped, delayed, and it won't break colored output;\n* Overmind can read environment variables from a file and use them as parameters so that you can configure Overmind behavior globally and/or per directory.\n\n**If a lot of those features seem like overkill for you, especially the tmux integration, you should take a look at Overmind's little sister — [Hivemind](https://github.com/DarthSim/hivemind)!**\n\n![Overmind screenshot](http://i.imgur.com/lfrFKMf.png)\n\n## Installation\n\n**Note:** At the moment, Overmind supports Linux, *BSD, and macOS only.\n\nOvermind works with [tmux](https://tmux.github.io/), so you need to install it first:\n\n```bash\n# on macOS (with homebrew)\n$ brew install tmux\n\n# on Ubuntu\n$ apt-get install tmux\n```\n\n**Note:** You can find installation manuals for other systems here: https://github.com/tmux/tmux\n\nThere are three ways to install Overmind:\n\n### With Homebrew (macOS)\n\n```bash\nbrew install overmind\n```\n\n### With Ruby\n\n```bash\ngem install overmind\n```\n\nYou can read about installing on Ruby On Rails [here] (https://github.com/DarthSim/overmind/blob/master/packaging/rubygems/README.md)\n\n### Download the latest Overmind release binary\n\nYou can download the latest release [here](https://github.com/DarthSim/overmind/releases/latest).\n\n### Build Overmind from source\n\nYou need Go 1.21 or later to build the project.\n\n```bash\n$ go install github.com/DarthSim/overmind/v2@latest\n```\n\nThe Overmind binary will be installed to `$(go env GOPATH)/bin`. Make sure that you added it to your `PATH`.\n\n**Note:** You can update Overmind the same way.\n\n## Usage\n\n**In short:** You can get help by running `overmind -h` and `overmind help [command]`.\n\n### Running processes\n\nOvermind reads the list of processes you want to manage from a file named `Procfile`. It may look like this:\n\n```Procfile\nweb: bin/rails server\nworker: bundle exec sidekiq\nassets: gulp watch\n```\n\nTo get started, you just need to run Overmind from your working directory containing a `Procfile`:\n\n```bash\n$ overmind start\n```\n\nYou can also use the short alias:\n\n```bash\n$ overmind s\n```\n\n#### Specifying a Procfile\n\nIf a `Procfile` isn't located in your working directory, you can specify the exact path:\n\n```bash\n$ overmind start -f path/to/your/Procfile\n$ OVERMIND_PROCFILE=path/to/your/Procfile overmind start\n```\n\n#### Specifying the ports\n\nOvermind sets the environment variable `PORT` for each process in your Procfile so that you can do things like this:\n\n```Procfile\nweb: bin/rails server -p $PORT\n```\n\nOvermind assigns the port base (5000 by default) to `PORT` for the first process and increases `PORT` by port step (100 by default) for each subsequent one. You can specify the port base and port step like this:\n\n```bash\n$ overmind start -p 3000 -P 10\n$ OVERMIND_PORT=3000 OVERMIND_PORT_STEP=10 overmind start\n```\n\n#### Disabling `PORT`\n\nIf you don't want Overmind to set the `PORT` variable, you can disable it:\n\n```bash\n$ overmind start -N\n$ OVERMIND_NO_PORT=1 overmind start\n```\n\n#### Referencing the ports of other processes\n\nIf overmind is specifying a port, each other process will be provided with environment variables that include them. Those variables will be have the format `OVERMIND_PROCESS_\u003cname\u003e_PORT` where \"name\" is the name of the process from the procfile, with any characters that are invalid in an environment variable replaced with `_`.\n\nIf processes are scaled, those port names will be numbered as well, based on the scaling of the process.\n\n```Procfile\nweb: bin/rails server -p $PORT\nproxy: ngrok http --subdomain overmind $OVERMIND_PROCESS_web_PORT\n```\n\n#### Running only the specified processes\n\nYou can specify the names of processes you want to run:\n\n```bash\n$ overmind start -l web,sidekiq\n$ OVERMIND_PROCESSES=web,sidekiq overmind start\n```\n\n#### Not running the specified processes\n\nSimilar to the above, if there are some processes in the Procfile that you do not want to run:\n\n```bash\n$ overmind start -x web,sidekiq\n$ OVERMIND_IGNORED_PROCESSES=web,sidekiq overmind start\n```\n\nThis takes precedence over the previous `-l` flag. i.e. if you:\n\n```bash\n$ overmind start -l web -x web\n$ OVERMIND_IGNORED_PROCESSES=web OVERMIND_PROCESSES=web overmind start\n```\n\nNothing will start.\n\n#### Scaling processes (formation)\n\nBy default, Overmind starts one instance of each process, but you can set the number of each process instances to run:\n\n```bash\n$ overmind start -m web=2,worker=5\n$ OVERMIND_FORMATION=web=2,worker=5 overmind start\n```\n\nThere is a special name `all` that you can use to scale all processes at once:\n\n```bash\n$ overmind start -m all=2,worker=5\n$ OVERMIND_FORMATION=all=2,worker=5 overmind start\n```\n\nIf you set instances number of some process to zero, this process won't be run:\n\n```bash\n$ overmind start -m some_production_task=0\n$ OVERMIND_FORMATION=some_production_task=0 overmind start\n```\n\n#### Processes that can die\n\nUsually, when a process dies, Overmind will interrupt all other processes. However, you can specify processes that can die without interrupting all other ones:\n\n```bash\n$ overmind start -c assets,npm_install\n$ OVERMIND_CAN_DIE=assets,npm_install overmind start\n```\n\nAlso, you can allow all processes to die:\n\n```bash\n$ overmind start --any-can-die\n$ OVERMIND_ANY_CAN_DIE=1 overmind start\n```\n\n#### Auto-restarting processes\n\nIf some of your processes tend to randomly crash, you can tell Overmind to restart them automatically when they die:\n\n```bash\n$ overmind start -r rails,webpack\n$ OVERMIND_AUTO_RESTART=rails,webpack overmind start\n```\n\nThe special name `all` can also be used to restart all processes automatically when they die:\n\n```bash\n$ overmind start -r all\n$ OVERMIND_AUTO_RESTART=all overmind start\n```\n\n\u003e [!NOTE] \n\u003e `OVERMIND_CAN_DIE` supersedes `OVERMIND_AUTO_RESTART`; if you want a restarting process, only put it in `OVERMIND_AUTO_RESTART` \n\n#### Specifying the colors\n\nOvermind colorizes process names with different colors. It may happen that these colors don't match well with your color scheme. In that case, you can specify your own colors using xterm color codes:\n\n```bash\n$ overmind start -b 123,123,125,126,127\n$ OVERMIND_COLORS=123,123,125,126,127 overmind start\n```\n\nIf you want Overmind to always use these colors, you can specify them in the [environment file](https://github.com/DarthSim/overmind#overmind-environment) located in your home directory.\n\n### Show timestamps\n\nBy default, Overmind doesn't show timestamps in its output since it expects your processes to add timestamps to their own output. But you can make Overmind to add timestamps to its output:\n\n```bash\n$ overmind start -T\n$ OVERMIND_SHOW_TIMESTAMPS=1 overmind start\n```\n\n### Connecting to a process\n\nIf you need to gain access to process input, you can connect to its `tmux` window:\n\n```bash\n$ overmind connect \u003cprocess_name\u003e\n```\n\nYou can safely disconnect from the window by hitting `Ctrl b` (or your tmux prefix) and then `d`.\n\nYou can omit the process name to connect to the first process defined in the Procfile.\n\n### Restarting a process\n\nYou can restart a single process without restarting all the other ones:\n\n```bash\n$ overmind restart sidekiq\n```\n\nYou can restart multiple processes the same way:\n\n```bash\n$ overmind restart sidekiq assets\n```\n\nIt's also possible to use wildcarded process names:\n\n```bash\n$ overmind restart 'sidekiq*'\n```\n\nWhen the command is called without any arguments, it will restart all the processes.\n\n### Stopping a process\n\nYou can stop a single process without stopping all the other ones:\n\n```bash\n$ overmind stop sidekiq\n```\n\nYou can stop multiple processes the same way:\n\n```bash\n$ overmind stop sidekiq assets\n```\n\nIt's also possible to use wildcarded process names:\n\n```bash\n$ overmind stop 'sidekiq*'\n```\n\nWhen the command is called without any arguments, it will stop all the processes without stopping Overmind itself.\n\n### Killing processes\n\nIf something goes wrong, you can kill all running processes:\n\n```bash\n$ overmind kill\n```\n\n### Overmind environment\n\nIf you need to set specific environment variables before running a `Procfile`, you can specify them in the `.overmind.env` file in the current working directory, your home directory, or/and in the `.env` file in in the current working directory. The file should contain `variable=value` pairs, one per line:\n\n```\nPATH=$PATH:/additional/path\nOVERMIND_CAN_DIE=npm_install\nOVERMIND_PORT=3000\n```\n\nFor example, if you want to use a separate `Procfile.dev` by default on a local environment, create `.overmind.env` file with `OVERMIND_PROCFILE=Procfile.dev`. Now, Overmind uses `Procfile.dev` by default.\n\nYou can specify additional env files to load with `OVERMIND_ENV` variable:\n\n```bash\n$ OVERMIND_ENV=./.env.local,./.env.development overmind s\n```\n\nThe files will be loaded in the following order:\n\n* `~/.overmind.env`\n* `./.overmind.env`\n* `./.env`\n* `$OVERMIND_ENV`\n\nYou can also opt to skip loading the `.env` file entirely (`.overmind.env` will still be read) by setting the variable `OVERMIND_SKIP_ENV`.\n\n#### Running a command in the Overmind environment\n\nSince you set up an environment with `.env` files, you may want to run a command inside this environment. You can do this using `run` command:\n\n```bash\n$ overmind run yarn install\n```\n\n### Run as a daemon\n\nOvermind can be run as a daemon:\n\n```bash\n$ overmind start -D\n$ OVERMIND_DAEMONIZE=1 overmind start\n```\n\nUse the `echo` command for the logs:\n\n```bash\n$ overmind echo\n```\n\nYou can quit daemonized Overmind with `quit`:\n\n```bash\n$ overmind quit\n```\n\n### Specifying a socket\n\nOvermind receives commands via a Unix socket. Usually, it opens a socket named `.overmind.sock` in a working directory, but you can specify the full path:\n\n```bash\n$ overmind start -s path/to/socket\n$ OVERMIND_SOCKET=path/to/socket overmind start\n```\n\nAll other commands support the same flag:\n\n```bash\n$ overmind connect -s path/to/socket web\n$ overmind restart -s path/to/socket sidekiq\n$ overmind kill -s path/to/socket\n```\n\n#### Using TCP network\n\nOvermind can bind its command center to a TCP address instead of Unix socket. This is useful when you run it on a remote machine.\n\n```bash\n$ overmind start -s \"0.0.0.0:4321\" -S \"tcp\"\n$ OVERMIND_SOCKET=\"0.0.0.0:4321\" OVERMIND_NETWORK=\"tcp\" overmind start\n```\n\nYou need to pass the same flags to other commands:\n\n```bash\n$ overmind connect -s \"0.0.0.0:4321\" -S \"tcp\" web\n```\n\n### Specifying tmux config\n\nOvermind can use a specified tmux config. This is useful if you want to differentiate from your main tmux window, for example adding a custom status line for Overmind or a different prefix key.\n\n```bash\novermind start -F ~/overmind.tmux.conf\nOVERMIND_TMUX_CONFIG=~/.overmind.tmux.conf overmind start\n```\n\n## Known issues\n\n### Overmind uses the system Ruby/Node/etc instead of a custom-defined one\n\nThis may happen if your Ruby/Node/etc version manager isn't configured properly. Make sure that the path to your custom binaries is included in your `PATH` before the system binaries path.\n\n### Overmind does not stop the Docker process properly\n\nUnfortunately, this is how Docker works. When you send `SIGINT` to a `docker run ...` process, it just detaches container and exits. You can solve this by using named containers and signal traps:\n\n```procfile\nmydocker: trap 'docker stop mydocker' EXIT \u003e /dev/null; docker run --name mydocker ...\n```\n\n### Overmind can't start because of a `bind: invalid argument` error\n\nAll operating systems have limits on Unix socket path length. Try to use a shorter socket path.\n\n### Overmind exits after `pg_ctl --wait start` and keeps PostgreSQL server running\n\nSince version 12.0 `pg_ctl --wait start` exits right after starting the server. Just use the `postgres` command directly.\n\n## Author\n\nSergey \"DarthSim\" Aleksandrovich\n\nHighly inspired by [Foreman](https://github.com/ddollar/foreman).\n\nMany thanks to @antiflasher for the awesome logo.\n\n## License\n\nOvermind is licensed under the MIT license.\n\nSee LICENSE for the full license text.\n","funding_links":[],"categories":["Process Manager","Go","\u003e 1k ★","others"],"sub_categories":["Procfile"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDarthSim%2Fovermind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDarthSim%2Fovermind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDarthSim%2Fovermind/lists"}