Add docs/magic-folder-howto.rst.
Signed-off-by: Daira Hopwood <daira@jacaranda.org>
This commit is contained in:
Daira Hopwood
Brian Warner
parent
f77c593177
commit
278d713dd5
|
|
@ -0,0 +1,215 @@
|
|||
=========================
|
||||
Magic Folder Set-up Howto
|
||||
=========================
|
||||
|
||||
1. `Preparation`_
|
||||
2. `Setting up a local test grid`_
|
||||
3. `Setting up Magic Folder`_
|
||||
4. `Testing`_
|
||||
|
||||
|
||||
Preparation
|
||||
===========
|
||||
|
||||
Linux
|
||||
-----
|
||||
|
||||
Install ``git`` from your distribution's package manager.
|
||||
Then run these commands:
|
||||
|
||||
git clone -b 2438.magic-folder-stable.5 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. Do not run
|
||||
"python setup.py test", because it currently hangs on
|
||||
Windows.
|
||||
|
||||
|
||||
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:3456/ and verify that
|
||||
alice is connected to the introducer and one storage server.
|
||||
Then do the same for http://127.0.0.1:3567/ 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" bob ../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% bob ..\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.
|
||||
|
||||
Subdirectories do not currently work on Windows.
|
||||
|
||||
For other known issues and limitations, see
|
||||
https://github.com/tahoe-lafs/tahoe-lafs/blob/2438.magic-folder-stable.5/docs/frontends/magic-folder.rst#known-issues-and-limitations
|
||||
|
||||
For simplicity, this Howto covers only using Magic Folder using a
|
||||
test grid on a single machine, with two clients and one server.
|
||||
It should also be 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).
|
||||
Loading…
Reference in New Issue