From 0eb31774d1da25d95c4d628a83734252b888b23a Mon Sep 17 00:00:00 2001 From: Zooko O'Whielacronx Date: Sun, 30 Dec 2007 05:47:17 -0700 Subject: [PATCH] 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 | 10 +-- README | 33 ++------ docs/configuration.txt | 27 ++++-- docs/install-details.html | 98 ++++++++++++++++++++++ docs/install.html | 71 ++++++++++++++++ docs/running.html | 40 +++++++++ docs/{testnet => testgrid}/introducer.furl | 0 7 files changed, 242 insertions(+), 37 deletions(-) create mode 100644 docs/install-details.html create mode 100644 docs/install.html create mode 100644 docs/running.html rename docs/{testnet => testgrid}/introducer.furl (100%) diff --git a/Makefile b/Makefile index a42064c1..23d8aea9 100644 --- a/Makefile +++ b/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 diff --git a/README b/README index b77e85ad..4faef826 100644 --- a/README +++ b/README @@ -1,35 +1,16 @@ -Welcome to the Allmydata-Tahoe project. This project implements a secure, -distributed, fault-tolerant storage grid. All of the source code is available -under a Free Software licence. +Welcome to the Tahoe project, a secure, decentralized, fault-tolerant +filesystem. All of the source code is available under a Free +Software, Open Source licence. -The basic idea is that the data in this storage grid is spread over all -participating nodes, using an algorithm that can recover the data even if -some of the nodes are not available. +This filesystem is encrypted and spread over multiple peers in such a +way that it remains available even when some of the peers are +unavailable, malfunctioning, or malicious. -The interface to the storage grid allows you to store and fetch files, either -by self-authenticating cryptographic identifier or by filename and path. - -See the web site for all kinds of information, news, and community -discussion: +See the web site for information, news, and 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 diff --git a/docs/configuration.txt b/docs/configuration.txt index 4686663d..675b4d9f 100644 --- a/docs/configuration.txt +++ b/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, -providing vdrive access as defined in webapi.txt . This file should contain a -Twisted "strports" specification, such as "8123" or -"tcp:8123:interface=127.0.0.1". The 'tahoe create-client' command sets the -webport to "tcp:8123:interface=127.0.0.1" by default, and is overridable by -the "--webport" option. +webport (optional): This controls where the client's webserver should +listen, providing filesystem access as defined in webapi.txt . This +file contains a Twisted "strports" specification XXX hyperlink, +such as "8123" or "tcp:8123:interface=127.0.0.1". The 'tahoe +create-client' command sets the webport to +"tcp:8123:interface=127.0.0.1" by default, and is overridable by the +"--webport" option. + +XXX 
tahoe create-client
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 diff --git a/docs/install-details.html b/docs/install-details.html new file mode 100644 index 00000000..48ee44c7 --- /dev/null +++ b/docs/install-details.html @@ -0,0 +1,98 @@ + +The code is retrievable using the darcs +revision control tool by running the following command: + +
+darcs get http://allmydata.org/source/tahoe/trunk tahoe
+
+ +This will create a directory named 
tahoe
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 
darcs pull
. + + + +operating system +linux +cygwin +Windows +Mac OS X +Solaris +
location of 
tahoe
executable
/usr/bin
/usr/bin
C:\Python25\Scripts
/Frameworks/Python/Versions/2.5/binpre>(XXX double-check this)
/usr/bin
(XXX double-check this)
+ +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. + diff --git a/docs/install.html b/docs/install.html new file mode 100644 index 00000000..bf0648ae --- /dev/null +++ b/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 install-details.html. + + +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. Python including development + headers i.e. "Python.h" (programming language) + +4. zope.interface (programming language extension) + + Note that Tahoe does not require the entire Zope package, + merely the much smaller zope.interface component. + +5. Twisted (network and + operating system integration library) + + Installing Twisted from the Twisted "sumo" source tarball works on + all supported platforms. + +6. OpenSSL, including development + headers (cryptography library) + +7. PyOpenSSL (secure + transport layer) + +8. Crypto++, including development + headers (cryptography library) + +9. required only for Windows-native (not required for + Cygwin): pywin32 + + +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 
make check-deps
which verifies that all of the +dependencies listed above are installed. + +Run 
make
to build Tahoe and some included libraries and +install the 
tahoe
executable into a subdirectory of the +current directory named 
bin
. + +Run 
make test
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 running.html for +instructions. diff --git a/docs/running.html b/docs/running.html new file mode 100644 index 00000000..5bcec006 --- /dev/null +++ b/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 install.html. + + +RUNNING: + +The 
tahoe
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 the public test grid), 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 
tahoe create-introducer
. Now start the introducer +by running 
tahoe start
. After it starts, there will be a +file named 
introducer.furl
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 
tahoe create-client
. Acquire a copy of +the 
introducer.furl
from the introducer and put it into +this directory, then run 
tahoe start
. 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 http://127.0.0.1:8123 to use +this node. + diff --git a/docs/testnet/introducer.furl b/docs/testgrid/introducer.furl similarity index 100% rename from docs/testnet/introducer.furl rename to docs/testgrid/introducer.furl -- 2.45.2