related ideas

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

diff --git a/doc/tips/distributed_wikis.mdwn b/doc/tips/distributed_wikis.mdwn
index 91bc1c8f275cead31dcbb46df809f7de3f9dd671..29273ada1f22eae8b4f5f134b499a849430a23eb 100644 (file)
--- a/doc/tips/distributed_wikis.mdwn
+++ b/doc/tips/distributed_wikis.mdwn
@@ -3,6 +3,8 @@ making it easy to create and maintain copies and branches of a project. And
 this can be used for all sorts of interesting stuff. Since ikiwiki can use
 git, let's explore some possibilities for distributed wikis.
 
 this can be used for all sorts of interesting stuff. Since ikiwiki can use
 git, let's explore some possibilities for distributed wikis.
 

+[[!toc levels=2]]
+

 ## a wiki mirror
 
 The simplest possibility is setting up a mirror. If a wiki exposes its git
 ## a wiki mirror
 
 The simplest possibility is setting up a mirror. If a wiki exposes its git


@@ -62,12 +64,10 @@ You need to install the ikiwiki package for the mirror to work. You can use ikiw
 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).
 
     cd ~user
 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).
 
     cd ~user

-    # setup base repository, named source.git
-    git clone --bare git://wiki.example.com/ source.git

     # setup srcdir, named source
     # setup srcdir, named source

-    git clone source.git
+    git clone git://wiki.example.com/ source

     # convenience copy of the setup file
     # convenience copy of the setup file

-    git clone -b origin/setup source.git setup
+    git clone -b origin/setup source setup

     cd setup
     edit ikiwiki.setup # adapt configuration
 
     cd setup
     edit ikiwiki.setup # adapt configuration
 


@@ -78,8 +78,8 @@ When editing ikiwiki.setup, make sure you change the following entries:
     srcdir: /home/user/source
     destdir: /var/www/mirror.example.com
     libdir: /home/user/source/.ikiwiki
     srcdir: /home/user/source
     destdir: /var/www/mirror.example.com
     libdir: /home/user/source/.ikiwiki

-    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

     ENV:
       TMPDIR: /home/user/tmp
 
     ENV:
       TMPDIR: /home/user/tmp
 


@@ -91,33 +91,19 @@ You should already be able to make a plain HTML rendering of the wiki:
 
     ikiwiki --setup ikiwiki.setup
 
 
     ikiwiki --setup ikiwiki.setup
 

-### Editing your copy through git
-
-At this point, your wiki should already be visible in `/var/www/mirror.example.com`, the `destdir`. You can edit it and changes should show up automatically in the `destdir`.
-
-However, you need yet another clone for this, the `srcdir` being used internally by the web interface of Ikiwiki. So clone the `repository` elsewhere:
-
-    git clone ~user/source.git checkout
-    cd checkout
-    edit index.mdwn
-    git commit index.mdwn
-    git push
-
-This will refresh the main page of the wiki, for example.
-

 ### Webserver configuration
 
 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.
 
 ### Webserver configuration
 
 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 your copy of the wiki. We'll see how to sync back later.
+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.

 
 #### Apache configuration
 
     <VirtualHost *:80>
 
 #### Apache configuration
 
     <VirtualHost *:80>

-        ServerName reseaulibre.example.com:80
-        DocumentRoot /var/www/reseaulibre.example.com
-        <Directory /var/www/reseaulibre.example.com>
+        ServerName mirror.example.com:80
+        DocumentRoot /var/www/mirror.example.com
+        <Directory /var/www/mirror.example.com>

             Options Indexes MultiViews ExecCGI
             AllowOverride None
             Order allow,deny
             Options Indexes MultiViews ExecCGI
             AllowOverride None
             Order allow,deny


@@ -130,9 +116,9 @@ Note that this will also configure CGI so that people can edit your copy of the
 #### Nginx configuration
 
     server {
 #### Nginx configuration
 
     server {

-        root /var/www/reseaulibre.example.com/;
+        root /var/www/mirror.example.com/;

         index index.html index.htm;
         index index.html index.htm;

-        server_name reseaulibre.example.com;
+        server_name mirror.example.com;

 
         location / {
             try_files $uri $uri/ /index.html;
 
         location / {
             try_files $uri $uri/ /index.html;


@@ -141,7 +127,7 @@ Note that this will also configure CGI so that people can edit your copy of the
             fastcgi_pass  unix:/tmp/fcgi.socket;
             fastcgi_index ikiwiki.cgi;
             fastcgi_param SCRIPT_FILENAME   /var/www/ikiwiki.cgi;
             fastcgi_pass  unix:/tmp/fcgi.socket;
             fastcgi_index ikiwiki.cgi;
             fastcgi_param SCRIPT_FILENAME   /var/www/ikiwiki.cgi;

-            fastcgi_param  DOCUMENT_ROOT      /var/www/reseaulibre.example.com;
+            fastcgi_param  DOCUMENT_ROOT      /var/www/mirror.example.com;

             include /etc/nginx/fastcgi_params;
         }
     }
             include /etc/nginx/fastcgi_params;
         }
     }


@@ -168,9 +154,26 @@ 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.
 

-### Pushing changes back to the main site
+### Alternative 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.
+
+At the setup step, you need to create *two* git repositories on the mirror:

 
 

-The final step is to push edits on the mirror back to the master site. That way the mirror is not only for reading, but can also be edited, even when the master is offline or the network is separated.
+    cd ~user
+    # setup base repository, named source.git
+    git clone --bare git://wiki.example.com/ source.git
+    # setup srcdir, named source
+    git clone source.git
+    # convenience copy of the setup file
+    git clone -b origin/setup source.git setup
+    cd setup
+    edit ikiwiki.setup # adapt configuration
+
+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

 
 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, again using the gitpush plugin: