refer to the other guides earlier
[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 three 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 `srcdir`, still requires a central bare repo - uses [[plugins/pinger]]
15  3. completely distinct ikiwiki installs, synchronised with [[plugins/contrib/gitpush]]
16
17 Here's a graphic overview of those:
18
19 ### Default setup - one central server
20
21 [[!img rcs/git/wiki_edit_flow.svg size=400x]]
22
23 In the default setup, all the resources are stored on the central
24 servers. Users can still clone and edit the git repo by hand and
25 contribute by git, but otherwise all the changes happen on a single
26 web interface. This basic setup is best described in [[rcs/git]].
27
28 ### Separate webserver and git repository
29
30 [[!img tips/Git_repository_and_web_server_on_different_hosts/separate-webserver.svg size=400x]]
31
32 This is the configuration described in
33 [[tips/Git_repository_and_web_server_on_different_hosts]]. The webserver part
34 hosts the HTML files, the ikiwiki [[cgi]] but everything else is on
35 the git server.
36
37 ### Decentralised pinger setup
38
39 [[!img ping-setup.svg size=400x]]
40
41 In this configuration, the mirrors all have their own `srcdir`, but
42 still need to push and pull from the same central bare git repo. The
43 [[plugins/pinger]] plugin is used to ping the mirrors from the central
44 server on edits.
45
46 Step by step setup instructions for this are detailed below.
47
48 ### Fully decentralised setup
49
50 [[!img decentralized_wikis.svg size=400x]]
51
52 In this configuration, each wiki is fully independent and pushes its
53 changes to other wikis using the [[plugins/contrib/gitpush]] plugin.
54
55 ## Step by step setup instructions
56
57 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. 
58
59 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.
60
61 Note that parts of the following documentation duplicate instructions from [[setup]], [[setup/byhand]], [[rcs/git]] and [[tips/laptop_wiki_with_git]].
62
63 ### Installing ikiwiki
64
65 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.
66
67     apt-get install ikiwiki
68
69 ### Setting up the wiki
70
71 (!) Optionnally: create a user just for this wiki. Otherwise the wiki will run as your user from here on.
72
73 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).
74
75     cd ~user
76     # setup srcdir, named source
77     git clone git://wiki.example.com/ source
78     # convenience copy of the setup file
79     git clone -b origin/setup source setup
80     cd setup
81     edit ikiwiki.setup # adapt configuration
82
83 When editing ikiwiki.setup, make sure you change the following entries:
84
85     cgiurl: http://mirror.example.com/ikiwiki.cgi
86     cgi_wrapper: /var/www/ikiwiki.cgi
87     srcdir: /home/user/source
88     destdir: /var/www/mirror.example.com
89     libdir: /home/user/source/.ikiwiki
90     git_wrapper: /home/user/source/.git/hooks/post-commit
91     git_test_receive_wrapper: /home/user/source/.git/hooks/pre-receive
92     ENV:
93       TMPDIR: /home/user/tmp
94
95 This assumes that your /var/www directory is writable by your user.
96
97 ### Basic HTML rendering
98
99 You should already be able to make a plain HTML rendering of the wiki:
100
101     ikiwiki --setup ikiwiki.setup
102
103 ### Webserver configuration
104
105 You will also need a webserver to serve the content in the `destdir`
106 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.
107
108 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.
109
110 #### Apache configuration
111
112     <VirtualHost *:80>
113         ServerName mirror.example.com:80
114         DocumentRoot /var/www/mirror.example.com
115         <Directory /var/www/mirror.example.com>
116             Options Indexes MultiViews ExecCGI
117             AllowOverride None
118             Order allow,deny
119             allow from all
120         </Directory>
121         ScriptAlias /ikiwiki.cgi /var/www/ikiwiki.cgi
122         ErrorDocument 404 "/ikiwiki.cgi"
123     </VirtualHost>
124
125 #### Nginx configuration
126
127     server {
128         root /var/www/mirror.example.com/;
129         index index.html index.htm;
130         server_name mirror.example.com;
131
132         location / {
133             try_files $uri $uri/ /index.html;
134         }
135         location /ikiwiki.cgi {
136             fastcgi_pass  unix:/tmp/fcgi.socket;
137             fastcgi_index ikiwiki.cgi;
138             fastcgi_param SCRIPT_FILENAME   /var/www/ikiwiki.cgi;
139             fastcgi_param  DOCUMENT_ROOT      /var/www/mirror.example.com;
140             include /etc/nginx/fastcgi_params;
141         }
142     }
143
144 Start this process as your own user (or the user that has write access
145 to `srcdir`, `destdir`, etc):
146
147     spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap
148
149 Make this writable:
150
151     chmod a+w /tmp/fcgi.socket
152
153 ### Enable the pinger functionality
154
155 At this point, you need to enable the pinger functionality to make sure that changes on the central server propagate to your mirror.
156
157 This assumes a central wiki that exposes its git
158 repository and has the [[plugins/pinger]] plugin enabled. Enable the
159 [[plugins/pingee]] plugin in your configuration, and edit the origin wiki,
160 adding a ping directive for your mirror:
161
162         \[[!ping from="http://thewiki.com/"
163         to="http://mymirror.com/ikiwiki.cgi?do=ping"]]
164
165 The "from" parameter needs to be the url to the origin wiki. The "to" parameter
166 is the url to ping on your mirror. This can be done basically in any page.
167
168 Now whenever the main wiki is edited, it will ping your mirror, which will
169 pull the changes from "origin" using git, and update itself. It could, in
170 turn ping another mirror, etc.
171
172 And if someone edits a page on your mirror, it will "git push origin",
173 committing the changes back to the origin git repository, and updating the
174 origin mirror. Assuming you can push to that git repository. If you can't,
175 and you want a mirror, and not a branch, you should disable web edits on
176 your mirror. (You could also point the cgiurl for your mirror at the origin
177 wiki if you do not want to incur that overhead or do not want to, or can't, run a CGI.)
178
179 ### Fully decentralized configuration
180
181 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.
182
183 At the setup step, you need to create *two* git repositories on the mirror:
184
185     cd ~user
186     # setup base repository, named source.git
187     git clone --bare git://wiki.example.com/ source.git
188     # setup srcdir, named source
189     git clone source.git
190     # convenience copy of the setup file
191     git clone -b origin/setup source.git setup
192     cd setup
193     edit ikiwiki.setup # adapt configuration
194
195 The following entries will be different from the above setup file:
196
197     git_wrapper: /home/user/source.git/hooks/post-commit
198     git_test_receive_wrapper: /home/user/source.git/hooks/pre-receive
199
200 To do this, the mirror needs to push back to the master, using the [[plugins/contrib/gitpush]] plugin:
201
202     git_push_to:
203     - git://wiki.example.com/
204
205 This will ensure that commits done on the mirror will propagate back to the master.
206
207 ## Other ideas
208
209 See also:
210
211  * [[setup]]
212  * [[setup/byhand]]
213  * [[rcs/git]]
214  * [[tips/laptop_wiki_with_git]]
215  * [ikiwiki creation notes](http://piny.be/jrayhawk/notes/ikiwiki_creation/)
216
217 ### Announcing the mirror
218
219 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:
220
221     mirrorlist:
222       example: https://wiki.example.com/
223
224 The [[plugins/mirrorlist]] plugin of course needs to be enabled for this to work.
225
226 ### branching a wiki
227
228 It follows that setting up a branch of a wiki is just like the fully decentralised mirror above, except
229 we don't want it to push changes back to the origin. The easy way to
230 accomplish this is to clone the origin git repository using a readonly
231 protocol (ie, "git://"). Then you can't push to it.
232
233 If a page on your branch is modified and other modifications are made to
234 the same page in the origin, a conflict might occur when that change is
235 pulled in. How well will this be dealt with and how to resolve it? I think
236 that the conflict markers will just appear on the page as it's rendered in
237 the wiki, and if you could even resolve the conflict using the web
238 interface. Not 100% sure as I've not gotten into this situation yet.
239
240 --[[Joey]]