mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2025-01-18 02:40:07 +00:00
rewrite docs, with pip and virtualenv
This commit is contained in:
Brian Warner
parent
090b592ff8
commit
ef1759046d
@ -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`
|
||||
|
||||
|
||||
249
docs/INSTALL.rst
249
docs/INSTALL.rst
@ -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
|
||||
|
||||
Download the latest stable release, `Tahoe-LAFS v1.10.2`_.
|
||||
Many Python installations already include ``pip``, but in case yours does
|
||||
not, follow the instructions at https://pip.pypa.io/en/stable/installing/ ::
|
||||
|
||||
.. _Tahoe-LAFS v1.10.2: https://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.10.2.zip
|
||||
% pip --version
|
||||
pip 8.1.1 from ... (python 2.7)
|
||||
|
||||
Set Up Tahoe-LAFS
|
||||
-----------------
|
||||
* virtualenv
|
||||
|
||||
Unpack the zip file and cd into the top-level directory that is thus created.
|
||||
Install ``virtualenv`` with the instructions at
|
||||
https://virtualenv.pypa.io/en/latest/installation.html ::
|
||||
|
||||
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.
|
||||
% virtualenv --version
|
||||
15.0.1
|
||||
|
||||
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.
|
||||
* 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.
|
||||
|
||||
.. _pipsi: https://pypi.python.org/pypi/pipsi/0.9
|
||||
|
||||
Running the Self-Tests
|
||||
----------------------
|
||||
|
||||
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``.
|
||||
|
||||
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::
|
||||
|
||||
% 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 :)
|
||||
|
||||
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.
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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 .
|
||||
|
||||
@ -6,30 +6,39 @@ You'll need `python`, `pip`, and `virtualenv`. But you won't need a compiler.
|
||||
Preliminaries
|
||||
-------------
|
||||
|
||||
1: Install Python-2.7.10 . Use the "Windows x86-64 MSI installer" at https://www.python.org/downloads/release/python-2711/
|
||||
1: Install Python-2.7.10 . Use the "Windows x86-64 MSI installer" at
|
||||
https://www.python.org/downloads/release/python-2711/
|
||||
|
||||
2: That should install `pip`, but if it doesn't, look at https://pip.pypa.io/en/stable/installing/ for installation instructions.
|
||||
2: That should install `pip`, but if it doesn't, look at
|
||||
https://pip.pypa.io/en/stable/installing/ for installation instructions.
|
||||
|
||||
3: Install `virtualenv` with https://virtualenv.pypa.io/en/latest/installation.html
|
||||
3: Install `virtualenv` with
|
||||
https://virtualenv.pypa.io/en/latest/installation.html
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
1: Start a CLI shell
|
||||
|
||||
2: Create a new virtualenv. Everything specific to Tahoe will go into this. You can use whatever name you like for the virtualenv, but example uses "tahoe".
|
||||
2: Create a new virtualenv. Everything specific to Tahoe will go into this.
|
||||
You can use whatever name you like for the virtualenv, but example uses
|
||||
"tahoe"::
|
||||
|
||||
PS C:\Users\me> virtualenv tahoe
|
||||
New python executable in C:\Users\me\tahoe\Scripts\python.exe
|
||||
Installing setuptools, pip, wheel...done.
|
||||
>
|
||||
|
||||
3: Activate the new virtualenv. This puts the virtualenv's `Scripts` directory on your PATH, allowing you to run commands that are installed there. The command prompt will change to include `(tahoe)` as a reminder that you've activated the "tahoe" virtualenv
|
||||
3: Activate the new virtualenv. This puts the virtualenv's `Scripts`
|
||||
directory on your PATH, allowing you to run commands that are installed
|
||||
there. The command prompt will change to include `(tahoe)` as a reminder that
|
||||
you've activated the "tahoe" virtualenv::
|
||||
|
||||
PS C:\Users\me> .\tahoe\Scripts\activate
|
||||
(tahoe) PS C:\Users\me>
|
||||
|
||||
4: Use `pip` to install the latest release of Tahoe-LAFS into this virtualenv:
|
||||
4: Use `pip` to install the latest release of Tahoe-LAFS into this
|
||||
virtualenv::
|
||||
|
||||
(tahoe) PS C:\Users\me> pip install --find-links=https://tahoe-lafs.org/deps/ tahoe-lafs
|
||||
Collecting tahoe-lafs
|
||||
@ -38,7 +47,7 @@ Installation
|
||||
Successfully installed ...
|
||||
(tahoe) PS C:\Users\me>
|
||||
|
||||
5: Verify that Tahoe was installed correctly by running `tahoe --version`:
|
||||
5: Verify that Tahoe was installed correctly by running `tahoe --version`::
|
||||
|
||||
(tahoe) PS C:\Users\me> tahoe --version
|
||||
tahoe-lafs: 1.11
|
||||
@ -47,23 +56,36 @@ Installation
|
||||
Running Tahoe-LAFS
|
||||
------------------
|
||||
|
||||
The rest of the documentation assumes you can run the `tahoe` executable just as you did in step 5 above. If you start a new shell (say, the next time your boot your computer), you'll need to re-activate the virtualenv as you did in step 3.
|
||||
The rest of the documentation assumes you can run the `tahoe` executable just
|
||||
as you did in step 5 above. If you start a new shell (say, the next time your
|
||||
boot your computer), you'll need to re-activate the virtualenv as you did in
|
||||
step 3.
|
||||
|
||||
Now use the docs in `running.rst`_ to learn how to configure your first Tahoe node.
|
||||
Now use the docs in `running.rst`_ to learn how to configure your first Tahoe
|
||||
node.
|
||||
|
||||
Installing A Different Version
|
||||
------------------------------
|
||||
|
||||
The `pip install tahoe-lafs` command above will install the latest release (from PyPI). If instead, you want to install from a git checkout, then run the following command (in an activated virtualenv, from the root of your git checkout):
|
||||
|
||||
The `pip install tahoe-lafs` command above will install the latest release
|
||||
(from PyPI). If instead, you want to install from a git checkout, then run
|
||||
the following command (in an activated virtualenv, from the root of your git
|
||||
checkout)::
|
||||
|
||||
$ (tahoe) pip install --find-links=https://tahoe-lafs.org/deps/ .
|
||||
|
||||
If you're planning to hack on the source code, you might want to add `--editable` so you won't have to re-install each time you make a change.
|
||||
If you're planning to hack on the source code, you might want to add
|
||||
`--editable` so you won't have to re-install each time you make a change.
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
Tahoe-LAFS depends upon several packages that use compiled C code, such as zfec, pycryptopp, and others. This code must be built separately for each platform (Windows, OS-X, and different flavors of Linux).
|
||||
Tahoe-LAFS depends upon several packages that use compiled C code, such as
|
||||
zfec, pycryptopp, and others. This code must be built separately for each
|
||||
platform (Windows, OS-X, and different flavors of Linux).
|
||||
|
||||
Pre-compiled "wheels" of all Tahoe's dependencies are hosted on the tahoe-lafs.org website in the `deps/` directory. The `--find-links=` argument (used in the examples above) instructs `pip` to look at that URL for dependencies. This should avoid the need for anything to be compiled during the install.
|
||||
Pre-compiled "wheels" of all Tahoe's dependencies are hosted on the
|
||||
tahoe-lafs.org website in the `deps/` directory. The `--find-links=` argument
|
||||
(used in the examples above) instructs `pip` to look at that URL for
|
||||
dependencies. This should avoid the need for anything to be compiled during
|
||||
the install.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user