docs/magic-folder-howto.rst

   1 =========================
   2 Magic Folder Set-up Howto
   3 =========================
   4
   5 1.  `Preparation`_
   6 2.  `Setting up a local test grid`_
   7 3.  `Setting up Magic Folder`_
   8 4.  `Testing`_
   9
  10
  11 Preparation
  12 ===========
  13
  14 Linux
  15 -----
  16
  17 Install ``git`` from your distribution's package manager.
  18 Then run these commands::
  19
  20   git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
  21   cd tahoe-lafs
  22   python setup.py test
  23
  24 The test suite usually takes about 15 minutes to run.
  25 Note that it is normal for some tests to be skipped.
  26 In the current branch, the Magic Folder tests produce
  27 considerable debugging output.
  28
  29 If you see an error like ``fatal error: Python.h: No such file or directory``
  30 while compiling the dependencies, you need the Python development headers. If
  31 you are on a Debian or Ubuntu system, you can install them with ``sudo
  32 apt-get install python-dev``. On RedHat/Fedora, install ``python-devel``.
  33
  34
  35 Windows
  36 -------
  37
  38 Windows 7 or above is required.
  39
  40 For 64-bit Windows:
  41
  42 * Install Python 2.7 from
  43   https://www.python.org/ftp/python/2.7/python-2.7.amd64.msi
  44 * Install pywin32 from
  45   https://tahoe-lafs.org/source/tahoe-lafs/deps/windows/pywin32-219.win-amd64-py2.7.exe
  46 * Install git from
  47   https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-64-bit.exe
  48
  49 For 32-bit Windows:
  50
  51 * Install Python 2.7 from
  52   https://www.python.org/ftp/python/2.7/python-2.7.msi
  53 * Install pywin32 from
  54   https://tahoe-lafs.org/source/tahoe-lafs/deps/windows/pywin32-219.win32-py2.7.exe
  55 * Install git from
  56   https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-32-bit.exe
  57
  58 Then (for any version) run these commands in a Command Prompt::
  59
  60   git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
  61   cd tahoe-lafs
  62   python setup.py build
  63
  64 Open a new Command Prompt with the same current directory,
  65 then run::
  66
  67   bin\tahoe --version-and-path
  68
  69 It is normal for this command to print warnings and
  70 debugging output on some systems. Do not run
  71 ``python setup.py test``, because it currently hangs on
  72 Windows.
  73
  74
  75 Setting up a local test grid
  76 ============================
  77
  78 Linux
  79 -----
  80
  81 Run these commands::
  82
  83   mkdir ../grid
  84   bin/tahoe create-introducer ../grid/introducer
  85   bin/tahoe start ../grid/introducer
  86   export FURL=`cat ../grid/introducer/private/introducer.furl`
  87   bin/tahoe create-node --introducer="$FURL" ../grid/server
  88   bin/tahoe create-client --introducer="$FURL" ../grid/alice
  89   bin/tahoe create-client --introducer="$FURL" ../grid/bob
  90
  91
  92 Windows
  93 -------
  94
  95 Run::
  96
  97   mkdir ..\grid
  98   bin\tahoe create-introducer ..\grid\introducer
  99   bin\tahoe start ..\grid\introducer
 100
 101 Leave the introducer running in that Command Prompt,
 102 and in a separate Command Prompt (with the same current
 103 directory), run::
 104
 105   set /p FURL=<..\grid\introducer\private\introducer.furl
 106   bin\tahoe create-node --introducer=%FURL% ..\grid\server
 107   bin\tahoe create-client --introducer=%FURL% ..\grid\alice
 108   bin\tahoe create-client --introducer=%FURL% ..\grid\bob
 109
 110
 111 Both Linux and Windows
 112 ----------------------
 113
 114 (Replace ``/`` with ``\`` for Windows paths.)
 115
 116 Edit ``../grid/alice/tahoe.cfg``, and make the following
 117 changes to the [node] and [client] sections::
 118
 119   [node]
 120   nickname = alice
 121   web.port = tcp:3457:interface=127.0.0.1
 122
 123   [client]
 124   shares.needed = 1
 125   shares.happy = 1
 126   shares.total = 1
 127
 128 Edit ``../grid/bob/tahoe.cfg``, and make the following
 129 change to the ``[node]`` section, and the same change as
 130 above to the ``[client]`` section::
 131
 132   [node]
 133   nickname = bob
 134   web.port = tcp:3458:interface=127.0.0.1
 135
 136 Note that when running nodes on a single machine,
 137 unique port numbers must be used for each node (and they
 138 must not clash with ports used by other server software).
 139 Here we have used the default of 3456 for the server,
 140 3457 for alice, and 3458 for bob.
 141
 142 Now start all of the nodes (the introducer should still be
 143 running from above)::
 144
 145   bin/tahoe start ../grid/server
 146   bin/tahoe start ../grid/alice
 147   bin/tahoe start ../grid/bob
 148
 149 On Windows, a separate Command Prompt is needed to run each
 150 node.
 151
 152 Open a web browser on http://127.0.0.1:3456/ and verify that
 153 alice is connected to the introducer and one storage server.
 154 Then do the same for http://127.0.0.1:3567/ to verify that
 155 bob is connected. Leave all of the nodes running for the
 156 next stage.
 157
 158
 159 Setting up Magic Folder
 160 =======================
 161
 162 Linux
 163 -----
 164
 165 Run::
 166
 167   mkdir -p ../local/alice ../local/bob
 168   bin/tahoe -d ../grid/alice magic-folder create magic: alice ../local/alice
 169   bin/tahoe -d ../grid/alice magic-folder invite magic: bob >invitecode
 170   export INVITECODE=`cat invitecode`
 171   bin/tahoe -d ../grid/bob magic-folder join "$INVITECODE" bob ../local/bob
 172
 173   bin/tahoe restart ../grid/alice
 174   bin/tahoe restart ../grid/bob
 175
 176 Windows
 177 -------
 178
 179 Run::
 180
 181   mkdir ..\local\alice ..\local\bob
 182   bin\tahoe -d ..\grid\alice magic-folder create magic: alice ..\local\alice
 183   bin\tahoe -d ..\grid\alice magic-folder invite magic: bob >invitecode
 184   set /p INVITECODE=<invitecode
 185   bin\tahoe -d ..\grid\bob magic-folder join %INVITECODE% bob ..\local\bob
 186
 187 Then close the Command Prompt windows that are running the alice and bob
 188 nodes, and open two new ones in which to run::
 189
 190   bin\tahoe start ..\grid\alice
 191   bin\tahoe start ..\grid\bob
 192
 193
 194 Testing
 195 =======
 196
 197 You can now experiment with creating files and directories in
 198 ``../local/alice`` and ``/local/bob``; any changes should be
 199 propagated to the other directory.
 200
 201 Note that when a file is deleted, the corresponding file in the
 202 other directory will be renamed to a filename ending in ``.backup``.
 203 Deleting a directory will have no effect.
 204
 205 Subdirectories do not currently work on Windows.
 206
 207 For other known issues and limitations, see
 208 https://github.com/tahoe-lafs/tahoe-lafs/blob/2438.magic-folder-stable.5/docs/frontends/magic-folder.rst#known-issues-and-limitations
 209
 210 For simplicity, this Howto covers only using Magic Folder using a
 211 test grid on a single machine, with two clients and one server.
 212 It should also be possible to run the nodes on different machines,
 213 to synchronize between three or more clients, to mix Windows and
 214 Linux clients, and to use multiple servers (if the Tahoe-LAFS
 215 encoding parameters are changed).