source: trunk/docs/INSTALL.rst

Last change on this file was e4275980, checked in by Jean-Paul Calderone <exarkun@…>, at 2020-11-19T14:12:56Z

Don't recommend tahoe-lafs.org/deps to folks in the install docs

  • Property mode set to 100644
File size: 10.7 KB
Line 
1.. -*- coding: utf-8-with-signature-unix; fill-column: 77 -*-
2
3..
4    note: if you aren't reading the rendered form of these docs at
5    http://tahoe-lafs.readthedocs.io/en/latest/ , then be aware that any
6    ":doc:" links refer to other files in this docs/ directory
7
8*********************
9Installing Tahoe-LAFS
10*********************
11
12Welcome to `the Tahoe-LAFS project`_, a secure, decentralized, fault-tolerant
13storage system. See :doc:`about` for an overview of the architecture and
14security properties of the system.
15
16This procedure should work on Windows, Mac, illumos (previously OpenSolaris),
17and too many flavors of Linux and of BSD to list.
18
19.. _the Tahoe-LAFS project: https://tahoe-lafs.org
20
21First: In Case Of Trouble
22=========================
23
24In some cases these instructions may fail due to peculiarities of your
25platform.
26
27If the following instructions don't Just Work without any further effort on
28your part, then please write to `the tahoe-dev mailing list`_ where friendly
29hackers will help you out.
30
31.. _the tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev
32
33Pre-Packaged Versions
34=====================
35
36You may not need to build Tahoe at all.
37
38If you are on Windows, please see :doc:`windows` for platform-specific
39instructions.
40
41If you are on a Mac, you can either follow these instructions, or use the
42pre-packaged bundle described in :doc:`OS-X`.
43
44Many Linux distributions include Tahoe-LAFS packages. Debian and Ubuntu users
45can ``apt-get install tahoe-lafs``. See `OSPackages`_ for other
46platforms.
47
48.. _OSPackages: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/OSPackages
49
50
51Preliminaries
52=============
53
54If you don't use a pre-packaged copy of Tahoe, you can build it yourself.
55You'll need Python2.7, pip, and virtualenv.
56Tahoe-LAFS depends on some libraries which require a C compiler to build.
57However, for many platforms, PyPI hosts already-built packages of libraries.
58
59If there is no already-built package for your platform,
60you will need a C compiler,
61the Python development headers,
62and some libraries (libffi-dev and libssl-dev).
63
64On a modern Debian/Ubuntu-derived distribution, this command will get you
65everything you need::
66
67    apt-get install build-essential python-dev libffi-dev libssl-dev libyaml-dev python-virtualenv
68
69On OS-X, install pip and virtualenv as described below. If you want to
70compile the dependencies yourself, you'll also need to install
71Xcode and its command-line tools.
72
73**Note** that Tahoe-LAFS depends on `openssl 1.1.1c` or greater.
74
75Python 2.7
76----------
77
78Check if you already have an adequate version of Python installed by running
79``python -V``. The latest version of Python v2.7 is recommended, which is
802.7.11 as of this writing. Python v2.6.x and v3 do not work. On Windows, we
81recommend the use of native Python v2.7, not Cygwin Python. If you don't have
82one of these versions of Python installed, `download`_ and install the latest
83version of Python v2.7. Make sure that the path to the installation directory
84has no spaces in it (e.g. on Windows, do not install Python in the "Program
85Files" directory)::
86
87    % python --version
88    Python 2.7.11
89
90.. _download: https://www.python.org/downloads/
91
92pip
93---
94
95Many Python installations already include ``pip``, but in case yours does
96not, get it with the `pip install instructions`_::
97
98    % pip --version
99    pip 10.0.1 from ... (python 2.7)
100
101.. _pip install instructions: https://pip.pypa.io/en/stable/installing/
102
103virtualenv
104----------
105
106If you do not have an OS-provided copy of ``virtualenv``, install it with the
107instructions from the `virtualenv documentation`_::
108
109
110    % virtualenv --version
111    15.1.0
112
113.. _virtualenv documentation: https://virtualenv.pypa.io/en/latest/installation.html
114
115C compiler and libraries
116------------------------
117
118Except on OS-X, where the Tahoe project hosts pre-compiled wheels for all
119dependencies, you will need several C libraries installed before you can
120build. You will also need the Python development headers, and a C compiler
121(your python installation should know how to find these).
122
123On Debian/Ubuntu-derived systems, the necessary packages are ``python-dev``,
124``libffi-dev``, and ``libssl-dev``, and can be installed with ``apt-get``. On
125RPM-based system (like Fedora) these may be named ``python-devel``, etc,
126instead, and cam be installed with ``yum`` or ``rpm``.
127
128**Note** that Tahoe-LAFS depends on `openssl 1.1.1c` or greater.
129
130
131Install the Latest Tahoe-LAFS Release
132=====================================
133
134We recommend creating a fresh virtualenv for your Tahoe-LAFS install, to
135isolate it from any python packages that are already installed (and to
136isolate the rest of your system from Tahoe's dependencies).
137
138This example uses a virtualenv named ``venv``, but you can call it anything
139you like. Many people prefer to keep all their virtualenvs in one place, like
140``~/.local/venvs/`` or ``~/venvs/``.
141
142It's usually a good idea to upgrade the virtualenv's ``pip`` and
143``setuptools`` to their latest versions, with ``venv/bin/pip install -U pip
144setuptools``. Many operating systems have an older version of ``virtualenv``,
145which then includes older versions of pip and setuptools. Upgrading is easy,
146and only affects the virtualenv: not the rest of your computer.
147
148Then use the virtualenv's ``pip`` to install the latest Tahoe-LAFS release
149from PyPI with ``venv/bin/pip install tahoe-lafs``. After installation, run
150``venv/bin/tahoe --version`` to confirm the install was successful::
151
152 % virtualenv venv
153 New python executable in ~/venv/bin/python2.7
154 Installing setuptools, pip, wheel...done.
155
156 % venv/bin/pip install -U pip setuptools
157 Downloading/unpacking pip from https://pypi.python.org/...
158 ...
159 Successfully installed pip setuptools
160
161 % venv/bin/pip install tahoe-lafs
162 Collecting tahoe-lafs
163 ...
164 Installing collected packages: ...
165 Successfully installed ...
166
167 % venv/bin/tahoe --version
168 tahoe-lafs: 1.14.0
169 foolscap: ...
170
171 %
172
173Install From a Source Tarball
174-----------------------------
175
176You can also install directly from the source tarball URL::
177
178 % virtualenv venv
179 New python executable in ~/venv/bin/python2.7
180 Installing setuptools, pip, wheel...done.
181
182 % venv/bin/pip install https://tahoe-lafs.org/downloads/tahoe-lafs-1.14.0.tar.bz2
183 Collecting https://tahoe-lafs.org/downloads/tahoe-lafs-1.14.0.tar.bz2
184 ...
185 Installing collected packages: ...
186 Successfully installed ...
187
188 % venv/bin/tahoe --version
189 tahoe-lafs: 1.14.0
190 ...
191
192Extras
193------
194
195Tahoe-LAFS provides some functionality only when explicitly requested at installation time.
196It does this using the "extras" feature of setuptools.
197You can request these extra features when running the ``pip install`` command like this::
198
199  % venv/bin/pip install tahoe-lafs[tor]
200
201This example enables support for listening and connecting using Tor.
202The Tahoe-LAFS documentation for specific features which require an explicit install-time step will mention the "extra" that must be requested.
203
204Hacking On Tahoe-LAFS
205---------------------
206
207To modify the Tahoe source code, you should get a git checkout, and install
208with the ``--editable`` flag. You should also use the ``[test]`` extra to get
209the additional libraries needed to run the unit tests::
210
211 % git clone https://github.com/tahoe-lafs/tahoe-lafs.git
212
213 % cd tahoe-lafs
214
215 % virtualenv venv
216
217 % venv/bin/pip install --editable .[test]
218 Obtaining file::~/tahoe-lafs
219 ...
220 Successfully installed ...
221
222 % venv/bin/tahoe --version
223 tahoe-lafs: 1.14.0.post34.dev0
224 ...
225
226This way, you won't have to re-run the ``pip install`` step each time you
227modify the source code.
228
229Running the ``tahoe`` executable
230================================
231
232The rest of the Tahoe-LAFS documentation assumes that you can run the
233``tahoe`` executable that you just created. You have four basic options:
234
235* Use the full path each time (e.g. ``~/venv/bin/tahoe``).
236* "`Activate`_" the virtualenv with ``. venv/bin/activate``, to get a
237  subshell with a ``$PATH`` that includes the ``venv/bin/`` directory, then
238  you can just run ``tahoe``.
239* Change your ``$PATH`` to include the ``venv/bin/`` directory, so you can
240  just run ``tahoe``.
241* Symlink from ``~/bin/tahoe`` to the ``tahoe`` executable. Since ``~/bin``
242  is typically in your ``$PATH`` (at least if it exists when you log in),
243  this will let you just run ``tahoe``.
244
245You might also find the `pipsi`_ tool convenient: ``pipsi install
246tahoe-lafs`` will create a new virtualenv, install tahoe into it, then
247symlink just the executable (into ``~/.local/bin/tahoe``). Then either add
248``~/.local/bin/`` to your ``$PATH``, or make one last symlink into
249``~/bin/tahoe``.
250
251.. _Activate: https://virtualenv.pypa.io/en/latest/userguide.html#activate-script
252.. _pipsi: https://pypi.python.org/pypi/pipsi/0.9
253
254Running the Self-Tests
255======================
256
257To run the self-tests from a source tree, you'll need ``tox`` installed. On a
258Debian/Ubuntu system, use ``apt-get install tox``. You can also install it
259into your tahoe-specific virtualenv with ``pip install tox``.
260
261Then just run ``tox``. This will create a new fresh virtualenv, install Tahoe
262(from the source tree, including any changes you have made) and all its
263dependencies (including testing-only dependencies) into the virtualenv, then
264run the unit tests. This ensures that the tests are repeatable and match the
265results of other users, unaffected by any other Python packages installed on
266your machine. On a modern computer this will take 5-10 minutes, and should
267result in a "all tests passed" mesage::
268
269 % tox
270 GLOB sdist-make: ~/tahoe-lafs/setup.py
271 py27 recreate: ~/tahoe-lafs/.tox/py27
272 py27 inst: ~/tahoe-lafs/.tox/dist/tahoe-lafs-1.14.0.post8.dev0.zip
273 py27 runtests: commands[0] | tahoe --version
274 py27 runtests: commands[1] | trial --rterrors allmydata
275 allmydata.test.test_auth
276   AccountFileCheckerKeyTests
277     test_authenticated ...                                           [OK]
278     test_missing_signature ...                                       [OK]
279  ...
280 Ran 1186 tests in 423.179s
281
282 PASSED (skips=7, expectedFailures=3, successes=1176)
283 __________________________ summary ___________________________________
284   py27: commands succeeded
285   congratulations :)
286
287Common Problems
288===============
289
290If you see an error like ``fatal error: Python.h: No such file or directory``
291while compiling the dependencies, you need the Python development headers. If
292you are on a Debian or Ubuntu system, you can install them with ``sudo
293apt-get install python-dev``. On RedHat/Fedora, install ``python-devel``.
294
295Similar errors about ``openssl/crypto.h`` indicate that you are missing the
296OpenSSL development headers (``libssl-dev``). Likewise ``ffi.h`` means you
297need ``libffi-dev``.
298
299**Note** that Tahoe-LAFS depends on `openssl 1.1.1c` or greater.
300
301
302Using Tahoe-LAFS
303================
304
305Now you are ready to deploy a decentralized filesystem. You will use the
306``tahoe`` executable to create, configure, and launch your Tahoe-LAFS nodes.
307See :doc:`running` for instructions on how to do that.
Note: See TracBrowser for help on using the repository browser.