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