doc/tips/Hosting_Ikiwiki_and_master_git_repository_on_different_machines.mdwn

   1 [[!meta title="Hosting Ikiwiki with a master git repository on a remote machine"]]
   2 [[!meta date="2013-07-22 16:38:20 -0400"]]
   3
   4 This tutorial explains how to set up a wiki such that:
   5
   6 - the machine running Ikiwiki is not the same as the one hosting the git repository;
   7 - changes can be done using CGI;
   8 - changes can be done using git (using ssh protocol).
   9
  10 This configuration may be useful when:
  11
  12 - you do not want (or cannot) connect to the machine hosting your wiki using
  13   `git` or `ssh`;
  14 - you do not want (or cannot) publish web content on the machine hosting you
  15   remotely accessible git repository.
  16
  17 I assume the [[rcs]] used is [[rcs/git]], but it might be done for other rcs.
  18
  19 # Similar and related tips and problems
  20
  21 - [[tips/distributed_wikis]] References different way of distributing wikis (including this one).
  22 - [[http://www.icanttype.org/blog/ikiwiki_git_remote_repo/]] Similar to what I
  23   am describing, excepted that you must be able to connect to the machine
  24   hosting Ikiwiki using ssh.
  25 - [[forum/How_to_specify_repository_is_on_a_remote_host__63__]] My solution
  26   solves the problem described here, excepted that svn is used there, and in
  27   the comments, Joey advice not to do this with svn.
  28 - [[forum/how_to_setup_ikiwiki_on_a_remote_host]] My solution might answer this
  29   problem.
  30
  31 # Overview
  32
  33 By default, when creating a wiki, Ikiwiki creates and uses two repositories: a
  34 bare repository, and a « slave » repository, used as the source to render the
  35 wiki. All of these are on the same machine.
  36
  37 Instead of having the bare repository hosted on the same machine, we will host
  38 it on a remote machine, and tell Ikiwiki to use it instead of its local one. We
  39 will also ensure that the wiki is rendered whenever a commit is done to the git
  40 repository.
  41
  42 [[!img separate-web-git-servers.svg size=400x]]
  43
  44 # Conventions
  45
  46 - We are building a wiki called *SITE*.
  47 - The machine running Ikiwiki and a web server is called the *Ikiwiki machine*.
  48 - The machine hosting the git repository is called the *git machine*. Users can
  49   make git pull and push to this machine.
  50
  51 # Let's go!
  52
  53 ## Creating ssh keys on the Ikiwiki machine
  54
  55 - Create a pair of ssh keys, not password-protected (as they will be used by
  56   script). Let's call them `id_SITE` and `id_SITE.pub`. These keys will be used
  57   by the ikiwiki machine to connect to the git machine.
  58
  59 ## Creating and setting up a repository on the git machine
  60
  61 - Create a repository `SITE.git` on the git machine (using `git init --bare`),
  62   and ensure that public key `id_SITE.pub` can pull from and push to this
  63   repository (using `~/.ssh/config` or by setting the right permissions on
  64   gitolite or gitosis).
  65
  66 ## Creating the wiki on the ikiwiki machine
  67
  68 - Create the wiki following [[the regular procedure|setup]]. You should have,
  69   among others, a directory `SITE.git`, being the master git repository, and a
  70   directory `SITE`, clone of `SITE.git`, used as source directory to render the
  71   wiki.
  72 - Ensure that your web server can serve the rendered wiki, and that changes can
  73   be done with CGI.
  74
  75 ## Configuring the wiki on the wiki machine so that it uses the repository of the git machine
  76
  77 - Configure ssh so that it uses the ssh key `id_SITE` to connect to the git
  78   machine: add the following lines to file `~/.ssh/config` on the ikiwiki
  79   machine:
  80
  81         Host server.name.of.the.git.machine
  82             User git-machine-user
  83             IdentityFile ~/.ssh/id_SITE
  84
  85 - Configure the local copy `SITE` of the wiki (on the ikiwiki machine) to use
  86   the remote git repository instead of the local `SITE.git`. To do so, in the
  87   file `SITE/.git/config`, replace the lines:
  88
  89         [remote "origin"]
  90                url = /path/to/SITE.git
  91                fetch = +refs/heads/*:refs/remotes/origin/*
  92
  93   by the lines:
  94
  95         [remote "origin"]
  96                 url = git-machine-user@server.name.of.the.git.machine:SITE.git
  97                 fetch = +refs/heads/*:refs/remotes/origin/*
  98
  99 - In this repository (`SITE`), run `git pull` and `git push` to ensure that
 100   everything works fine. It *works fine* when you will be able to run `git
 101   pull` and `git push` without user interaction.
 102
 103 - Disable the `post-update` hook in ikiwiki: it is used if the git commits are
 104   done on this machine, which is no longer the case. To do so, in file
 105   `SITE.setup`, comment the line:
 106
 107         git_wrapper => '/path/to/SITE.git/hooks/post-update',
 108
 109 - Tell Ikiwiki to push to the ikiwiki machine when a commit is done by the web
 110   (CGI). To do so, in file `SITE.setup`, add the line:
 111
 112         git_wrapper_background_command => 'git push',
 113
 114 - Enable plugin [[pingee|http://ikiwiki.info/plugins/pingee/]]. It allows git
 115   (on the git machine) to tell ikiwiki to update and rebuild the wiki when
 116   commits are done on the git repository, using only an http connection. To do
 117   so, add `pingee` to the list of enabled plugins (variable `add_plugins` in
 118   file `SITE.setup`).
 119
 120 - Rebuild the wiki (since you chaned the setup file `SITE.setup`).
 121
 122         ikiwiki --setup SITE.setup --rebuild --verbose
 123
 124 ## Configure the git repository (on the git machine) to update the wiki after a push
 125
 126 Add in the `post-receive` hook (file `SITE.git/hooks/post-receive`):
 127
 128       git log -1 --format=format:%ae HEAD | grep -e '@web$' -e 'USER@HOST' ||  wget "http://WIKI-URL/ikiwiki.cgi?do=ping" -O /dev/stdout
 129
 130 If your wiki is password protected, use:
 131
 132       git log -1 --format=format:%ae HEAD | grep -e '@web$' -e 'USER@HOST' ||  wget "http://LOGIN:PASSWORD@WIKI-URL/ikiwiki.cgi?do=ping" -O /dev/stdout
 133
 134 The bit before `wget` is here to prevent updating the wiki while it is
 135 updating, which can lead to a deadlock. Indeed, when the wiki is edited via
 136 web, or a tag page is automatically added, IkiWiki pushes the changes to the
 137 Git machine. Then, the hook on this latter machine tries to pull changes from
 138 the IkiWiki machine, and here is the deadlock. Explanations of the command:
 139
 140 * `git log -1 --format=format:%ae HEAD`: Looks for the user name of the
 141   latest commit.
 142 * `grep -e '@web$' -e 'USER@HOST': Check whether this last commit was pushed
 143   from the IkiWiki machine (change `USER@HOST` to the appropriate string).
 144 * `wget ...`: If the last commit does not come from the IkiWiki machine
 145   (which means it comes from another machine), update the wiki.
 146
 147 ## Going further
 148
 149 - *Web server on a third machine* It should be possible to use a third machine
 150   to host the web server, using [[this documentation|tips/Git_repository_and_web_server_on_different_hosts/]].
 151 - *Using [[gitolite|https://github.com/sitaramc/gitolite]] to manage
 152   repositories on the git machine* Simply replace the manipulations of git on
 153   the git machine by the corresponding manipulations using gitolite.
 154     * With gitolite, you can use this line in a `post-update` hook:
 155
 156         `[ x"$GL_USER" = x"`*`gitolite-user`*`" ] || wget ...` where *gitolite-user* is the name of the public key registered through gitolite.
 157
 158         Thus, you filter out precisely the events that originate from the server-to-be-pinged, no matter what the commit id says. (For example, if you push commits you created on a local CGI ikiwiki, they'd be called '@web' as well).