From ef4049f929209764b25b527ce34aff97f61df975 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 28 Oct 2015 16:54:37 +0000 Subject: [PATCH] Add docs/magic-folder-howto.rst. Signed-off-by: Daira Hopwood --- docs/magic-folder-howto.rst | 215 ++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/magic-folder-howto.rst diff --git a/docs/magic-folder-howto.rst b/docs/magic-folder-howto.rst new file mode 100644 index 00000000..48c12f0d --- /dev/null +++ b/docs/magic-folder-howto.rst @@ -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=