Merge branch 'master' into contact-procedure-update

1 files changed, 78 insertions, 45 deletions

diff --git a/create-a-wiki.mdwn b/create-a-wiki.mdwn
index 37a944f..b6736f1 100644
--- a/create-a-wiki.mdwn
+++ b/create-a-wiki.mdwn
@@ -6,34 +6,48 @@ with git.
 
 The components needed are
 
-* Ikiwiki
-* Apache2 or Nginx web server
-* Git
+  * Ikiwiki
+  * Apache2 or Nginx web server
+  * Git
 
 **Table of Contents**
-[!toc]
+[[!toc]]
 
 What I have in mind is to access my lab wiki through
-_http://localhost/~<name>/lab-wiki_ for web editing and
-_~/lab-wiki/wiki-slave_ for local offline editing.
+`http://localhost/~<name>/lab-wiki` for web editing and
+`~/lab-wiki/wiki-slave` for local offline editing.
 
 It should be noted that what is described here probably is a perfectly
 _unsafe_ usage of a web server. Make sure that the computer does not
 except requests from Internet.
 
-# Install and configure Git
+
+Install and configure Git
+=========================
 
 I can not recall how this was done. Refer to
-[[Git's official website|https://git-scm.com/]]
+[Git's official website](https://git-scm.com/)
+
 
-# Install and configure Ikiwiki
+Install and configure Ikiwiki
+=============================
 
-Refer to [[ikiwiki setup|https://ikiwiki.info/setup/]] at
-[[ikiwiki's official website|https://ikiwiki.info]] for initial
+Refer to [ikiwiki setup](https://ikiwiki.info/setup/) at
+[ikiwiki's official website](https://ikiwiki.info) for initial
 install and configuration and
-[[an article on Git|https://ikiwiki.info/rcs/git/]] for more details on
+[an article on Git](https://ikiwiki.info/rcs/git/) for more details on
 setting up Ikiwiki together with Git.
 
+Install packages referred to in the ansible configuration:
+
+    sudo aptitude install \
+      ikiwiki \
+      libauthen-passphrase-perl \
+      highlight-common libhighlight-perl libimage-magick-perl \
+      libmail-sendmail-perl libnet-dns-sec-perl \
+      fcgiwrap spawn-fcgi \
+      pandoc
+
 I did my best to answer the questions provided in the initial
 installation and default configuration with the target of ending up
 with something like this:
@@ -47,41 +61,43 @@ with something like this:
 However, not all of the above was configurable in the form, for
 example the configuration file location. I needed to move directories
 and files around and change the remaining configurations in
-_~/lab-wiki/wiki.setup_ and run
+`~/lab-wiki/wiki.setup` and run
 
     $ ikiwiki --setup ~/lab-wiki/wiki.setup
 
-I also created the extra Git repository _wiki-slave_ for local edits:
+I also created the extra Git repository `wiki-slave` for local edits:
 
     $ cd ~/lab-wiki; git clone wiki.git wiki-slave
 
 The connectivity chart is now as follows
 
-    .         Bare Git Repository
-    .         ~/lab-wiki/wiki.git
-    .             /         \
-    .            /           \
-    .           /             \
-    . The Ikiwiki Repository  |
-    .   ~/lab-wiki/wiki       |
-    .           |             |
-    .           |    Repository for Local Edits
-    .           |     ~/lab-wiki/wiki-slave
-    .           |             |
-    .  The Ikiwiki Web Part   |
-    . ~/public_html/lab-wiki  |
-    .                         |
-    .            The Preview Ikiwiki Web Part
-    .           ~/public_html/lab-wiki-preview
-
-# Install and configure Apache 2
+            Bare Git Repository
+            ~/lab-wiki/wiki.git
+                /         \
+               /           \
+              /             \
+    The Ikiwiki Repository  |
+      ~/lab-wiki/wiki       |
+              |             |
+              |    Repository for Local Edits
+              |     ~/lab-wiki/wiki-slave
+              |             |
+     The Ikiwiki Web Part   |
+    ~/public_html/lab-wiki  |
+                            |
+               The Preview Ikiwiki Web Part
+              ~/public_html/lab-wiki-preview
+
+
+Install and configure Apache 2
+==============================
 
 For installation, follow the instructions in
-[[Apache's official documentation|https://httpd.apache.org/docs]]. I
+[Apache's official documentation](https://httpd.apache.org/docs). I
 got Apache 2.4.6 installed.
 
 I needed to activate the userdir module. Refer to
-[[Per-user web directories|https://httpd.apache.org/docs/2.4/howto/public_html.html]]
+[Per-user web directories](https://httpd.apache.org/docs/2.4/howto/public_html.html)
 in Apache's documentation. For Debian do the following
 
     $ cd /etc/apache2/mods-enabled
@@ -89,9 +105,9 @@ in Apache's documentation. For Debian do the following
     $ ln -s ln -s ../mods-available/userdir.conf
 
 Also CGI execution need to be activated. See
-[[Dynamic Content with CGI|https://httpd.apache.org/docs/2.4/howto/cgi.html]]
+[Dynamic Content with CGI](https://httpd.apache.org/docs/2.4/howto/cgi.html)
 in Apache's documentation. My
-_/etc/apache2/mods-available/userdir.conf_ now looks as follows
+`/etc/apache2/mods-available/userdir.conf` now looks as follows
 
     <IfModule mod_userdir.c>
             UserDir public_html
@@ -119,19 +135,36 @@ _/etc/apache2/mods-available/userdir.conf_ now looks as follows
             </Directory>
     </IfModule>
 
-# Get preview of local modifications
+
+Install and conifgure Nginx
+===========================
+
+A valid web server alternative
+is
+[Nginx](http://nginx.org/en/docs/).
+
+For installation and configuration
+follow [Ikiwiki on Dot CGI](https://ikiwiki.info/tips/dot_cgi/). `sudo
+aptitude install nginx`. Note the alexjj comment that on
+Debian the package *fcgiwrap* automatically spwans the FastCGI
+program.
+
+
+
+Get preview of local modifications
+==================================
 
 Now every thing works as work as expected. I can fetch the latest
-updated to _wiki-slave_, perform my updates, and whenever those are
-pushed to _origin/master_, the post-update hook makes sure that the
+updated to `wiki-slave`, perform my updates, and whenever those are
+pushed to `origin/master`, the post-update hook makes sure that the
 web version is updated.
 
 But what if I want to inspect and verify my local changes before
-pushing them to _origin/master_?
+pushing them to `origin/master`?
 
 The subject is covered in
-[[the article on Git|https://ikiwiki.info/rcs/git/]]. I did what
-follows. Copy _wiki.setup_ to _wiki-preview.setup_ and edit those
+[the article on Git](https://ikiwiki.info/rcs/git/). I did what
+follows. Copy `wiki.setup` to `wiki-preview.setup` and edit those
 fields:
 
     wikiname: lab-wiki-preview
@@ -144,11 +177,11 @@ fields:
     gitorigin_branch: ''
     gitmaster_branch: master
 
-The idea is that the preview wiki works against wiki-slave, which is
+The idea is that the preview wiki works against `wiki-slave`, which is
 my simulated environment for local repository. What always works now
 is to, at any point, recompile/refresh the wiki:
 
     ikiwiki -setup ~/lab-wiki/wiki-preview.setup -refresh
 
-Also, committing on the local _master_ branch _should_ automatically
-update the lab-wiki-preview wiki.
+Also, committing on the local `master` branch _should_ automatically
+update the `lab-wiki-preview` wiki.