summaryrefslogtreecommitdiffstats
path: root/create-a-wiki-preview.mdwn
blob: fd01bec552dcd74acc842bf8488ddb380f86a010 (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
---
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. Since July 2019 that is Debian 10
Buster. 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 configuration and wiki repositories.
 * BusyBox -- includes http-server, included in 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://localhost:8080/|
/cgiurl:/ s|:.*$|: http://localhost:8080/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|:.*$|: ''|
/^pandoc_smart:/ d
EOF
sed -f /tmp/fripost-wiki.sed -i ~/.ikiwiki/fripost-wiki.setup
```

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

Copy Ikiwiki configuration from Fripost Ansible repository:

    cp ~/git/fripost/wiki/.ikiwiki/IkiWiki/Plugin/*.pm ~/.ikiwiki/IkiWiki/Plugin/

Run setup:

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

Starting, refreshing and rebuilding the wiki
============
Now all the configuration is done.
This section will discuss commands that needs to be executed repeatedly.

The following command will start the web server on port 8080:

```
busybox httpd -p 127.0.0.1:8080 -h "$HOME/public_html/fripost-wiki"
```

This server will shut down when your computer does.
If you want to shut down the server, but not your computer, run the following command:

```
pkill -ef "busybox httpd -p 127.0.0.1:8001"
```

Now all is in place! Visit <http://localhost:8080/>.
The main site page can be accessed at <http://localhost:8080/website/>.

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!