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