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