From e495db255bb84f72d349a2e072a763ee5340b053 Mon Sep 17 00:00:00 2001 From: Brian Warner Date: Wed, 4 Apr 2007 17:55:35 -0700 Subject: [PATCH] add more useful text to the README --- README | 71 +++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 58 insertions(+), 13 deletions(-) diff --git a/README b/README index c81fd788..3440af9f 100644 --- a/README +++ b/README @@ -2,6 +2,10 @@ Welcome to the AllMyData "tahoe" project. This project implements a scalable distributed fault-tolerant filestore. +The basic idea is that the data in this filesystem is spread over all +participating nodes, using an algorithm that can recover the data even if a +majority of the nodes are no longer available. + The main application code is in the 'allmydata' package, under src/allmydata/ . There is also a patched version of PyCrypto (adding a faster CTR-mode) in src/Crypto/ which gets installed to the 'allmydata.Crypto' package (since the @@ -44,22 +48,63 @@ BUILDING: 'make test' runs the unit test suite. - 'make deb-dapper' or 'make deb-sid' will construct a debian package named - 'allmydata-tahoe'. +INSTALLING: + + If you're running on a debian system, use 'make deb-dapper' or 'make + deb-sid' to construct a debian package named 'allmydata-tahoe', which you + can then install. + + If not, you'll need to run three separate install steps, one for each of the + three subpackages (allmydata, allmydata.Crypto, and pyfec). You may wish to + use a different version of 'python' for these steps, or provide a --prefix + or --root argument for the install. + + cd src/pyfec && python setup.py install && cd ../.. + + cd src/Crypto && python setup.py install && cd ../.. + + # the allmydata subpackage's setup.py script is in the root directory + python setup.py install + + To test that all the modules got installed properly, start a python + interpreter and import modules as follows: + + % python + Python 2.4.4 (#2, Jan 13 2007, 17:50:26) + [GCC 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)] on linux2 + Type "help", "copyright", "credits" or "license" for more information. + >>> import allmydata.Crypto + >>> import allmydata.interfaces + >>> import fec + >>> + + To run from a source tree (without installing first), type 'make', which + will put all the necessary libraries into a local directory named + instdir/lib/pythonN.N/site-packages/ , which you can then add to your + PYTHONPATH . + RUNNING: - If you installed one of the debian packages constructed by "make deb-*" then - it creates an 'allmydata-tahoe' executable, usually in /usr/bin . If you - didn't install a package you can find allmydata-tahoe in instdir/scripts. - This tool is used to create, start, and stop nodes. - - Somewhere in your mesh there must be a central 'queen' node. This is - constructed by running 'allmydata-tahoe create-queen --basedir WHERE'. Once - constructed, you can start the queen by running 'allmydata-tahoe start - --basedir WHERE'. Inside that base directory, there will be a pair of files - 'introducer.furl' and 'vdrive.furl'. Make a copy of these, as they'll be - needed on the client nodes. + If you installed one of the debian packages constructed by "make deb-*" then + it creates an 'allmydata-tahoe' executable, usually in /usr/bin . If you + didn't install a package you can find allmydata-tahoe in instdir/scripts. + This tool is used to create, start, and stop nodes. Each node lives in a + separate base directory, inside of which you can add files to configure and + control the node. Nodes also read and write files within that directory. + + A mesh consists of a single central 'queen' node and a large number of + 'client' nodes. If you are joining an existing mesh, the queen node will + already be running, and you'll just need to create a client node. If you're + creating a brand new mesh, you'll need to create both a queen and a client + (and then invite other people to create their own client nodes and join your + mesh). + + The queen node is constructed by running 'allmydata-tahoe create-queen + --basedir WHERE'. Once constructed, you can start the queen by running + 'allmydata-tahoe start --basedir WHERE'. Inside that base directory, there + will be a pair of files 'introducer.furl' and 'vdrive.furl'. Make a copy of + these, as they'll be needed on the client nodes. To construct a client node, pick a new working directory for it, then run 'allmydata-tahoe create-client --basedir $HERE'. Copy the two .furl files -- 2.45.2