mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2024-12-25 15:41:06 +00:00
a7c50b104e
Signed-off-by: Daira Hopwood <daira@jacaranda.org>
232 lines
6.7 KiB
ReStructuredText
232 lines
6.7 KiB
ReStructuredText
=========================
|
|
Magic Folder Set-up Howto
|
|
=========================
|
|
|
|
1. `This document`_
|
|
2. `Preparation`_
|
|
3. `Setting up a local test grid`_
|
|
4. `Setting up Magic Folder`_
|
|
5. `Testing`_
|
|
|
|
|
|
This document
|
|
=============
|
|
|
|
This is preliminary documentation of how to set up the
|
|
Magic Folder pre-release using a test grid on a single Linux
|
|
or Windows machine, with two clients and one server. It is
|
|
aimed at a fairly technical audience.
|
|
|
|
For an introduction to Magic Folder and how to configure it
|
|
more generally, see `docs/frontends/magic-folder.rst`_.
|
|
|
|
It it possible to adapt these instructions to run the nodes on
|
|
different machines, to synchronize between three or more clients,
|
|
to mix Windows and Linux clients, and to use multiple servers
|
|
(if the Tahoe-LAFS encoding parameters are changed).
|
|
|
|
.. _`docs/frontends/magic-folder.rst`: ../docs/frontends/magic-folder.rst
|
|
|
|
|
|
Preparation
|
|
===========
|
|
|
|
Linux
|
|
-----
|
|
|
|
Install ``git`` from your distribution's package manager.
|
|
Then run these commands::
|
|
|
|
git clone -b 2438.magic-folder-stable.8 https://github.com/tahoe-lafs/tahoe-lafs.git
|
|
cd tahoe-lafs
|
|
python setup.py test
|
|
|
|
The test suite usually takes about 15 minutes to run.
|
|
Note that it is normal for some tests to be skipped.
|
|
In the current branch, the Magic Folder tests produce
|
|
considerable debugging output.
|
|
|
|
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``.
|
|
|
|
|
|
Windows
|
|
-------
|
|
|
|
Windows 7 or above is required.
|
|
|
|
For 64-bit Windows:
|
|
|
|
* Install Python 2.7 from
|
|
https://www.python.org/ftp/python/2.7/python-2.7.amd64.msi
|
|
* Install pywin32 from
|
|
https://tahoe-lafs.org/source/tahoe-lafs/deps/windows/pywin32-219.win-amd64-py2.7.exe
|
|
* Install git from
|
|
https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-64-bit.exe
|
|
|
|
For 32-bit Windows:
|
|
|
|
* Install Python 2.7 from
|
|
https://www.python.org/ftp/python/2.7/python-2.7.msi
|
|
* Install pywin32 from
|
|
https://tahoe-lafs.org/source/tahoe-lafs/deps/windows/pywin32-219.win32-py2.7.exe
|
|
* Install git from
|
|
https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-32-bit.exe
|
|
|
|
Then (for any version) run these commands in a Command Prompt::
|
|
|
|
git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
|
|
cd tahoe-lafs
|
|
python setup.py build
|
|
|
|
Open a new Command Prompt with the same current directory,
|
|
then run::
|
|
|
|
bin\tahoe --version-and-path
|
|
|
|
It is normal for this command to print warnings and debugging output
|
|
on some systems. ``python setup.py test`` can also be run, but there
|
|
are some known sources of nondeterministic errors in tests on Windows
|
|
that are unrelated to Magic Folder.
|
|
|
|
|
|
Setting up a local test grid
|
|
============================
|
|
|
|
Linux
|
|
-----
|
|
|
|
Run these commands::
|
|
|
|
mkdir ../grid
|
|
bin/tahoe create-introducer ../grid/introducer
|
|
bin/tahoe start ../grid/introducer
|
|
export FURL=`cat ../grid/introducer/private/introducer.furl`
|
|
bin/tahoe create-node --introducer="$FURL" ../grid/server
|
|
bin/tahoe create-client --introducer="$FURL" ../grid/alice
|
|
bin/tahoe create-client --introducer="$FURL" ../grid/bob
|
|
|
|
|
|
Windows
|
|
-------
|
|
|
|
Run::
|
|
|
|
mkdir ..\grid
|
|
bin\tahoe create-introducer ..\grid\introducer
|
|
bin\tahoe start ..\grid\introducer
|
|
|
|
Leave the introducer running in that Command Prompt,
|
|
and in a separate Command Prompt (with the same current
|
|
directory), run::
|
|
|
|
set /p FURL=<..\grid\introducer\private\introducer.furl
|
|
bin\tahoe create-node --introducer=%FURL% ..\grid\server
|
|
bin\tahoe create-client --introducer=%FURL% ..\grid\alice
|
|
bin\tahoe create-client --introducer=%FURL% ..\grid\bob
|
|
|
|
|
|
Both Linux and Windows
|
|
----------------------
|
|
|
|
(Replace ``/`` with ``\`` for Windows paths.)
|
|
|
|
Edit ``../grid/alice/tahoe.cfg``, and make the following
|
|
changes to the ``[node]`` and ``[client]`` sections::
|
|
|
|
[node]
|
|
nickname = alice
|
|
web.port = tcp:3457:interface=127.0.0.1
|
|
|
|
[client]
|
|
shares.needed = 1
|
|
shares.happy = 1
|
|
shares.total = 1
|
|
|
|
Edit ``../grid/bob/tahoe.cfg``, and make the following
|
|
change to the ``[node]`` section, and the same change as
|
|
above to the ``[client]`` section::
|
|
|
|
[node]
|
|
nickname = bob
|
|
web.port = tcp:3458:interface=127.0.0.1
|
|
|
|
Note that when running nodes on a single machine,
|
|
unique port numbers must be used for each node (and they
|
|
must not clash with ports used by other server software).
|
|
Here we have used the default of 3456 for the server,
|
|
3457 for alice, and 3458 for bob.
|
|
|
|
Now start all of the nodes (the introducer should still be
|
|
running from above)::
|
|
|
|
bin/tahoe start ../grid/server
|
|
bin/tahoe start ../grid/alice
|
|
bin/tahoe start ../grid/bob
|
|
|
|
On Windows, a separate Command Prompt is needed to run each
|
|
node.
|
|
|
|
Open a web browser on http://127.0.0.1:3457/ and verify that
|
|
alice is connected to the introducer and one storage server.
|
|
Then do the same for http://127.0.0.1:3568/ to verify that
|
|
bob is connected. Leave all of the nodes running for the
|
|
next stage.
|
|
|
|
|
|
Setting up Magic Folder
|
|
=======================
|
|
|
|
Linux
|
|
-----
|
|
|
|
Run::
|
|
|
|
mkdir -p ../local/alice ../local/bob
|
|
bin/tahoe -d ../grid/alice magic-folder create magic: alice ../local/alice
|
|
bin/tahoe -d ../grid/alice magic-folder invite magic: bob >invitecode
|
|
export INVITECODE=`cat invitecode`
|
|
bin/tahoe -d ../grid/bob magic-folder join "$INVITECODE" ../local/bob
|
|
|
|
bin/tahoe restart ../grid/alice
|
|
bin/tahoe restart ../grid/bob
|
|
|
|
Windows
|
|
-------
|
|
|
|
Run::
|
|
|
|
mkdir ..\local\alice ..\local\bob
|
|
bin\tahoe -d ..\grid\alice magic-folder create magic: alice ..\local\alice
|
|
bin\tahoe -d ..\grid\alice magic-folder invite magic: bob >invitecode
|
|
set /p INVITECODE=<invitecode
|
|
bin\tahoe -d ..\grid\bob magic-folder join %INVITECODE% ..\local\bob
|
|
|
|
Then close the Command Prompt windows that are running the alice and bob
|
|
nodes, and open two new ones in which to run::
|
|
|
|
bin\tahoe start ..\grid\alice
|
|
bin\tahoe start ..\grid\bob
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
You can now experiment with creating files and directories in
|
|
``../local/alice`` and ``/local/bob``; any changes should be
|
|
propagated to the other directory.
|
|
|
|
Note that when a file is deleted, the corresponding file in the
|
|
other directory will be renamed to a filename ending in ``.backup``.
|
|
Deleting a directory will have no effect.
|
|
|
|
For other known issues and limitations, see
|
|
https://github.com/tahoe-lafs/tahoe-lafs/blob/2438.magic-folder-stable.8/docs/frontends/magic-folder.rst#known-issues-and-limitations
|
|
|
|
As mentioned earlier, it is also possible to run the nodes on
|
|
different machines, to synchronize between three or more clients,
|
|
to mix Windows and Linux clients, and to use multiple servers
|
|
(if the Tahoe-LAFS encoding parameters are changed).
|