Skip to content

Commit

Permalink
Update README, tnx to @yaroslav
Browse files Browse the repository at this point in the history
  • Loading branch information
DarthSim committed Jan 14, 2017
1 parent 6e6e61f commit 39ed1a2
Showing 1 changed file with 35 additions and 30 deletions.
65 changes: 35 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<a href="https://evilmartians.com/?utm_source=overmind">
<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
</a>

## 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 outputso 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

Expand All @@ -51,23 +56,23 @@ 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
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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -108,21 +113,21 @@ $ 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]
```

### 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
Expand All @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 39ed1a2

Please sign in to comment.