docs: a bunch of updates to simplify the process of installing from source and running Tahoe

These changes are a work-in-progress -- there are many incomplete and incorrect parts, but the install.html and running.html files 
are complete and should work (and they are delightfully concise!).  I'm pushing this just to let people see incremental progress 
and to solicit feedback.  "Testing out" the install.html and running.html files and submitting patches or bug reports would be 
quite welcome.

More to come.

Makefile

@@ -45,7 +45,7 @@ endif
 
 TRIAL=PYTHONUNBUFFERED=1 $(TRIALCMD) --rterrors $(REACTOROPT)
 
-build-deps: check-manual-deps
+build-deps: check-deps
 	mkdir -p "$(SUPPORTLIB)"
 	PYTHONPATH="$(PYTHONPATH)$(PATHSEP)$(SUPPORTLIB)$(PATHSEP)" \
          $(PYTHON) misc/dependencies/build-deps-setup.py install \
@@ -98,7 +98,7 @@ endif
 
 # TESTING
 
-.PHONY: check-deps check-twisted-dep $(CHECK_PYWIN32_DEP) signal-error-deps, signal-error-twisted-dep, signal-error-pywin32-dep, test test-figleaf figleaf-output
+.PHONY: check-all-deps check-twisted-dep $(CHECK_PYWIN32_DEP) signal-error-deps, signal-error-twisted-dep, signal-error-pywin32-dep, test test-figleaf figleaf-output
 
 
 signal-error-deps:
@@ -139,7 +139,7 @@ OpenSSL).  Please see the README for help on installing dependencies."
 	@echo
 	exit 1
 
-check-deps: check-manual-deps
+check-all-deps: check-deps
 	$(PP) \
 	 $(PYTHON) -c 'import allmydata, zfec, foolscap, simplejson, nevow, pycryptopp' || $(MAKE) signal-error-deps
 
@@ -152,10 +152,10 @@ check-pywin32-dep:
 check-pyopenssl-dep:
 	$(PYTHON) -c 'import OpenSSL' || $(MAKE) signal-error-pyopenssl-dep
 
-check-manual-deps: check-twisted-dep $(CHECK_PYWIN32_DEP) check-pyopenssl-dep
+check-deps: check-twisted-dep $(CHECK_PYWIN32_DEP) check-pyopenssl-dep
 
 .checked-deps:
-	$(MAKE) check-deps
+	$(MAKE) check-all-deps
 	touch .checked-deps
 
 # you can use 'make test TEST=allmydata.test.test_introducer' to run just

README

@@ -1,35 +1,16 @@
-Welcome to the Allmydata-Tahoe project.  This project implements a secure,
+Welcome to the Tahoe project, a secure, decentralized, fault-tolerant
-distributed, fault-tolerant storage grid.  All of the source code is available 
+filesystem.  All of the source code is available under a Free
-under a Free Software licence.
+Software, Open Source licence.
 
-The basic idea is that the data in this storage grid is spread over all
+This filesystem is encrypted and spread over multiple peers in such a
-participating nodes, using an algorithm that can recover the data even if
+way that it remains available even when some of the peers are
-some of the nodes are not available.
+unavailable, malfunctioning, or malicious.
 
-The interface to the storage grid allows you to store and fetch files, either
+See the web site for information, news, and discussion:
-by self-authenticating cryptographic identifier or by filename and path.
-
-See the web site for all kinds of information, news, and community
-discussion:
 
 http://allmydata.org
 
 
-GETTING PRECOMPILED BINARIES FOR DEBIAN-LIKE SYSTEMS:
-
-Pre-compiled binaries are available for Debian or Ubuntu.  Please see the
-following web page for instructions:
-
-http://allmydata.org/trac/tahoe/wiki/DownloadDebianPackages
-
-
-BUILDING ON WINDOWS:
-
-Please see the README.win32 file for some specific issues, but after you've
-understood those issues then come back here and follow the instructions in
-this README.
-
-
 DEPENDENCIES:
 
 If you aren't getting a pre-compiled binary, then you'll have to ensure that

docs/configuration.txt

@@ -20,12 +20,27 @@ furl is created by the introducer node and written into its base directory
 when it starts, whereupon it should be published to everyone who wishes to
 attach a client to that grid
 
-webport (optional): This controls where the client's webserver should listen,
+webport (optional): This controls where the client's webserver should
-providing vdrive access as defined in webapi.txt . This file should contain a
+listen, providing filesystem access as defined in webapi.txt . This
-Twisted "strports" specification, such as "8123" or
+file contains a Twisted "strports" specification XXX hyperlink,
-"tcp:8123:interface=127.0.0.1".  The 'tahoe create-client' command sets the
+such as "8123" or "tcp:8123:interface=127.0.0.1".  The 'tahoe
-webport to "tcp:8123:interface=127.0.0.1" by default, and is overridable by
+create-client' command sets the webport to
-the "--webport" option.
+"tcp:8123:interface=127.0.0.1" by default, and is overridable by the
+"--webport" option.
+
+XXX <pre>tahoe create-client</pre> will put a port specification into a file named
+XXX $HERE/webport, unless overridden by the --webport option to
+XXX create-client.  The presence of a port specification in the webport
+XXX file prompts the client node to run a webserver on the desired port,
+XXX through which you can view, upload, download, and delete files.  The
+XXX contents of the webport file is actually a "strports specification",
+XXX defined in
+XXX http://twistedmatrix.com/documents/current/api/twisted.application.strports.html
+XXX , so you can have it only listen on a local interface by writing
+XXX "tcp:8123:interface=127.0.0.1" to this file (that's what create-client
+XXX does by default), or make it use SSL by writing
+XXX "ssl:8123:privateKey=mykey.pem:certKey=cert.pem" instead.
+
 
 client.port (optional): This controls which port the node listens on. If not
 provided, the node will ask the kernel for any available port, and write it

docs/install-details.html

@@ -0,0 +1,98 @@
+
+The code is retrievable using the <a href="http://darcs.net">darcs</a>
+revision control tool by running the following command:
+
+<pre>
+darcs get http://allmydata.org/source/tahoe/trunk tahoe
+</pre>
+
+This will create a directory named <pre>tahoe</pre> in the current working
+directory and put a copy of the latest source code into it.  Later, if
+you want to get any new changes, then cd into that directory and run
+the command <pre>darcs pull</pre>.
+
+
+<table>
+<tt>operating system</tt><td>location of <pre>tahoe</pre> executable</td>
+<tt>linux</tt><td><pre>/usr/bin</pre></td>
+<tt>cygwin</tt><td><pre>/usr/bin</pre></td>
+<tt>Windows</tt><td><pre>C:\Python25\Scripts</pre></td>
+<tt>Mac OS X</tt><td><pre>/Frameworks/Python/Versions/2.5/binpre>(XXX double-check this)</td>
+<tt>Solaris</tt><td><pre>/usr/bin</pre>(XXX double-check this)</td>
+</table>
+
+EASY_INSTALLABLE DEPENDENCIES
+
+The following Python packages are required, but normally they are
+automatically installed as a side-effect of installing Tahoe.
+
+ + Python setuptools (build and distribution tool)
+
+   http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
+
+   The Tahoe install process will automatically download and install
+   setuptools if it is not present.  However, if an old, incompatible version
+   of setuptools is present (< v0.6c6 on Cygwin, or < v0.6a9 on other
+   platforms), then the install will fail.
+
+   If the install fails due to your current version of setuptools being
+   incompatible, please either upgrade or uninstall your version of
+   setuptools and re-run the install.
+
+ + zfec (erasure coding library)
+
+   http://cheeseshop.python.org/pypi/zfec
+
+   zfec is packaged in a setuptools-compatible way and included in the Python
+   Package Index (PyPI), so it will be automatically installed when you
+   install Tahoe (see INSTALLING).  It can be manually installed by running
+   "easy_install zfec".
+
+ + Python foolscap (secure remote object library)
+
+   http://cheeseshop.python.org/pypi/foolscap
+
+   foolscape is packaged in a setuptools-compatible way and included in the
+   Python Package Index (PyPI), so it will be automatically installed when
+   you install Tahoe (see INSTALLING).  It can be manually installed by
+   running "easy_install foolscap".
+
+ + Python simplejson (JSON parser)
+
+   http://cheeseshop.python.org/pypi/simplejson
+
+   simplejson is packaged in a setuptools-compatible way and included in the
+   Python Package Index (PyPI), so it will be automatically installed when
+   you install Tahoe (see INSTALLING).  It can be manually installed by
+   running "easy_install simplejson".
+
+ + Python Nevow (0.6.0 or later) (web presentation language)
+
+   http://divmod.org/trac/wiki/DivmodNevow
+
+   Note that the current version of Nevow (0.9.18) requires Twisted 2.4.0 or
+   later.
+
+   Nevow is packaged in a setuptools-compatible way and included in the
+   Python Package Index (PyPI), so it will be automatically installed when
+   you install Tahoe (see INSTALLING).  It can be manually installed by
+   running "easy_install nevow".
+
+ + Python pycryptopp (0.2.1 or later) (Python crypto library)
+
+   http://pypi.python.org/pypi/pycryptopp
+
+   pycryptopp is packaged in a setuptools-compatible way and included in the
+   Python Package Index (PyPI), so it will be automatically installed when
+   you install Tahoe (see INSTALLING).  It can be manually installed by
+   running "easy_install nevow".
+
+If you are behind a firewall and you can configure your firewall to
+forward TCP connections on a port to the computer running your Tahoe
+node, then you can configure the Tahoe node to announce itself as
+being available on that IP address and port.  The way to do this is to
+create a file named $HERE/advertised_ip_addresses, in which you can
+put IP addresses and port numbers in "dotted-quad:port" form,
+e.g. "209.97.232.113:1345".  You can put multiple
+IP-address-and-port-number entries into this file, on separate lines.
+

docs/install.html

@@ -0,0 +1,71 @@
+This is the default procedure to install from source.  It has been
+verified to work on Windows, Cygwin, Mac, Linux, and Solaris.  It's
+likely to work on other platforms.  For more details and for
+alternative installation procedures, please
+see <a href="install-details.html">install-details.html</a>.
+
+
+DEPENDENCIES:
+
+Prior to installing Tahoe the following must be installed:
+
+1. gcc including g++ (programming language)
+
+   If you are building for Windows or for Cygwin, the Cygwin version
+   of gcc will work.
+
+2. GNU make (build tool) 
+
+3. <a href="http://python.org">Python</a> including development
+   headers i.e. "Python.h" (programming language)
+
+4. zope.interface (programming language extension)
+
+   Note that Tahoe does <em>not</em> require the entire Zope package,
+   merely the much smaller zope.interface component.
+
+5. <a href="http://twistedmatrix.com">Twisted</a> (network and
+   operating system integration library)
+
+   Installing Twisted from the Twisted "sumo" source tarball works on
+   all supported platforms.
+
+6. <a href="http://openssl.org">OpenSSL</a>, including development
+   headers (cryptography library)
+
+7. <a href="http://pyopenssl.sourceforge.net">PyOpenSSL</a> (secure
+   transport layer)
+
+8. <a href="http://cryptopp.com">Crypto++</a>, including development
+   headers (cryptography library)
+
+9. required only for Windows-native (not required for
+   Cygwin): <a href="http://sourceforge.net/projects/pywin32/">pywin32</a>
+
+
+GET THE SOURCE CODE:
+
+Tarballs of the source code are available at:
+
+http://allmydata.org/source/tahoe/
+
+
+INSTALL:
+
+Unpack the tarball and cd into the top-level directory.
+
+Run <pre>make check-deps</pre> which verifies that all of the
+dependencies listed above are installed.
+
+Run <pre>make</pre> to build Tahoe and some included libraries and
+install the <pre>tahoe</pre> executable into a subdirectory of the
+current directory named <pre>bin</pre>.
+
+Run <pre>make test</pre> to verify that it built correctly and passes
+all tests.
+
+
+Now you have the Tahoe source code installed and are ready to use it
+to form a decentralized
+filesystem. See <a href="running.html">running.html</a> for
+instructions.

docs/running.html

@@ -0,0 +1,40 @@
+This is how to run a Tahoe node or a complete Tahoe grid.  First you
+have to install the Tahoe source code, as documented
+in <a href="install.html">install.html</a>.
+
+
+RUNNING:
+
+The <pre>tahoe</pre> executable 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 the node.  Nodes also read and write
+files within that directory.
+
+A grid consists of a single Introducer and one or more nodes.  If you
+are creating a new grid, you'll need to create both an Introducer and
+a node (and then invite other people to create their own nodes and
+join your grid).  If you are joining an existing grid (such
+as <a href="http://XXX">the public test grid</a>), the Introducer will
+already be running, and you'll need to create a node.
+
+To construct an introducer, create a new empty base directory for it
+(the name of the directory is up to you) and cd into that directory.
+Now run <pre>tahoe create-introducer</pre>.  Now start the introducer
+by running <pre>tahoe start</pre>.  After it starts, there will be a
+file named <pre>introducer.furl</pre> in that base directory.  This
+file contains the URL which the nodes must use in order to connect to
+this introducer.
+
+To construct a node, create a new empty base directory (the name of
+the directory is up to you) and cd into that directory.  Now
+run <pre>tahoe create-client</pre>.  Acquire a copy of
+the <pre>introducer.furl</pre> from the introducer and put it into
+this directory, then run <pre>tahoe start</pre>.  After that, the node
+should be off and running.  The first thing it will do is connect to
+the introducer and get itself connected to all other nodes on the
+grid.
+
+Point your web browser
+to <a href="http://127.0.0.1:8123">http://127.0.0.1:8123</a> to use
+this node.
+