update the quick start guide for debian jessie

README.md

@@ -30,19 +30,13 @@ And then running:
 
     $ sudo apt-key adv --recv-key 0xC0EAC2F9CE9ED9B0
     $ sudo apt-get update
-    $ sudo apt-get install etcd autoradio
-
-This will install and start the necessary jobs (which will initially
-fail due to the missing configuration).
-
-Edit `/etc/default/autoradio` and set, at least, the `DOMAIN`
-variable to what you've assigned to the cluster. The jobs will
-automatically start as soon as the configuration is saved.
+    $ sudo apt-get install etcd autoradio-server
 
 
 ## Full cluster install procedure
 
-Note: this procedure requires etcd 2.0 or later.
+Note: this procedure assumes a Debian distribution, it should work
+either with Wheezy (oldstable) or Jessie (stable).
 
 This assumes that you have an existing domain name (here
 *example.com*) that you control, and that you will run the cluster
@@ -53,60 +47,79 @@ number of machines.
 Having said that, follow these steps to bootstrap a new streaming
 cluster:
 
-1. Make sure that, on each of your servers, the output of
-   `hostname -f` is the fully-qualified hostname of the machine,
-   and that it resolves to its public IP (possibly using `/etc/hosts`).
+1. Make sure that, on each of your servers, the output of `hostname
+   -f` is the fully-qualified hostname of the machine, and that it
+   resolves to its public IP (possibly using `/etc/hosts`). This way
+   autoradio can detect the IP address that peers should use when
+   communicating with each host. Also, for simplicity, we're going to
+   assume that each host can resolve the IP address of each other just
+   by using its short name.
+
+2. Pick one of your servers, say *host1*, and add a delegation for
+   *radio.example.com* to it. For instance, in a `bind`-formatted zone
+   file:
+
+        radio  IN   NS  3600  host1.example.com.
+
+3. On *host1*, edit `/etc/default/etcd` with the following contents:
 
-2. On every server, run the above-mentioned steps to set up the APT
-   repository and install (do not configure) the `etcd` and
-   `autoradio` packages.
+        ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
+        ETCD_INITIAL_ADVERTISE_PEER_URLS=http://host1:2380
+        ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
+        ETCD_ADVERTISE_CLIENT_URLS=http://host1:2379
+        ETCD_INITIAL_CLUSTER_STATE=new
+        ETCD_INITIAL_CLUSTER=node1=http://host1:2380
 
-3. Pick one of your servers and add a delegation for
-   *radio.example.com* to it. For instance, with `bind`:
+    Once you save the file, restart the *etcd* daemon: this will
+    initialize an empty database:
 
-        radio  IN   NS  3600  machine1.example.com.
+        $ service etcd restart
 
-4. On *machine1*, edit `/etc/default/etcd` with the following
-   contents:
+4. On *host1*, edit `/etc/default/autoradio` and add:
 
-        START=1
-        BOOTSTRAP=1
+        DOMAIN="--domain=radio.example.com"
 
-    Once you save the file, the *etcd* daemon will start and
-    initialize an empty database.
+5. Run the steps in the _Installation_ section above to set up the APT
+   repository and install the `etcd` and `autoradio` packages using
+   the configuration you just wrote.
 
-5. On *machine1*, edit `/etc/default/autoradio` and set
-   `DOMAIN=radio.example.com`. This will start the *radiod* and
-   *redirectord* daemons, and you will be able to serve DNS records
-   for the *radio.example.com* zone. Check with:
+   This will start the *radiod* and *redirectord* daemons, and you
+   will be able to serve DNS records for the *radio.example.com* zone.
+
+   Check that the service is healthy with:
 
         $ ping -c1 radio.example.com
 
-    This should send a ping to *machine1*.
+    This should send a ping to *host1*.
+
+Now that the first node is up and running, set up the remaining
+machines. For every host:
 
-6. Set up the remaining machines. It is a two-step process: first, run
-   the following command on the first machine:
+1. Set up etcd. First, run the following command on the first machine
+   (host1):
 
-        $ etcdctl member add machine2 http://machine2:2380
+        $ etcdctl member add host2 http://host2:2380
 
-    (remember not to include a final slash on the node URL).
+   (remember not to include a final slash on the node URL).
 
-    This will print out some environment variables. You should copy
-    the `ETCD_INITIAL_CLUSTER` line into `/etc/default/etcd` on
-    machine2, resulting in something like:
+   This will print out some environment variables. You should copy
+   the `ETCD_INITIAL_CLUSTER` line into `/etc/default/etcd` on
+   the new host. The other lines of that file should be identical to
+   what shown in step 4 of the previous checklist, replacing the host
+   name where necessary.
 
-        START=1
-        ETCD_INITIAL_CLUSTER=machine1=http://...,machine2=http://...
-    
-    Finally, set `DOMAIN=radio.example.com` in
-    `/etc/default/autoradio`, and the daemons will start
-    automatically.
+   Note that you will need to wait for etcd on the new machine to
+   start successfully before you can run `etcdctl member add` for the
+   next one. For further instructions on how to change the etcd
+   cluster configuration at runtime, see
+   [the etcd documentation](https://github.com/coreos/etcd/blob/master/Documentation/runtime-configuration.md).
 
-    Note that you will need to wait for etcd on the new machine to
-    start successfully before you can run `etcdctl member add` for the
-    next one. For further instructions on how to change the etcd
-    cluster configuration at runtime, see
-    [the etcd documentation](https://github.com/coreos/etcd/blob/master/Documentation/runtime-configuration.md).
+2. Set `DOMAIN` in `/etc/default/autoradio` (as shown in step 5 of
+   the previous checklist above), and the daemons will start
+   automatically.
+
+3. Install the autoradio packages, see _Installation_ section above.
+   The daemons should start automatically with the new configuration.
 
 
 ## Building from source
@@ -185,16 +198,16 @@ The autoradio HTTP server can operate in one of two modes:
     redirects but might simplify access for people behind corporate
     proxies and such.
 
-    This behavior is controlled by the `--enable-icecast-proxy`
-    command-line flag to *redirectord*.
+This behavior is controlled by the `--enable-icecast-proxy`
+command-line flag to *redirectord*. It is set to true by default.
 
 
 ## Firewalls
 
 The users should be able to reach ports 53/tcp, 53/udp, 80/tcp and
-8000/tcp (unless proxying is enabled) on all nodes. Nodes should be
-able to reach 2379/tcp and 2380/tcp (the etcd ports) on each other;
-these two ports can be public if you've set up X509-based
+8000/tcp (the latter only if proxying is disabled) on all nodes. Nodes
+should be able to reach 2379/tcp and 2380/tcp (the etcd ports) on each
+other; these two ports can be public if you've set up X509-based
 authentication for etcd.
 
 
@@ -237,7 +250,7 @@ started in the whole cluster.
 
 There's a [Vagrant](http://www.vagrantup.com/) environment in the
 `vagrant-test` subdirectory that will set up a test three-node cluster
-(with Debian Wheezy as the base system) using pre-packaged binaries.
+(with Debian Jessie as the base system) using pre-packaged binaries.
 To run it:
 
     $ cd vagrant-test
@@ -248,10 +261,10 @@ it will turn up three nodes called **node1**, **node2** and **node3**.
 Use `vagrant ssh` to inspect them.
 
 If you want to test a locally-built package, copy the `autoradio` and
-`etcd` Debian packages in the `vagrant-test` directory and set the
-`LOCAL` environment variable to a non-empty string when invoking
-vagrant:
-
-    $ LOCAL=1 vagrant up
+`etcd` Debian packages in the `vagrant-test` directory and, in that
+same directory, run
 
+    $ dpkg-scanpackages -m . >Packages
 
+the provisioning process will automatically use the local packages if
+they are available.