updated documentation

README

-
-
-radio.ai
-========
-
-A distributed, fault-tolerant icecast streaming network.
-

README.rst

+
+
+radio.ai
+========
+
+The RadioAI service aims to provide a reliable, fault-tolerant Icecast
+streaming network for audio and video. It provides all the necessary
+components to ensure that the traffic from the source to the clients
+is uninterrupted, even in face of high load or server crashes.
+
+It is a full-stack service, meaning that it includes its own DNS and
+HTTP servers, for full control of the request flow.
+
+RadioAI works by using etcd_ to coordinate the various nodes and store
+the global mount configuration. The intended target is a set of
+homogeneous servers (or virtual machines) dedicated to this purpose.
+RadioAI also needs a dedicated DNS domain (or a delegation for a
+subdomain).
+
+
+Installation
+------------
+
+The simplest installation method is probably to use the pre-built
+Debian packages (only available for amd64 at the moment), by placing
+this line in ``/etc/apt/sources.list.d/radioai.list``::
+
+    deb http://www.incal.net/ale/debian radioai/
+
+And then running::
+
+    $ sudo apt-get update
+    $ sudo apt-get install etcd radioai
+
+This will install and start the necessary jobs (which will initially
+fail due to the missing configuration).
+
+Edit ``/etc/default/radioai`` 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.
+
+
+Securing etcd
++++++++++++++
+
+In a production cluster, you will want to limit access to the *etcd*
+daemons so that only the other nodes can connect to it. While it is
+possible to do this with firewall rules, the dynamic membership of the
+cluster may make this difficult. We suggest using instead *etcd*'s
+support for X509 client authentication, together with a tool to manage
+an online CA (such as autoca_). This way, enrolling a new machine in
+the cluster only requires generating a new client certificate, and no
+other configuration.
+
+Install the CA certificate in ``/etc/radioai/etcd_ca.pem``, the client
+certificate in ``/etc/radioai/etcd_client.pem`` and its private key in
+``/etc/radioai/etcd_client.key``, and the clients will connect to
+*etcd* using SSL authentication.
+
+
+Operation
+---------
+
+In order to create a new stream (*mount*, in the Icecast terminology),
+assuming you are running RadioAI on the ``example.com`` domain:
+
+#. On any node, run::
+
+    $ radioctl create-mount /path/to/mount.ogg
+
+   this will output the username and password used to authenticate the
+   source. Take note of them.
+
+   The cluster will be automatically reconfigured with the new mount in
+   a few seconds at most.
+
+#. Configure the source, using the username/password provided in the
+   previous step, and point it at the following URL::
+
+    http://stream.example.com/path/to/mount.ogg
+
+#. Tell your users to listen to the stream at::
+
+    http://stream.example.com/path/to/mount.ogg.m3u
+
+
+DNS zone delegation
++++++++++++++++++++
+
+Since we can't modify the DNS glue records for the zone delegation in
+real-time, we have to restrict slightly the assumptions on the
+availability of nodes in the cluster: you have to assume that at least
+N of your nodes will be partially available at any one time (i.e. at
+least one of a chosen subset of N servers will be reachable). The
+number N should be fairly low, say 3. Then, you can use those 3
+servers as the nameservers for zone delegation, and the other nodes
+are free to have dynamic membership.
+
+
+
+.. _etcd: https://github.com/coreos/etcd
+.. _autoca: https://git.autistici.org/public/ai/autoca