Setting up Disco
This document helps you to install Disco from source, either on a single server or a cluster of servers. This requires installation of some :ref:`prereqs`.
.. seealso:: :ref:`install_sys`.
You should have a quick look at :ref:`overview` before setting up the system, to get an idea what should go where and why. To make a long story short, Disco works as follows:
You need at least one Linux/Unix server. Any distribution should work (including Mac OS X).
On each server the following are required:
The same version of Erlang and Python should be installed on all servers. The default version of Python on the clients from which Disco jobs are submitted should also match that on the servers.
DISCO_PROXY needs one of
Due to issues with unicode in Python2's httplib library, we recommend installing the pycurl package. Disco will transparently use pycurl when available.
git clone git://github.com/discoproject/disco.git $DISCO_HOME cd $DISCO_HOME make cd lib && python setup.py install --user && cd .. bin/disco nodaemon
Its convenient to add the :mod:`disco <discocli>` command to your path.
Extract the package (if necessary) and
cd into it.
We will refer to this directory as :envvar:`DISCO_HOME`.
Now compile Disco:
This is often the easiest and the least intrusive way to get started with Disco.
You should repeat the above command on all machines in your Disco cluster. You can also install disco systemwide:
Install the python libraries for the local user:
cd lib python setup.py install --user cd ..
Or you can install these libraries in your favorite place.
Disco must be located at the same path on all the nodes.
To start the master and enter its Erlang shell, without redirecting the log to a file, run:
To start the master as a daemon and log to a file, use:
If Disco has started up properly, you should be able to see its processes running:
ps aux | grep beam.*disco
If you don't see any Disco processes, you may want to try :ref:`troubleshooting`.
Next we need to enable passwordless login via ssh to all servers in
the Disco cluster. If you have only one machine, you need to enable
passwordless login to
localhost for the Disco user.
Run the following command as the Disco user, assuming that it doesn't have valid ssh-keys already:
ssh-keygen -N '' -f ~/.ssh/id_dsa
If you have one server (or shared home directories), say:
cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys
Otherwise, repeat the following command for all the servers
in the cluster:
Now try to login to all servers in the cluster or
localhost, if you
have only one machine. You should not need to give a password nor answer
to any questions after the first login attempt.
As the last step, if you run Disco on many machines, you need to make sure that all servers in the Disco cluster use the same Erlang cookie, which is used for authentication between Erlang nodes. Run the following command as the Disco user on the master server:
scp ~/.erlang.cookie nodeX:
Repeat the command for all the servers
The Erlang cookie must be readable only to the disco user.
If it isn't, run
chmod 400 ~/.erlang.cookie on all the nodes.
Add nodes to Disco
At this point you should have Disco up and running. The final step, before testing the system, is to specify which servers are available for Disco. This is done via Disco's web interface.
Point your browser at
where :envvar:`DISCO_MASTER_HOST` and :envvar:`DISCO_PORT` should be
replaced with their actual values.
Normally you can use http://localhost:8989,
if you run Disco locally or through an SSH tunnel.
You should see the Disco main screen (see :ref:`a screenshot <screenshots>`).
configure on the right side of the page.
On the configuration page, click
add row to add a new set of available nodes.
Click the cells on the new empty row, and add hostname of an available server
(or a :ref:`range of hostnames <confignodes_multi>`) in the left cell,
and the number of available cores (CPUs) on that server in the right cell.
Once you have entered a value, click the cell again to save it.
Keep in mind that for more than one node, hostnames need to resolve globally (e.g. you should be relying on DNS to resolve hostnames, not /etc/hosts on an individual machine).
Hostnames used by Disco are shortnames, and not fully qualified hostnames. DNS must be configured to correctly resolve the shortnames of the hostnames in the cluster.
Disco cannot currently use raw IP addresses for hostnames. Short DNS hostnames must be used to name cluster nodes.
A relatively common mistake is that
master is just an alias for the loopback address,
localhost, provided in /etc/hosts on the master machine.
In such cases, some nodes may not be able to resolve the master properly:
they may all resolve to themselves (if they all have the same hosts file),
nothing at all, or different machines (if they are configured differently).
You can add as many rows as needed to fully specify your cluster,
which may have varying number of cores on different nodes.
save table when you are done.
If you have only a single machine, the resulting table should look like this, assuming that you have two cores available for Disco:
Add multiple nodes in the same line
You can also specify multiple nodes on a single line, if the nodes are named with a common prefix, as here:
This table specifies that there are 30 nodes available in the cluster, from
nx30 and each node has 8 cores.
Test the System
Now Disco should be ready for use.
We can use the following simple Disco script that computes word frequencies in a text file to see that the system works correctly.
.. literalinclude:: ../../examples/util/count_words.py :language: python
Run the script as follows from :envvar:`DISCO_HOME`:
Disco attempts to use the current hostname as :envvar:`DISCO_MASTER_HOST`, if it is not defined in any settings file.
If you are runing Disco on multiple machines you must use the same version of Python for running Disco scripts as you use on the server side.
You can run the script on any machine that can access the master. The safest bet is to test the script on the master node itself.
If the machine where you run the script can access the master node but not other nodes in the cluster, you need to set :envvar:`DISCO_PROXY`. The proxy address should be the same as the master's above. This makes Disco fetch results through the master node, instead of connecting to the nodes directly.
If the script produces some results, congratulations, you have a working Disco setup! If you are new to Disco, you might want to read the :ref:`tutorial` next.
If the script fails, see the section about :ref:`troubleshooting`.