Corrected mistake
[ikiwiki.git] / doc / tips / distributed_wikis.mdwn
1 [[rcs/git]] and other distributed version control systems are all about
2 making it easy to create and maintain copies and branches of a project. And
3 this can be used for all sorts of interesting stuff. Since ikiwiki can use
4 git, let's explore some possibilities for distributed wikis.
5
6 [[!toc levels=2]]
7
8 ## Overview
9
10 There are several possible level of decentralisation:
11
12  0. [[default setup|rcs/git]], no decentralisation
13  1. [[a simple HTML mirror|tips/Git_repository_and_web_server_on_different_hosts/]]
14  2. [[separate ikiwiki and git servers|tips/Hosting_Ikiwiki_and_master_git_repository_on_different_machines]]
15  3. separate `srcdir`, still requires a central bare repo - uses [[plugins/pinger]]
16  4. completely distinct ikiwiki installs, synchronised with [[plugins/contrib/gitpush]]
17
18 Here's a graphic overview of those:
19
20 ### Default setup - one central server
21
22 [[!img rcs/git/wiki_edit_flow.svg size=400x]]
23
24 In the default setup, all the resources are stored on the central
25 servers. Users can still clone and edit the git repo by hand and
26 contribute by git, but otherwise all the changes happen on a single
27 web interface. This basic setup is best described in [[rcs/git]].
28
29 ### Separate webserver and git repository
30
31 [[!img tips/Git_repository_and_web_server_on_different_hosts/separate-webserver.svg size=400x]]
32
33 This is the configuration described in
34 [[tips/Git_repository_and_web_server_on_different_hosts]]. The webserver part
35 hosts the HTML files, the ikiwiki [[cgi]] but everything else is on
36 the git server.
37
38 ### Separate ikiwiki web server, and git server
39
40 [[!img Hosting_Ikiwiki_and_master_git_repository_on_different_machines/separate-web-git-servers.svg size=400x]]
41 [[http://spalax.fr.eu.org/separate-web-git-servers.svg]] *Could someone with admin rights upload [[this image|http://spalax.fr.eu.org/separate-web-git-servers.svg]] to [[IkiWiki|Hosting_Ikiwiki_and_master_git_repository_on_different_machines/separate-web-git-servers.svg]]? I am not allowed to do so. [[Louis|spalax]]*
42
43 This is the configuration described in
44 [[tips/Hosting_Ikiwiki_and_master_git_repository_on_different_machines]]. One server hosts the web server (and the [[Ikiwiki cgi|cgi]]) and the git source dir; a second server hosts the git bare repository. This can be used when you have very limited access to the git server.
45
46 > I don't understand how this configuration is different from the previous one, could you clarify? the image link is broken as well. [[anarcat]]
47 >> Sorry. I did a mistake. I hope this is more clear now. [[Louis|spalax]]
48
49 ### Decentralised pinger setup
50
51 [[!img ping-setup.svg size=400x]]
52
53 In this configuration, the mirrors all have their own `srcdir`, but
54 still need to push and pull from the same central bare git repo. The
55 [[plugins/pinger]] plugin is used to ping the mirrors from the central
56 server on edits.
57
58 Step by step setup instructions for this are detailed below.
59
60 ### Fully decentralised setup
61
62 [[!img decentralized_wikis.svg size=400x]]
63
64 In this configuration, each wiki is fully independent and pushes its
65 changes to other wikis using the [[plugins/contrib/gitpush]] plugin.
66
67 ## Step by step setup instructions
68
69 The first two ways of setting up ikiwiki are better described in [[setup]] or [[tips/Git_repository_and_web_server_on_different_hosts]]. The remainder of this page describes the latter two more complex distributed setups. 
70
71 Say you have a friend that has already configured a shiny ikiwiki site, and you want to help by creating a mirror. You still need to figure out how to install ikiwiki and everything, hopefully this section will help you with that.
72
73 Note that parts of the following documentation duplicate instructions from [[setup]], [[setup/byhand]], [[rcs/git]] and [[tips/laptop_wiki_with_git]].
74
75 ### Installing ikiwiki
76
77 You need to install the ikiwiki package for the mirror to work. You can use ikiwiki to publish the actual HTML pages elsewhere if you don't plan on letting people edit the wiki, but generally you want the package to be installed on the webserver for editing to work.
78
79     apt-get install ikiwiki
80
81 ### Setting up the wiki
82
83 (!) Optionnally: create a user just for this wiki. Otherwise the wiki will run as your user from here on.
84
85 We assume your username is `user` and that you will host the wiki under the hostname `mirror.example.com`. The original wiki is at `wiki.example.com`. We also assume that your friend was nice enough to provide a copy of the `.setup` file in the `setup` branch, which is the case for any wiki hosted on [branchable.com](http://branchable.com).
86
87     cd ~user
88     # setup srcdir, named source
89     git clone git://wiki.example.com/ source
90     # convenience copy of the setup file
91     git clone -b origin/setup source setup
92     cd setup
93     edit ikiwiki.setup # adapt configuration
94
95 When editing ikiwiki.setup, make sure you change the following entries:
96
97     cgiurl: http://mirror.example.com/ikiwiki.cgi
98     cgi_wrapper: /var/www/ikiwiki.cgi
99     srcdir: /home/user/source
100     destdir: /var/www/mirror.example.com
101     libdir: /home/user/source/.ikiwiki
102     git_wrapper: /home/user/source/.git/hooks/post-commit
103     git_test_receive_wrapper: /home/user/source/.git/hooks/pre-receive
104     ENV:
105       TMPDIR: /home/user/tmp
106
107 This assumes that your /var/www directory is writable by your user.
108
109 ### Basic HTML rendering
110
111 You should already be able to make a plain HTML rendering of the wiki:
112
113     ikiwiki --setup ikiwiki.setup
114
115 ### Webserver configuration
116
117 You will also need a webserver to serve the content in the `destdir`
118 defined above. We assume you will configure a virtual host named `mirror.example.com`. Here are some examples on how to do those, see [[!iki setup]] and [[!iki tips/dot_cgi]] for complete documentation.
119
120 Note that this will also configure CGI so that people can edit the wiki. Note that this configuration may involve timeouts if the main site is down, as ikiwiki will attempt to push to the central git repository at every change.
121
122 #### Apache configuration
123
124     <VirtualHost *:80>
125         ServerName mirror.example.com:80
126         DocumentRoot /var/www/mirror.example.com
127         <Directory /var/www/mirror.example.com>
128             Options Indexes MultiViews ExecCGI
129             AllowOverride None
130             Order allow,deny
131             allow from all
132         </Directory>
133         ScriptAlias /ikiwiki.cgi /var/www/ikiwiki.cgi
134         ErrorDocument 404 "/ikiwiki.cgi"
135     </VirtualHost>
136
137 #### Nginx configuration
138
139     server {
140         root /var/www/mirror.example.com/;
141         index index.html index.htm;
142         server_name mirror.example.com;
143
144         location / {
145             try_files $uri $uri/ /index.html;
146         }
147         location /ikiwiki.cgi {
148             fastcgi_pass  unix:/tmp/fcgi.socket;
149             fastcgi_index ikiwiki.cgi;
150             fastcgi_param SCRIPT_FILENAME   /var/www/ikiwiki.cgi;
151             fastcgi_param  DOCUMENT_ROOT      /var/www/mirror.example.com;
152             include /etc/nginx/fastcgi_params;
153         }
154     }
155
156 Start this process as your own user (or the user that has write access
157 to `srcdir`, `destdir`, etc):
158
159     spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap
160
161 Make this writable:
162
163     chmod a+w /tmp/fcgi.socket
164
165 ### Enable the pinger functionality
166
167 At this point, you need to enable the pinger functionality to make sure that changes on the central server propagate to your mirror.
168
169 This assumes a central wiki that exposes its git
170 repository and has the [[plugins/pinger]] plugin enabled. Enable the
171 [[plugins/pingee]] plugin in your configuration, and edit the origin wiki,
172 adding a ping directive for your mirror:
173
174         \[[!ping from="http://thewiki.com/"
175         to="http://mymirror.com/ikiwiki.cgi?do=ping"]]
176
177 The "from" parameter needs to be the url to the origin wiki. The "to" parameter
178 is the url to ping on your mirror. This can be done basically in any page.
179
180 Now whenever the main wiki is edited, it will ping your mirror, which will
181 pull the changes from "origin" using git, and update itself. It could, in
182 turn ping another mirror, etc.
183
184 And if someone edits a page on your mirror, it will "git push origin",
185 committing the changes back to the origin git repository, and updating the
186 origin mirror. Assuming you can push to that git repository. If you can't,
187 and you want a mirror, and not a branch, you should disable web edits on
188 your mirror. (You could also point the cgiurl for your mirror at the origin
189 wiki if you do not want to incur that overhead or do not want to, or can't, run a CGI.)
190
191 ### Fully decentralized configuration
192
193 In the above configuration, the master git repository is still on the main site. If that site goes down, there will be delays when editing the wiki mirror. It could also simply fail because it will not be able to push the changes to the master git repo. An alternative is to setup a local bare repository that is synced with the master.
194
195 At the setup step, you need to create *two* git repositories on the mirror:
196
197     cd ~user
198     # setup base repository, named source.git
199     git clone --bare git://wiki.example.com/ source.git
200     # setup srcdir, named source
201     git clone source.git
202     # convenience copy of the setup file
203     git clone -b origin/setup source.git setup
204     cd setup
205     edit ikiwiki.setup # adapt configuration
206
207 The following entries will be different from the above setup file:
208
209     git_wrapper: /home/user/source.git/hooks/post-commit
210     git_test_receive_wrapper: /home/user/source.git/hooks/pre-receive
211
212 To do this, the mirror needs to push back to the master, using the [[plugins/contrib/gitpush]] plugin:
213
214     git_push_to:
215     - git://wiki.example.com/
216
217 This will ensure that commits done on the mirror will propagate back to the master.
218
219 ## Other ideas
220
221 See also:
222
223  * [[setup]]
224  * [[setup/byhand]]
225  * [[rcs/git]]
226  * [[tips/laptop_wiki_with_git]]
227  * [ikiwiki creation notes](http://piny.be/jrayhawk/notes/ikiwiki_creation/)
228
229 ### Announcing the mirror
230
231 Once your mirror works, you can also add it to the list of mirrors. You can ask the mirror where you take it from (and why not, all mirrors) to add it to their setup file. As an example, here's the configuration for the first mirror:
232
233     mirrorlist:
234       example: https://wiki.example.com/
235
236 The [[plugins/mirrorlist]] plugin of course needs to be enabled for this to work.
237
238 ### branching a wiki
239
240 It follows that setting up a branch of a wiki is just like the fully decentralised mirror above, except
241 we don't want it to push changes back to the origin. The easy way to
242 accomplish this is to clone the origin git repository using a readonly
243 protocol (ie, "git://"). Then you can't push to it.
244
245 If a page on your branch is modified and other modifications are made to
246 the same page in the origin, a conflict might occur when that change is
247 pulled in. How well will this be dealt with and how to resolve it? I think
248 that the conflict markers will just appear on the page as it's rendered in
249 the wiki, and if you could even resolve the conflict using the web
250 interface. Not 100% sure as I've not gotten into this situation yet.
251
252 --[[Joey]]