Skip to content

Commit

Permalink
rewrite docs, with pip and virtualenv
Browse files Browse the repository at this point in the history
  • Loading branch information
@warner
warner committed Mar 26, 2016
1 parent 090b592 commit ef17590
Show file tree
Hide file tree
Showing 4 changed files with 272 additions and 50 deletions.
2 changes: 1 addition & 1 deletion README.rst
View file
Expand Up @@ -33,7 +33,7 @@ pre-release code), you should create a virtualenv and install into that:
* `git clone https://github.com/tahoe-lafs/tahoe-lafs.git`
* `cd tahoe-lafs`
* `virtualenv tahoe`
* `source tahoe/bin/activate`
* `. tahoe/bin/activate`
* `pip install --editable .`
* `tahoe --version`

Expand Down
249 changes: 221 additions & 28 deletions docs/INSTALL.rst
View file
Expand Up @@ -29,54 +29,247 @@ hackers will help you out.

.. _the tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev

Install Python
--------------
Pre-Packaged Versions
---------------------

You may not need to build Tahoe at all.

If you are on Windows, please see `windows.rst`_ for platform-specific
instructions.

If you are on a Mac, you can either follow these instructions, or use the
pre-packaged bundle described in `OS-X.rst`_. The Tahoe project hosts
pre-compiled "wheels" for all dependencies, so use the ``--find-links=``
option described below to avoid needing a compiler.

Many Linux distributions include Tahoe-LAFS packages. Debian and Ubuntu users
can ``apt-get install tahoe-lafs``. See `OSPackages.rst`_ for other
platforms.



Preliminaries
-------------

If you don't use a pre-packaged copy of Tahoe, you can build it yourself.
You'll need Python2.7, pip, and virtualenv. On unix-like platforms, you will
need a C compiler, the Python development headers, and some libraries
(libffi-dev and libssl-dev).

On Debian/Ubuntu-derived distributions, this command will get you everything
you need::

apt-get install build-essential python-dev libffi-dev libssl-dev python-virtualenv

On OS-X, install pip and virtualenv as described below. If you want to
compile the dependencies yourself (instead of using ``--find-links`` to take
advantage of the pre-compiled ones we host), you'll also need to install
Xcode and its command-line tools.

* python 2.7

Check if you already have an adequate version of Python installed by running
``python -V``. The latest version of Python v2.7 is required. Python v2.6.x
and v3 do not work. On Windows, we recommend the use of native Python v2.7,
not Cygwin Python. If you don't have one of these versions of Python
installed, `download`_ and install the latest version of Python v2.7. Make
sure that the path to the installation directory has no spaces in it (e.g. on
Windows, do not install Python in the "Program Files" directory).
``python -V``. The latest version of Python v2.7 is required, which is 2.7.10
as of this writing. Python v2.6.x and v3 do not work. On Windows, we
recommend the use of native Python v2.7, not Cygwin Python. If you don't have
one of these versions of Python installed, `download`_ and install the latest
version of Python v2.7. Make sure that the path to the installation directory
has no spaces in it (e.g. on Windows, do not install Python in the "Program
Files" directory)::

% python --version
Python 2.7.11

.. _download: https://www.python.org/downloads/

Get Tahoe-LAFS
--------------
* pip

Many Python installations already include ``pip``, but in case yours does
not, follow the instructions at https://pip.pypa.io/en/stable/installing/ ::

% pip --version
pip 8.1.1 from ... (python 2.7)

* virtualenv

Install ``virtualenv`` with the instructions at
https://virtualenv.pypa.io/en/latest/installation.html ::

% virtualenv --version
15.0.1

* C compiler and libraries

Except on OS-X, where the Tahoe project hosts pre-compiled wheels for all
dependencies, you will need several C libraries installed before you can
build. You will also need the Python development headers, and a C compiler
(your python installation should know how to find these).

On Debian/Ubuntu-derived systems, use:

apt-get install build-essential python-dev libffi-dev libssl-dev python-virtualenv

RPM-based systems will use something similar, but with ``yum`` or ``rpm``
instead of ``apt-get``, and ``python-devel`` instead of ``python-dev``.

Install the Latest Tahoe-LAFS Release
------------------------------------

We recommend creating a fresh virtualenv for your Tahoe-LAFS install, to
isolate it from any python packages that are already installed (and to
isolate the rest of your system from Tahoe's dependencies).

Activate the virtualenv, then install the latest Tahoe-LAFS release from PyPI
with ``pip install tahoe-lafs``. After installation, run ``tahoe --version``
to confirm the install was successful::

% virtualenv tahoe
New python executable in ~/tahoe/bin/python2.7
Installing setuptools, pip, wheel...done.
% . tahoe/bin/activate
(tahoe) % pip install tahoe-lafs
Collecting tahoe-lafs
...
Installing collected packages: ...
Successfully installed ...
(tahoe) % tahoe --version
tahoe-lafs: 1.11.0
foolscap: ...
(tahoe) %

On OS-X, instead of ``pip install tahoe-lafs``, use this command to take
advantage of the hosted pre-compiled wheels::

pip install --find-links=https://tahoe-lafs.org/deps tahoe-lafs


Install From a Source Tarball
-----------------------------

You can also download the source tarball first, unpack it, then install from
the unpacked source tree.

Download the latest stable release, `Tahoe-LAFS v1.11.0`_.

.. _Tahoe-LAFS v1.11.0: https://tahoe-lafs.org/source/tahoe-lafs/releases/tahoe-lafs-1.11.0.tar.bz2

Then unpack and install (again into a virtualenv)::

% wget https://tahoe-lafs.org/source/tahoe-lafs/releases/tahoe-lafs-1.11.0.tar.bz2
...
% tar xf tahoe-lafs-1.11.0.tar.bz2
...
% cd tahoe-lafs-1.11.0
% virtualenv tahoe
New python executable in ~/tahoe-lafs-1.11.0/tahoe/bin/python2.7
Installing setuptools, pip, wheel...done.
% . tahoe/bin/activate
(tahoe) % pip install .
Processing ~/tahoe-lafs-1.11.0
...
Installing collected packages: ...
Successfully installed ...
(tahoe) % tahoe --version
tahoe-lafs: 1.11.0
...
(tahoe) %


Hacking On Tahoe-LAFS
---------------------

To modify the Tahoe source code, you should get a git checkout, and install
with the ``--editable`` flag::

% git clone https://github.com/tahoe-lafs/tahoe-lafs.git
...
% cd tahoe-lafs
% virtualenv tahoe
New python executable in ~/tahoe-lafs/tahoe/bin/python2.7
Installing setuptools, pip, wheel...done.
% . tahoe/bin/activate
(tahoe) % pip install --editable .
Processing ~/tahoe-lafs-1.11.0
...
Installing collected packages: ...
Successfully installed ...
(tahoe) % tahoe --version
tahoe-lafs: 1.11.0
...
(tahoe) %

This way, you won't have to re-run the ``pip install`` step each time you
modify the source code.

Running Tahoe-LAFS
------------------

The rest of the Tahoe-LAFS documentation assumes that you can run the
``tahoe`` executable that you just created. To do this from other shells, you
will either need to activate the virtualenv first (as above), or you can use
the full path to the ``tahoe`` executable. If you created the virtualenv in
``~/tahoe``, then the executable will live in ``~/tahoe/bin/tahoe``::

# new shell, not in a virtualenv
% ~/tahoe/bin/tahoe --version
tahoe-lafs: 1.11.0
...

You can symlink this to your ``~/bin`` directory for convenience. You might
also like the `pipsi`_ tool: by running ``pipsi install tahoe-lafs``, you
will end up with a ``~/.local/bin/tahoe`` that is symlinked to a new
virtualenv.

Download the latest stable release, `Tahoe-LAFS v1.10.2`_.
.. _pipsi: https://pypi.python.org/pypi/pipsi/0.9

.. _Tahoe-LAFS v1.10.2: https://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.10.2.zip
Running the Self-Tests
----------------------

Set Up Tahoe-LAFS
-----------------
To run the self-tests from a source tree, you'll need ``tox`` installed. On a
Debian/Ubuntu system, use ``apt-get install tox``. You can also install it
into your ``tahoe`` virtualenv with ``pip install tox``.

Unpack the zip file and cd into the top-level directory that is thus created.
Then just run ``tox``. This will create a new fresh virtualenv, install Tahoe
(from the source tree, including any changes you have made) and all its
dependencies into the virtualenv, then run the unit tests. This ensures that
the tests are repeatable and match the results of other users, unaffected by
anything else installed on your machine. On a modern computer this will take
5-10 minutes, and should result in a "all tests passed" mesage::

Run "``python setup.py build``" to generate the ``tahoe`` executable in a
subdirectory of the current directory named ``bin``. This will download and
build anything you need from various websites.
% tox
GLOB sdist-make: ~/tahoe/setup.py
py27 recreate: ~/tahoe/.tox/py27
py27 inst: ~/tahoe/.tox/dist/tahoe-lafs-1.11.0a2.post8.dev0.zip
py27 runtests: commands[0] | tahoe --version
py27 runtests: commands[1] | trial --rterrors allmydata
allmydata.test.test_auth
AccountFileCheckerKeyTests
test_authenticated ... [OK]
test_missing_signature ... [OK]
...
Ran 1186 tests in 423.179s
PASSED (skips=7, expectedFailures=3, successes=1176)
__________________________ summary ___________________________________
py27: commands succeeded
congratulations :)

On Windows, the ``build`` step might tell you to open a new Command Prompt
(or, on XP and earlier, to log out and back in again). This is needed the
first time you set up Tahoe-LAFS on a particular installation of Windows.
Common Problems
---------------

If you see an error like ``fatal error: Python.h: No such file or directory``
while compiling the dependencies, you need the Python development headers. If
you are on a Debian or Ubuntu system, you can install them with ``sudo
apt-get install python-dev``. On RedHat/Fedora, install ``python-devel``.

Run "``bin/tahoe --version``" (on Windows, "``bin\tahoe --version``") to
verify that the executable tool prints out the right version number after
"``allmydata-tahoe:``".
Similar errors about ``openssl/crypto.h`` indicate that you are missing the
OpenSSL development headers (``libssl-dev``). Likewise ``ffi.h`` means you
need ``libffi-dev``.

Optionally run "``python setup.py trial``" to verify that it passes all of
its self-tests.

Run Tahoe-LAFS
--------------

Now you are ready to deploy a decentralized filesystem. The ``tahoe``
executable in the ``bin`` directory can configure and launch your Tahoe-LAFS
nodes. See `<running.rst>`__ for instructions on how to do that.
executable can configure and launch your Tahoe-LAFS nodes. See
`<running.rst>`__ for instructions on how to do that.
21 changes: 14 additions & 7 deletions docs/running.rst
View file
Expand Up @@ -12,10 +12,10 @@ This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid.
First you have to install the Tahoe-LAFS software, as documented in
INSTALL.rst_.

The ``tahoe`` program in the ``bin`` directory is used to create,
start, and stop nodes. Each node lives in a separate base directory, in
which there is a configuration file named ``tahoe.cfg``. Nodes read and
write files within this base directory.
The ``tahoe`` program in your virtualenv's ``bin`` directory is used to
create, start, and stop nodes. Each node lives in a separate base
directory, in which there is a configuration file named ``tahoe.cfg``.
Nodes read and write files within this base directory.

A grid consists of a set of *storage nodes* and *client nodes* running
the Tahoe-LAFS code. There is also an *introducer node* that is
Expand All @@ -26,9 +26,6 @@ grid`_ as you only need to create a client node. When you want to create your
own grid you'll need to create the introducer and several initial storage
nodes (see the note about small grids below).

If the Tahoe-LAFS ``bin`` directory is not on your PATH, then in all
the command lines below, specify the full path to ``bin/tahoe``.

To construct a client node, run “``tahoe create-client``”, which will create
``~/.tahoe`` to be the node's base directory. Acquire the ``introducer.furl``
(see below if you are running your own introducer, or use the one from the
Expand Down Expand Up @@ -174,3 +171,13 @@ You can chat with other users of and hackers of this software on the
list`_.

.. _tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev


Complain
========

Bugs can be filed on the Tahoe-LAFS "Trac" instance, at
https://tahoe-lafs.org/trac/ .

You can also "fork" the repo and submit Pull Requests on Github:
https://github.com/tahoe-lafs/tahoe-lafs .

0 comments on commit ef17590

Please sign in to comment.