source: trunk/docs/INSTALL.rst

Last change on this file was 8f983cb, checked in by meejah <meejah@…>, at 2020-03-11T23:38:03Z

bump version to 1.14.0 and update release notes

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