clarify the step by step instructions in relation with the larger set of distributed...

[git.ikiwiki.info.git] / doc / tips / distributed_wikis.mdwn

diff --git a/doc/tips/distributed_wikis.mdwn b/doc/tips/distributed_wikis.mdwn
index 29273ada1f22eae8b4f5f134b499a849430a23eb..2fd82700ccc093afca3d9c45bdd139ee946fe37e 100644 (file)
--- a/doc/tips/distributed_wikis.mdwn
+++ b/doc/tips/distributed_wikis.mdwn
@@ -5,35 +5,56 @@ git, let's explore some possibilities for distributed wikis.
 
 [[!toc levels=2]]
 
 
 [[!toc levels=2]]
 

-## a wiki mirror
+## Overview

 
 

-The simplest possibility is setting up a mirror. If a wiki exposes its git
-repository and has the [[plugins/pinger]] plugin enabled, then anyone can
-set up a mirror that will automatically be kept up-to-date with the origin
-wiki. Just clone the git repo, configure ikiwiki to use it, enable the
-[[plugins/pingee]] plugin in your configuration, and edit the origin wiki,
-adding a ping directive for your mirror:
+There are three possible level of decentralisation:

 
 

-       \[[!ping from="http://thewiki.com/"
-       to="http://mymirror.com/ikiwiki.cgi?do=ping"]]
+ 0. [[default setup|rcs/git]], no decentralisation
+ 1. [[a simple HTML mirror|tips/Git_repository_and_web_server_on_different_hosts/]]
+ 2. separate `srcdir`, still requires a central bare repo - uses [[plugins/pinger]]
+ 3. completely distinct ikiwiki installs, synchronised with [[plugins/contrib/gitpush]]

 
 

-The "from" parameter needs to be the url to the origin wiki. The "to" parameter
-is the url to ping on your mirror.
+Here's a graphic overview of those:

 
 

-Now whenever the main wiki is edited, it will ping your mirror, which will
-pull the changes from "origin" using git, and update itself. It could, in
-turn ping another mirror, etc.
+### Default setup - one central server

 
 

-And if someone edits a page on your mirror, it will "git push origin",
-committing the changes back to the origin git repository, and updating the
-origin mirror. Assuming you can push to that git repository. If you can't,
-and you want a mirror, and not a branch, you should disable web edits on
-your mirror. (You could also point the cgiurl for your mirror at the origin
-wiki.)
+[[!img rcs/git/wiki_edit_flow.svg size=400x]]
+
+In the default setup, all the resources are stored on the central
+servers. Users can still clone and edit the git repo by hand and
+contribute by git, but otherwise all the changes happen on a single
+web interface. This basic setup is best described in [[rcs/git]].
+
+### Separate webserver and git repository
+
+[[!img tips/Git_repository_and_web_server_on_different_hosts/separate-webserver.svg size=400x]]
+
+This is the configuration described in
+[[tips/Git_repository_and_web_server_on_different_hosts]]. The webserver part
+hosts the HTML files, the ikiwiki [[cgi]] but everything else is on
+the git server.
+
+### Decentralised pinger setup
+
+[[!img ping-setup.svg size=400x]]
+
+In this configuration, the mirrors all have their own `srcdir`, but
+still need to push and pull from the same central bare git repo. The
+[[plugins/pinger]] plugin is used to ping the mirrors from the central
+server on edits.
+
+Step by step setup instructions for this are detailed below.
+
+### Fully decentralised setup

 
 

-## branching a wiki
+[[!img decentralized_wikis.svg size=400x]]

 
 

-It follows that setting up a branch of a wiki is just like a mirror, except
+In this configuration, each wiki is fully independent and pushes its
+changes to other wikis using the [[plugins/contrib/gitpush]] plugin.
+
+### branching a wiki
+
+It follows that setting up a branch of a wiki is just like the fully decentralised mirror above, except

 we don't want it to push changes back to the origin. The easy way to
 accomplish this is to clone the origin git repository using a readonly
 protocol (ie, "git://"). Then you can't push to it.
 we don't want it to push changes back to the origin. The easy way to
 accomplish this is to clone the origin git repository using a readonly
 protocol (ie, "git://"). Then you can't push to it.


@@ -47,7 +68,9 @@ interface. Not 100% sure as I've not gotten into this situation yet.
 
 --[[Joey]]
 
 
 --[[Joey]]
 

-## Practical example
+## Step by step setup instructions
+
+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. 

 
 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.
 
 
 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.
 


@@ -96,7 +119,7 @@ You should already be able to make a plain HTML rendering of the wiki:
 You will also need a webserver to serve the content in the `destdir`
 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.
 
 You will also need a webserver to serve the content in the `destdir`
 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.
 

-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.
+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.

 
 #### Apache configuration
 
 
 #### Apache configuration
 


@@ -141,9 +164,31 @@ Make this writable:
 
     chmod a+w /tmp/fcgi.socket
 
 
     chmod a+w /tmp/fcgi.socket
 

-### Read-only mirror: done!
+### Enable the pinger functionality

 
 

-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.
+At this point, you need to enable the pinger functionality to make sure that changes on the central server propagate to your mirror.
+
+This assumes a central wiki that exposes its git
+repository and has the [[plugins/pinger]] plugin enabled. Enable the
+[[plugins/pingee]] plugin in your configuration, and edit the origin wiki,
+adding a ping directive for your mirror:
+
+       \[[!ping from="http://thewiki.com/"
+       to="http://mymirror.com/ikiwiki.cgi?do=ping"]]
+
+The "from" parameter needs to be the url to the origin wiki. The "to" parameter
+is the url to ping on your mirror. This can be done basically in any page.
+
+Now whenever the main wiki is edited, it will ping your mirror, which will
+pull the changes from "origin" using git, and update itself. It could, in
+turn ping another mirror, etc.
+
+And if someone edits a page on your mirror, it will "git push origin",
+committing the changes back to the origin git repository, and updating the
+origin mirror. Assuming you can push to that git repository. If you can't,
+and you want a mirror, and not a branch, you should disable web edits on
+your mirror. (You could also point the cgiurl for your mirror at the origin
+wiki if you do not want to incur that overhead or do not want to, or can't, run a CGI.)

 
 ### Announcing the mirror
 
 
 ### Announcing the mirror
 


@@ -154,7 +199,7 @@ Once your mirror works, you can also add it to the list of mirrors. You can ask
 
 The [[plugins/mirrorlist]] plugin of course needs to be enabled for this to work.
 
 
 The [[plugins/mirrorlist]] plugin of course needs to be enabled for this to work.
 

-### Alternative configuration
+### Fully decentralized configuration

 
 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.
 
 
 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.
 


@@ -175,7 +220,7 @@ The following entries will be different from the above setup file:
     git_wrapper: /home/user/source.git/hooks/post-commit
     git_test_receive_wrapper: /home/user/source.git/hooks/pre-receive
 
     git_wrapper: /home/user/source.git/hooks/post-commit
     git_test_receive_wrapper: /home/user/source.git/hooks/pre-receive
 

-To do this, the mirror needs to push back to the master, again using the gitpush plugin:
+To do this, the mirror needs to push back to the master, using the [[plugins/contrib/gitpush]] plugin:

 
     git_push_to:
     - git://wiki.example.com/
 
     git_push_to:
     - git://wiki.example.com/