see also wiki:Packaging and wiki:OSPackages

Advanced Install

1. Additional Build/Install Documentation
2. Packaged By The Operating System
3. Dependencies
4. Overview
5. The "Desert Island" Build
6. Installing Outside The Source Tree
  6.1. Installing The Latest Release
  6.2. easy_install
  6.3. Debian software package (deb)
  6.4. Windows
7. Installing From A Source Tree
  7.1. Creating a binary distribution From A Source Tree
8. Testing
9. Platform-specific Notes
  9.1. Debian/Ubuntu
  9.2. CentOS 5.4
    9.2.1 Dependencies
  9.3. MacOS
  9.4. Windows
    9.4.1. What if that doesn't work?
    9.4.2. How do I make it run as a Windows service?
    9.4.3. How do I make it run under a different user account?

Additional Build/Install Documentation

The quick start docs in docs/quickstart.rst are sufficient to get Tahoe-LAFS running on all platforms. This wiki page is only for advanced, optional installation features and you should not read this page if all you want is to get Tahoe-LAFS running. If you have trouble getting it to work by following docs/quickstart.rst then please write to ​the tahoe-dev mailing list and ask for help.

Zooko writing: I do not take any responsibility for the contents of this page -- wiki:AdvancedInstall. In my opinion it contains some bits of bad advice and obsolete statements. I don't take the time to monitor or edit this page. I would advise you to follow docs/quickstart.rst instead, and if that doesn't work then email the tahoe-dev list for help.

P.S. If anyone *does* maintain this page, then I don't want to be rude by leaving this negative comment here on your page. Next time you're doing clean-up and modernization of the content, you could remove this, or move it the bottom, or whatever. Of course, if nobody ever does clean-up of the content of this page, then this comment will still be here.

Please feel free to add sections to this page with anything you might learn while building Tahoe-LAFS. Information which may be useful in the most general cases will be folded into docs/quickstart.rst .

Also note that this page is updated less frequently than quickstart.rst and may contain some stale information.

Packaged By The Operating System

Tahoe-LAFS is already integrated into some operating systems. See the OSPackages page.

Dependencies

The canonical list of dependencies and their versions is in src/allmydata/_auto_deps.py. To see the current versions of those dependencies (plus a few others like the Python interpreter and the operating system) run tahoe --version.

This isn't a complete list of dependencies though, because some of those packages also have dependencies of their own. To see the complete list of all dependencies, run PYTHONPATH=${PYTHONPATH}:./support/lib/python2.5/site-packages/ python -c "import pkg_resources;print ', '.join([d.project_name+': '+d.version for d in set(pkg_resources.require('allmydata-tahoe'))])". An example output from that command is:

zope.interface: 3.5.0, simplejson: 2.0.7, pyutil: 1.3.30, zbase32: 1.1.1, allmydata-tahoe: 1.2.0-r3353, pyOpenSSL: 0.7, Twisted: 8.1.0-r25700, Nevow: 0.9.33-r17166, foolscap: 0.3.2, zfec: 1.4.2, pycryptopp: 0.5.12, argparse: 0.8.0, setuptools: 0.6c10dev

Prior to Tahoe-LAFS v1.9.0, users running on Microsoft Windows also needed to manually install ​pywin32. This should no longer be needed.

Overview

Tahoe-LAFS is happy to build and run in-place, from a source tree. It is not necessary to install it (outside the source tree) before use, but if you'd like to do so, please read the "Installing Outside The Source Tree" section below.

However, it does need to be "built" before running it in place. While Tahoe-LAFS itself is pure-python and therefore does not require a distinct compile step, the mechanics that make it easy to run-in-place do require a setup phase. In addition, Tahoe-LAFS uses several third-party python libraries to work its magic, many of which are unlikely to be just "lying around" and already installed. Several of these use compiled C code, so they do require a compile step.

python setup.py build will download and build any third-party libraries that are not already available on your system. It will also prepare the source tree for running-in-place. This basically does a "setup.py develop" into a local ./support/lib/python2.5/site-packages/ directory. The bin/tahoe executable knows that it adds this directory to PYTHONPATH before it does anything else.

If you need to use an HTTP proxy to access the web, set the http_proxy environment variable accordingly. For example in Unix: http_proxy=host:port python setup.py build.

After building, you can run the source tree's bin/tahoe script to create, configure, and use your new Tahoe-LAFS node. As long as bin/tahoe is left inside the built source tree, it can be run from anywhere (even through a symlink). So until you delete the source tree, you can symlink ~/bin/tahoe to your source tree's bin/tahoe and then use it as you would any other system executable.

The "Desert Island" Build

Tahoe-LAFS will download and install most of the libraries it requires when you run "python setup.py build". You might want to pre-download these libraries: perhaps you are about to get on an airplane, or you anticipate having poor network connectivity, or you just don't like the idea of a so-called compile step using the network (the download step uses !PyPI to figure out where to download these libraries from, so you might be concerned that it or one of the project web pages it references has been modified to point at something malicious).

This disconnected-build operation is supported in two ways. When building from a darcs checkout, you can download the latest "tahoe-deps" bundle from ​http://tahoe-lafs.org/source/tahoe-lafs/deps/tahoe-deps.tar.gz . Unpack this in your source tree, and the build process will grab any necessary libraries from its tahoe-deps/ directory instead of downloading them from the internet. You can also unpack tahoe-deps into the parent directory to share it between multiple trees.

Alternatively, if you are building from a tarball (either a release tarball from ​http://tahoe-lafs.org/source/tahoe-lafs/releases/ , or a continually-generated current-trunk tarball from ​http://tahoe-lafs.org/source/tahoe-lafs/tarballs/ ), you can simply download the -SUMO version of the tarball instead of the regular one. The "SUMO" tarball includes the current tahoe-deps bundle pre-unpacked in the source tree.

The tahoe-deps bundle is updated every once in a while, as new versions of the dependent libraries are released, or as Tahoe becomes dependent upon new things. The ​http://tahoe-lafs.org/source/tahoe-lafs/deps/ directory contains historical ones, but there should never be a reason to use anything but the latest. The tahoe-deps bundle contains a README that has a version number.

Installing Outside The Source Tree

If you want to use Tahoe-LAFS without keeping the source tree around, you will need to actually install it somewhere. You have several options:

Installing The Latest Release

easy_install

"easy_install allmydata-tahoe", on any system that has easy_install and setuptools installed, will download the latest release of Tahoe-LAFS (and its dependencies, all found via PyPI), build everything, and install it into the standard place for python libraries on your system. On unix platforms this usually goes into /usr/lib/python2.5/site-packages/ and /usr/bin/tahoe .

Debian software package (deb)

On Debian or Ubuntu linux systems, you can install pre-compiled packages by adding the tahoe-lafs.org APT repository to your /etc/apt/sources.list and installing the "allmydata-tahoe" package. See DownloadDebianPackages for details.

Windows

There used to be an installer for Windows, but we now recommend that Windows users just follow the ​quickstart instructions. The SMB-based ("WinFUSE") frontend that was provided by the AllMyData.com client is no longer available, since it depended on a closed-source library for which no open-source replacement was available. If you are interested in Windows filesystem integration, see tickets #1361 and #1111.

Installing From A Source Tree

These commands will take the current source tree and install its contents somewhere else on your system. This is the traditional meaning of "install".

The "setup.py install" target will install Tahoe-LAFS (and its dependencies) into the standard place for python libraries on your system: on Unix platforms this usually goes into /usr/lib/python2.5/site-packages/ and /usr/bin/tahoe .

The "make install" Makefile target is a wrapper around "setup.py install" that uses --single-version-externally-managed to bypass the extra checking that setuptools does. This allows "make install" to work somewhat more like traditional Unix software. However, once Tahoe has been installed this way, it may be difficult to get it to stop using the installed version even when using bin/tahoe from a different build directory; see #1258.

("make install PREFIX=/usr/local" does not currently work -- see #703.)

Creating a binary distribution From A Source Tree

These commands will take the current source tree and create a single-file installer (or some other form of binary distribution). The installer-like-thing can then be moved to some other system and installed there.

The "setup.py bdist_egg" command will create a single-file .egg in the dist/ directory, which can be manually copied onto your PYTHONPATH somewhere. The .egg will declare its dependencies, but will not include them: you must arrange for them to be installed before the .egg will be usable.

The "make deb-PLATFORM-head" target (i.e. make deb-hardy-head) will create a debian package with the current tree's Tahoe code. This .deb file will be placed in the parent directory. The debian package will declare dependencies on the other libraries that it needs (like foolscap and zfec), but it will not include any code from them. The allmydata.org APT repository (see DownloadDebianPackages for details) has packages for the dependencies that aren't already in Debian proper.

It is also possible to create a binary distribution using ​bb-freeze. Install bb-freeze, then in the root of a Tahoe source tree with full path <tahoedir>, on Windows do:

python setup.py build
set PYTHONPATH=<tahoedir>\support\Lib\site-packages;<tahoedir>\src
bb-freeze static\tahoe.py

or on Unix do:

python setup.py build
export PYTHONPATH=<tahoedir>/support/lib/pythonx.y/site-packages:<tahoedir>/src
bb-freeze static/tahoe.py

where x.y is your Python version. (This has not been tested on Unix.)

This should create a dist directory containing the bb-frozen distribution. The ​bbfreeze-users Google group may be able to help with general questions about bb-freeze.

Testing

Use python setup.py test to run the whole test suite. This will rebuild if necessary.

There are a few other supported ways to run tests:

• bin/tahoe debug trial. This will not rebuild (if a build was needed, some tests may fail). It accepts all of the same options as Twisted's trial script; use bin/tahoe debug trial --help to see help for these.
• python setup.py trial does the same thing as bin/tahoe debug trial, although it doesn't support all of the trial options (and the test suite must be specified using -s). It's supported mainly for backward compatibility.
• make test does the same thing as python setup.py test.
• make quicktest does the same thing as bin/tahoe debug trial.

Running trial directly is not supported because it will not necessarily put the correct libraries (the same ones that would be used by bin/tahoe) on Python's sys.path.

To run a subset of the tests after making a source change that does not require a rebuild, bin/tahoe debug trial <testsuite> is the quickest option.

To test an OS package manager's installation of Tahoe, use tahoe debug trial, where tahoe (not bin/tahoe) is the installed script. Currently this will produce a spurious failure in allmydata.test.test_runner.BinTahoe.test_the_right_code due to #1576, but all other tests should be valid.

Platform-specific Notes

Debian/Ubuntu

Tahoe-LAFS is primarily developed on Debian/Ubuntu machines. You can either build from source (as described by this page), or download pre-compiled debian packages for several distributions. See the DownloadDebianPackages page for details.

CentOS 5.4

For installing in CentOS 5.4 you need this list of package:

yum install gcc python-devel sqlite-devel gcc-c++ openssl-devel

Dependencies

cpp glibc-devel glibc-headers kernel-headers libgomp libstdc++-devel e2fsprogs-devel keyutils-libs-devel krb5-devel libselinux-devel libsepol-devel zlib-devel

MacOS

You will need the standard Xcode development tools installed, or at least GCC in order to build some dependencies.
Note that Xcode is quite large (2.5GB) so plan accordingly if you will need to download it.

Windows

The following procedure will build and run Tahoe-LAFS on Windows. (This is basically docs/quickstart.rst and part of docs/running.rst​ with Windows-specific paths spelled out.) Note that this assumes that you install Python in the default location (C:\Python27 for Python 2.7.x), if you choose another location you'll need to adjust the instructions below:

1. Download and install Python 2.7.3 (the x86 or x86-64 MSI installer link) from ​http://www.python.org/getit/releases/2.7.3/ .

2. Download the latest Tahoe-LAFS release from ​http://tahoe-lafs.org/source/tahoe-lafs/releases/. Unpack it in a convenient place, such as C:\tahoe-lafs.

3. Open a command prompt and cd to the top of the Tahoe-LAFS tree (e.g. cd \tahoe-lafs).

4. Run "C:\Python27\python setup.py build". Wait a bit until it stops working. Note that you need a working network connection because it will download various dependencies. Ignore any warnings.

5. Run "C:\tahoe-lafs\bin\tahoe create-client C:\tahoelafsbase". Choose an appropriate base directory.

6. Run "notepad C:\tahoelafsbase\tahoe.cfg" to edit your config file. After "introducer.furl = ", paste in the FURL of the introducer for the grid you want to connect to. See TestGrid to get the FURL of the introducer for the testgrid.

7. Run "C:\tahoe-lafs\bin\tahoe start C:\tahoelafsbase". Your node will start running and connect to the grid. The Windows firewall may ask whether or not to allow Python to make network connections. Say yes.

C:\Python27\python setup.py install can also optionally be used as on other platforms.

What if that doesn't work?

The build or install steps could result in an error that says a compiler is needed. If this happens and you are using Python 2.6 or Python 2.7, it is a packaging bug that should be reported to the tahoe-dev list. If you are using a different version of Python or want to compile the C/C++ components yourself, install the MinGW C/C++ compiler as follows (this only works for 32-bit Windows):

1. Download and install MinGW from ​http://sourceforge.net/projects/mingw/files/ (the main installer linked from the big green download button). The installer will prompt you for what components to install. You need the base components plus g++.

2. Early versions of 5.1.x of MinGW had a bug in the bundled Gnu assembler. If typing "as --version" at the command line gives "GNU assembler (GNU Binutils) 2.20", then you have an affected version. To fix this, download an upgrade to a newer version of MinGW which has GNU assembler (GNU Binutils) 2.20.51.20100613 or later.

3. Configure distutils to use MinGW. If you have another C/C++ compiler installed, such as the cygwin one, distutils may default to using it instead of the mingw one. To configure distutils to use mingw32, create a file called ​distutils.cfg in C:\Python26\lib\distutils, and put in that file (you may also need to use the script from ​this email in order to "register" the mingw compiler):

[build]
compiler=mingw32

4. Add the MinGW binary path to your PATH variable. To do that, go to the control panel (classic view), and double-click "System". Click on the "Advanced" tab (for Vista or later, click the "Advanced system settings" link on the left and accept the elevation prompt), then click the "Environment Variables" button. Scroll down to the "Path" variable in the "System Variables" list, double-click it, append ";C:\MinGW\bin" to the path, and "OK" out of all the dialogs. If you installed MinGW in some place other than C:\MinGW, adjust the path appropriately.

After installing the compilers, repeat the above instructions from step 4 (using a new command prompt to make sure that the environment variable setting has taken effect).

If you receive "error: Setup script exited with error: command 'gcc' failed with exit status 1" from python setup.py build, edit C:\Python27\Lib\distutils\cygwincompiler.py to remove all of the -mno-cygwin options, then try again (see ticket #1769). Don't do this unless it actually fails the first time round.

How do I make it run as a Windows service?

​http://agiletesting.blogspot.com/2005/09/running-python-script-as-windows.html

How do I make it run under a different user account?

1. Create the new user account if necessary.

2. Run tahoe through "runas":

   runas /user:Computer\Tahoeuser "bin\tahoe start C:\tahoe-basedir"
   

3. Adjust file system permissions as needed and possible (Home Editions of Windows lack user interfaces to modify permissions)