summaryrefslogtreecommitdiffstats
path: root/create-a-wiki-preview.mdwn
blob: 05f815356c504af738f7d298518e8b8323cd70d3 (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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
---
title: Create a Fripost wiki preview
...

This article describes how to set up preview of Friposts wiki.

**Table of contents**

[[!toc]]

The setup will produce the following layout:

```
    Bare remote Git repository
 (git.fripost.org:fripost-wiki.git)
                |
                |                 Library and config
    Repository for Local Edits       (~/.ikiwiki/)
       (~/git/fripost/wiki)               |
                |                    +---------+
                |                    | Ikiwiki |
   The Preview Ikiwiki Web Part -----| Pandoc  |
    (~/public_html/fripost-wiki)     | Plugins |
                |                    +---------+
        +------------+      +---------+
        | Web server | ---- | Browser |
        +------------+      +---------+
```

Where *~/git/fripost/wiki* is a local git repository with remote
tracking of Fripost's origin remote wiki repository
*git.fripost.org:fripost-wiki.git*. The local preview version will
reside in *~/public_html/fripost-wiki*. Eventually it will be accessed
by pointing the browser to *http://fripost.localhost* and
*http://wiki.fripost.localhost* respectively. The wiki configuration
*~/.ikiwiki/fripost-wiki.setup* will be only minor modifications of
Friposts wiki configuration.

The guide assumes Debian stable. This is the overview of software
needed:

 * Git  -- from Debian
 * Ikiwiki -- from Debian
 * Pandoc -- from Debian
 * Some Ikiwiki plugins (e.g. for Pandoc) which will be provided from
   Fripost's configuraiton
 * Nginx -- webserver from Debian

Install and configure Git
=========================

Refer to [Git och Fripost](git_och_fripost) for installation
instructions.

You will need the following repositories:

 * <https://git.fripost.org/fripost-ansible>
 * <https://git.fripost.org/fripost-wiki>

Clone with SSH if you want to edit, which will require you to provide
a public key to Fripost administrators. Below snippets assume:

    git clone https://git.fripost.org/fripost-ansible ~/git/fripost/ansible
    git clone https://git.fripost.org/fripost-wiki ~/git/fripost/wiki

Install and configure Ikiwiki, Pandoc and plugins
=================================================

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 apt install \
      ikiwiki \
      libauthen-passphrase-perl \
      highlight-common libhighlight-perl libimage-magick-perl \
      libmail-sendmail-perl libnet-dns-sec-perl \
      fcgiwrap spawn-fcgi \
      pandoc \
      clamdscan

Copy Ikiwiki configuration from Fripost Ansible repository:

    mkdir -p ~/public_html/fripost-wiki ~/.ikiwiki
    cp -r ~/git/fripost/ansible/roles/wiki/files/var/lib/ikiwiki/* ~/.ikiwiki

Modify the configuration *~/.ikiwkik/fripost-wiki.setup* according to
the below (inspect */tmp/fripost-wiki.sed*):

```
cat <<EOF | tee /tmp/fripost-wiki.sed
/adminemail:/ s/admin@/$USER@/
/^adminuser:/,/^[a-z]*:/ {
  /^ *-/ d
  /^adminuser:/ a \\
      - $USER
}
/^srcdir:/      s|:.*$|: $HOME/git/fripost/wiki|
/^destdir:/     s|:.*$|: $HOME/public_html/fripost-wiki|
/^cgi_wrapper:/ s|:.*$|: $HOME/public_html/fripost-wiki/ikiwiki.cgi|
/url:/    s|:.*$|: http://wiki.fripost.localhost/ \# http://fripost.localhost/|
/cgiurl:/ s|:.*$|: http://wiki.fripost.localhost/ikiwiki.cgi|
/^libdir:\|^ *file:/ s|/var/lib/ikiwiki|$HOME/.ikiwiki|
/^sslcookie:/ s/1/0/g
/^git_wrapper:/ s/^/\#/g
/^wrappergroup:/ s/^/\#/g
/^historyurl:/ s/^/\#/g
/^diffurl:/ s/^/\#/g
/^gitorigin_branch:/ s|:.*$|: ''|
EOF
sed -f /tmp/fripost-wiki.sed \
  < ~/git/fripost/ansible/roles/wiki/files/var/lib/ikiwiki/fripost-wiki.setup \
  > ~/.ikiwiki/fripost-wiki.setup
```

*TODO investegate what to do with post update thing.*

Run setup:

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

Install and conifgure Nginx and host files
==========================================

Fripost uses [Nginx](http://nginx.org/en/docs/). For installation and
configuration
follow [Ikiwiki on Dot CGI](https://ikiwiki.info/tips/dot_cgi/). Note
the alexjj comment that on Debian the package *fcgiwrap* automatically
spwans the FastCGI program.

    sudo apt install nginx

The follwing will configure *http://wiki.fripost.localhost* and
*http://fripost.localhost*:

```
cat <<EOF | sudo tee /etc/nginx/sites-available/localhost.fripost.conf
server {
  listen [::]:80;
  listen *:80;
  server_name fripost.localhost;
  access_log /var/log/nginx/access.log.localhost.fripost.log;
  error_log /var/log/nginx/error.log.localhost.fripost.log;
  location / {
    root $HOME/public_html/fripost-wiki/website;
    location /static {
      root $HOME/public_html/fripost-wiki;
    }
  }
}

server {
  listen [::]:80;
  listen *:80;
  server_name wiki.fripost.localhost;
  access_log /var/log/nginx/access.log.localhost.fripost.wiki.log;
  error_log /var/log/nginx/error.log.localhost.fripost.wiki.log;
  location / {
    root $HOME/public_html/fripost-wiki;
  }
}
EOF
```

Make available, test and install:

```
sudo ln -s -r -t /etc/nginx/sites-enabled/ /etc/nginx/sites-available/localhost.fripost.conf
sudo nginx -t && sudo systemctl restart nginx.service
```

Modify host files:

```
cat <<EOF > /tmp/hosts

# Fripost wiki preview setup
127.0.1.1   wiki.fripost.localhost fripost.localhost
::1         wiki.fripost.localhost fripost.localhost
EOF
grep -q wiki.fripost.localhost /etc/hosts \
  || { sudo cp /etc/hosts /etc/hosts.bac_$(date +%Y%m%d) \
       && sudo sed -i '$ r /tmp/hosts' /etc/hosts ; }
```

Alternatives to Nginx include Apache. Fripost wiki used include
configuration for Apache, but these are not maintained any
longer. Brows this repository history for sample configurations.

Refresh wiki
============

Now all is in place! Visit <http://wiki.fripost.localhost>. Use the
following commands to refresh or fully rebuild the wiki:

```
ikiwiki --setup ~/.ikiwiki/fripost-wiki.setup --refresh
ikiwiki --setup ~/.ikiwiki/fripost-wiki.setup --rebuild
```

Happy hacking!