README.md
1# Serf
2
3* Website: http://www.serfdom.io
4* IRC: `#serfdom` on Freenode
5* Mailing list: [Google Groups](https://groups.google.com/group/serfdom/)
6
7Serf is a decentralized solution for service discovery and orchestration
8that is lightweight, highly available, and fault tolerant.
9
10Serf runs on Linux, Mac OS X, and Windows. An efficient and lightweight gossip
11protocol is used to communicate with other nodes. Serf can detect node failures
12and notify the rest of the cluster. An event system is built on top of
13Serf, letting you use Serf's gossip protocol to propagate events such
14as deploys, configuration changes, etc. Serf is completely masterless
15with no single point of failure.
16
17Here are some example use cases of Serf, though there are many others:
18
19* Discovering web servers and automatically adding them to a load balancer
20* Organizing many memcached or redis nodes into a cluster, perhaps with
21 something like [twemproxy](https://github.com/twitter/twemproxy) or
22 maybe just configuring an application with the address of all the
23 nodes
24* Triggering web deploys using the event system built on top of Serf
25* Propagating changes to configuration to relevant nodes.
26* Updating DNS records to reflect cluster changes as they occur.
27* Much, much more.
28
29## Quick Start
30
31First, [download a pre-built Serf binary](http://www.serfdom.io/downloads.html)
32for your operating system or [compile Serf yourself](#developing-serf).
33
34Next, let's start a couple Serf agents. Agents run until they're told to quit
35and handle the communication of maintenance tasks of Serf. In a real Serf
36setup, each node in your system will run one or more Serf agents (it can
37run multiple agents if you're running multiple cluster types. e.g. web
38servers vs. memcached servers).
39
40Start each Serf agent in a separate terminal session so that we can see
41the output of each. Start the first agent:
42
43```
44$ serf agent -node=foo -bind=127.0.0.1:5000 -rpc-addr=127.0.0.1:7373
45...
46```
47
48Start the second agent in another terminal session (while the first is still
49running):
50
51```
52$ serf agent -node=bar -bind=127.0.0.1:5001 -rpc-addr=127.0.0.1:7374
53...
54```
55
56At this point two Serf agents are running independently but are still
57unaware of each other. Let's now tell the first agent to join an existing
58cluster (the second agent). When starting a Serf agent, you must join an
59existing cluster by specifying at least one existing member. After this,
60Serf gossips and the remainder of the cluster becomes aware of the join.
61Run the following commands in a third terminal session.
62
63```
64$ serf join 127.0.0.1:5001
65...
66```
67
68If you're watching your terminals, you should see both Serf agents
69become aware of the join. You can prove it by running `serf members`
70to see the members of the Serf cluster:
71
72```
73$ serf members
74foo 127.0.0.1:5000 alive
75bar 127.0.0.1:5001 alive
76...
77```
78
79At this point, you can ctrl-C or force kill either Serf agent, and they'll
80update their membership lists appropriately. If you ctrl-C a Serf agent,
81it will gracefully leave by notifying the cluster of its intent to leave.
82If you force kill an agent, it will eventually (usually within seconds)
83be detected by another member of the cluster which will notify the
84cluster of the node failure.
85
86## Documentation
87
88Full, comprehensive documentation is viewable on the Serf website:
89
90http://www.serfdom.io/docs
91
92## Developing Serf
93
94If you wish to work on Serf itself, you'll first need [Go](http://golang.org)
95installed (version 1.2+ is _required_). Make sure you have Go properly
96[installed](https://golang.org/doc/install),
97including setting up your [GOPATH](http://golang.org/doc/code.html#GOPATH).
98
99Next, clone this repository into `$GOPATH/src/github.com/hashicorp/serf` and
100then just type `make`. In a few moments, you'll have a working `serf` executable:
101
102```
103$ make
104...
105$ bin/serf
106...
107```
108
109*note: `make` will also place a copy of the executable under $GOPATH/bin*
110
111You can run tests by typing `make test`.
112
113If you make any changes to the code, run `make format` in order to automatically
114format the code according to Go standards.
115