1 =========================
2 Magic Folder Set-up Howto
3 =========================
6 2. `Setting up a local test grid`_
7 3. `Setting up Magic Folder`_
17 Install ``git`` from your distribution's package manager.
18 Then run these commands::
20 git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
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.
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``.
38 Windows 7 or above is required.
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
47 https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-64-bit.exe
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
56 https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-32-bit.exe
58 Then (for any version) run these commands in a Command Prompt::
60 git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
64 Open a new Command Prompt with the same current directory,
67 bin\tahoe --version-and-path
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
75 Setting up a local test grid
76 ============================
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
98 bin\tahoe create-introducer ..\grid\introducer
99 bin\tahoe start ..\grid\introducer
101 Leave the introducer running in that Command Prompt,
102 and in a separate Command Prompt (with the same current
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
111 Both Linux and Windows
112 ----------------------
114 (Replace ``/`` with ``\`` for Windows paths.)
116 Edit ``../grid/alice/tahoe.cfg``, and make the following
117 changes to the [node] and [client] sections::
121 web.port = tcp:3457:interface=127.0.0.1
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::
134 web.port = tcp:3458:interface=127.0.0.1
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.
142 Now start all of the nodes (the introducer should still be
143 running from above)::
145 bin/tahoe start ../grid/server
146 bin/tahoe start ../grid/alice
147 bin/tahoe start ../grid/bob
149 On Windows, a separate Command Prompt is needed to run each
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
159 Setting up Magic Folder
160 =======================
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
173 bin/tahoe restart ../grid/alice
174 bin/tahoe restart ../grid/bob
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
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::
190 bin/tahoe start ..\grid\alice
191 bin/tahoe start ..\grid\bob
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.
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.
205 Subdirectories do not currently work on Windows.
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
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).