From 39ed1a28c56bdf78a79d0e3c89470a239193407f Mon Sep 17 00:00:00 2001 From: DarthSim Date: Sat, 14 Jan 2017 21:53:41 +0600 Subject: [PATCH] Update README, tnx to @yaroslav --- README.md | 65 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 914a719..cc922c9 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,51 @@ [![Build Status](https://travis-ci.org/DarthSim/overmind.svg?branch=master)](https://travis-ci.org/DarthSim/overmind) -Overmind allows you to launch a number of processes in a single terminal using [tmux](https://tmux.github.io/) and Procfile. +Overmind 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. + +Procfile 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) or [here](http://docs.deis.io/en/latest/using_deis/process-types/). + +There 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, 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. Sponsored by Evil Martians -## The Overmind powers +## Overmind features -There are a lot of Procfile runners written in different languages, but Overmind has some superpowers, that the other runners don't: +You may know several Procfile process management tools, but Overmind has some unique, _extraterrestrial_ powers others don't: -* Overmind starts processes in a tmux session, so you can connect to a process and get control over it; -* Overmind can restart processes on a fly, so you don't need to restart a whole stack; -* Overmind allows specified processes to die without interrupting all other ones; -* Overmind uses pty to capture processes output, so it won't be cut, delayed, and colors will remain the same; -* Overmind reads environment variables from a file and uses them as params, so you can configure Overmind's behavior globally and/or per directory. +* Overmind starts processes in a tmux session, so you can easily connect to any process and gain control over it; +* Overmind can restart a single process on the fly — you don't need to restart the whole stack; +* Overmind allows a specified process to die without interrupting all of the other ones; +* Overmind uses `pty` to capture process output — so it won't be clipped, delayed, and it won't break colored output; +* 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. -_Don't need all this powers? You may be interested in the Overmind's little sister - [Hivemind](https://github.com/DarthSim/hivemind)_ +**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)!** -![Overmind screenshot](http://img.darthsim.me/overmind.png) +![Overmind screenshot](http://i.imgur.com/lfrFKMf.png) ## Installation -_Because of using pty and tmux, Overmind doesn't support Windows._ +**Note:** Because Overmind relies on `pty` and `tmux`, it doesn't support Windows. Overmind works with [tmux](https://tmux.github.io/), so you need to install it first: ```bash +# on macOS (with homebrew) +$ brew install tmux + # on Ubuntu $ apt-get install tmux -# on Mac OS X (with homebrew) -$ brew install tmux ``` -__Note:__ You can find installation manual for other systems here: https://github.com/tmux/tmux +**Note:** You can find installation manual for other systems here: https://github.com/tmux/tmux -There are two ways to install Overmind itself: +There are two ways to install Overmind: -### Download the last Overmind release binary +### Download the latest Overmind release binary -You can download the last release [here](https://github.com/DarthSim/overmind/releases/latest). +You can download the latest release [here](https://github.com/DarthSim/overmind/releases/latest). ### Build Overmind from source @@ -51,15 +56,15 @@ You need Go 1.6 or later to build the project. $ go get -u -f github.com/DarthSim/overmind ``` -__Note:__ You can update Overmind the same way. +**Note:** You can update Overmind the same way. ## Usage -**TL;DR:** You can get help by running `overmind -h` and `overmind help [command]`. +**In short:** You can get help by running `overmind -h` and `overmind help [command]`. ### Running processes -Overmind reads the processes you want to run from a Procfile, that looks like this: +Overmind reads the list of processes you want to manage from a file named `Procfile`. It may look like this: ```Procfile web: bin/rails server @@ -67,7 +72,7 @@ worker: bundle exec sidekiq assets: gulp watch ``` -To get started, you just need to run Overmind from your working directory containing a Procfile. +To get started, you just need to run Overmind from your working directory containing a `Procfile`: ```bash $ overmind start @@ -81,16 +86,16 @@ $ overmind s #### Specifying a Procfile -If a Procfile isn't located in your working directory, you can specify it: +If a `Procfile` isn't located in your working directory, you can specify the exact path: ```bash $ overmind start -f path/to/your/Procfile $ OVERMIND_PROCFILE=path/to/your/Procfile overmind start ``` -#### Running only specified processes +#### Running only the specified processes -You can specify the names of the processes you want to run: +You can specify the names of processes you want to run: ```bash $ overmind start -l web,sidekiq @@ -99,7 +104,7 @@ $ OVERMIND_PROCESSES=web,sidekiq overmind start #### Processes that can die -Normally when some process dies, Overmind interrupts all other processes. But you can specify processes, that can die without interrupting all other ones: +Usually, when a process dies, Overmind will interrupt all other processes. However, you can specify processes that can die without interrupting all other ones: ```bash $ overmind start -c assets,npm_install @@ -108,7 +113,7 @@ $ OVERMIND_CAN_DIE=assets,npm_install overmind start ### Connecting to a process -If you need to get access to a process input, you can connect to it's tmux window: +If you need to gain access to process input, you can connect to its `tmux` window: ```bash $ overmind connect [process_name] @@ -116,13 +121,13 @@ $ overmind connect [process_name] ### Restarting a process -You can restart a single process without restarting the other ones: +You can restart a single process without restarting all the other ones: ```bash $ overmind restart sidekiq ``` -You can restart multiple process the same way: +You can restart multiple processes the same way: ```bash $ overmind restart sidekiq assets @@ -138,7 +143,7 @@ $ overmind kill ### Overmind environment -If you need to set specific environment variables before running a Procfile, you can specify them in `.overmind.env` in the current working directory and/or your home directory. The file should contain variable=value pairs one by line: +If 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 and/or your home directory. The file should contain `variable=value` pairs, one per line: ``` PATH=$PATH:/additional/path @@ -148,7 +153,7 @@ OVERMIND_PORT_BASE=3000 ### Specifying a socket -Overmind receives commands via a unix socket. Normally it opens a socket named `.overmind.sock` in a working directory, but you can specify it: +Overmind 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: ```bash $ overmind start -s path/to/socket