summaryrefslogtreecommitdiffstats
path: root/create-a-wiki/create-a-wiki.mdwn
blob: b6736f1e1c62dbb0c62aa3d61913f476a62a0557 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
This article describes mine (the author's, also known as Gustav)
attempts to configure an Ikiwiki lab environment on my laptop
computer. The purpose of the experiment is to learn how Ikiwiki
functions and how to effectively work with Ikiwiki and offline editing
with git.

The components needed are

  * Ikiwiki
  * Apache2 or Nginx web server
  * Git

**Table of Contents**
[[!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.

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

I can not recall how this was done. Refer to
[Git's official website](https://git-scm.com/)


Install and configure Ikiwiki
=============================

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

    url:         http://localhost/~<name>/lab-wiki
    srcdir:      ~/lab-wiki/wiki
    destdir:     ~/public_html/lab-wiki
    repository:  ~/lab-wiki/wiki.git
    settings:    ~/lab-wiki/wiki.setup

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

    $ ikiwiki --setup ~/lab-wiki/wiki.setup

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

For installation, follow the instructions in
[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)
in Apache's documentation. For Debian do the following

    $ cd /etc/apache2/mods-enabled
    $ ln -s ln -s ../mods-available/userdir.load
    $ 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)
in Apache's documentation. My
`/etc/apache2/mods-available/userdir.conf` now looks as follows

    <IfModule mod_userdir.c>
            UserDir public_html
            UserDir /home/*/public_html
            UserDir disabled root
    
            <Directory /home/*/public_html>
                    AllowOverride FileInfo AuthConfig Limit Indexes
                    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
                    <Limit GET POST OPTIONS>
                            Require all granted
                    </Limit>
                    <LimitExcept GET POST OPTIONS>
                            Require all denied
                    </LimitExcept>
            </Directory>
    
            <Directory /home/*/public_html>
                    Options +ExecCGI
                    AddHandler cgi-script .cgi
            </Directory>
            <Directory /home/*/public_html/*>
                    Options +ExecCGI
                    AddHandler cgi-script .cgi
            </Directory>
    </IfModule>


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
web version is updated.

But what if I want to inspect and verify my local changes before
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
fields:

    wikiname: lab-wiki-preview
    srcdir: ~/lab-wiki/wiki-slave
    destdir: ~/public_html/lab-wiki-preview
    url: http://skolem/~<name>/lab-wiki-preview
    cgiurl: http://skolem/~<name>/lab-wiki-preview/ikiwiki.cgi
    cgi_wrapper: ~/public_html/lab-wiki-preview/ikiwiki.cgi
    git_wrapper: ~/lab-wiki/wiki-slave/.git/hooks/post-commit
    gitorigin_branch: ''
    gitmaster_branch: master

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.