docs/magic-folder-howto.rst

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