1 =========================
2 Magic Folder Set-up Howto
3 =========================
7 3. `Setting up a local test grid`_
8 4. `Setting up Magic Folder`_
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.
20 For an introduction to Magic Folder and how to configure it
21 more generally, see `docs/frontends/magic-folder.rst`_.
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).
28 .. _`docs/frontends/magic-folder.rst`: ../docs/frontends/magic-folder.rst
37 Install ``git`` from your distribution's package manager.
38 Then run these commands::
40 git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
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.
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``.
58 Windows 7 or above is required.
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
67 https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-64-bit.exe
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
76 https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-32-bit.exe
78 Then (for any version) run these commands in a Command Prompt::
80 git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
84 Open a new Command Prompt with the same current directory,
87 bin\tahoe --version-and-path
89 It is normal for this command to print warnings and
90 debugging output on some systems. Do not run
91 ``python setup.py test``, because it currently hangs on
95 Setting up a local test grid
96 ============================
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
118 bin\tahoe create-introducer ..\grid\introducer
119 bin\tahoe start ..\grid\introducer
121 Leave the introducer running in that Command Prompt,
122 and in a separate Command Prompt (with the same current
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
131 Both Linux and Windows
132 ----------------------
134 (Replace ``/`` with ``\`` for Windows paths.)
136 Edit ``../grid/alice/tahoe.cfg``, and make the following
137 changes to the ``[node]`` and ``[client]`` sections::
141 web.port = tcp:3457:interface=127.0.0.1
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::
154 web.port = tcp:3458:interface=127.0.0.1
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.
162 Now start all of the nodes (the introducer should still be
163 running from above)::
165 bin/tahoe start ../grid/server
166 bin/tahoe start ../grid/alice
167 bin/tahoe start ../grid/bob
169 On Windows, a separate Command Prompt is needed to run each
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
179 Setting up Magic Folder
180 =======================
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
193 bin/tahoe restart ../grid/alice
194 bin/tahoe restart ../grid/bob
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
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::
210 bin\tahoe start ..\grid\alice
211 bin\tahoe start ..\grid\bob
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.
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.
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
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).