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