dockerfile_fswiki_local

Dockerfile for local use FSWiki (FreeStyleWiki) with Markdown Plugin, CSP (Content Security Policy), and LaTeX/MathML rendering using MathJax.

Project maintained by KazKobara Hosted on GitHub Pages — Theme by mattgraham

Dockerfile and docker-compose.yml for local use FSWiki

日本語 Japanese

FSWiki (FreeStyleWiki) is a Wiki clone written in Perl (and JavaScript).

screenshot

Features

This Dockerfile is to launch FSWiki enabling:

CAUTION: To expose it to the public network, additional security considerations would be necessary including https use, load-balancing, permissions and so on.

markdown_screenshot

The above is the screenshot of the following markdown document (in a markdown block of FSWiki in the ‘kati_dark’ theme where other themes are available from here.

# Markdown Plugin with CSP

## Syntax

1. **Inline _scripts_** and _**unintended** inline styles_ are ~~allowed~~ blocked by CSP.
    - <span type="text/css" class="orange">Coloring</span> shall be realized using style-sheet defined {type, class} selectors.

### Definition List

CSP
: Content ___Security___ Policy

=FSWiki=
    A *Wiki* clone written in [Perl](https://www.perl.org/ "https://www.perl.org/") (and JavaScript).

### Table

<!-- Realizing 'text-align:' in a markdown table without using inline-style requires a tweak. -->

| text-align: left | text-align: center | text-align: right |
|:---------|:----------:|---------:|
| left     |   center   |    right |

### Fenced Code Block

```console
git clone https://github.com/KazKobara/dockerfile_fswiki_local.git
cd dockerfile_fswiki_local
```

### \\( \LaTeX \\) (and MathML) Using MathJax

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

It can show equations, and so on, beautifully, such as
\\( \sin^{2} \theta + \cos^{2} \theta = 1 \\),
\\( \tan \theta = \frac{\sin \theta}{\cos \theta} \\)  and below:
\\[ \lim_{h \to 0} \frac{f(x+h) - f(x)}{h} \\]

How to use

Run the following commands on a shell terminal.

1. Get Dockerfile etc

1.1 git clone and enter the folder

git clone https://github.com/KazKobara/dockerfile_fswiki_local.git

cd dockerfile_fswiki_local

1.2 Edit parameters in .env file

vim .env
Variable Explanation
FSWIKI_DATA_ROOT Set the root folder that includes FSWiki’s attach/ config/ data/ log/ to share them as the container’s shared volumes.*1
CONTAINER_CLI Set your container CLI, such as docker or nerdctl.
COMPOSE Set your container composer, such as docker-compose or nerdctl compose.
  • *1 Edit docker-compose.yml or run_fswiki_local.sh you use to change the shared volumes.

1.3 Download FSWiki under ./tmp/

./get_fswiki.sh

2. Build and run

In the following steps, you can choose either 2a. compose version (such as ‘docker-compose’, ‘nerdctl compose’) or 2b. shell script version depending on your environment.

If they pop up the following window on Windows OS, click the “cancel” button to block the access from outside your PC.

cancel

2a Compose Version

2a.1 Build image

nerdctl compose build

or

docker-compose build
  • On Windows OS, add .exe after the command.
  • Building the image on Alpine takes time in git clone, presumably to resolve FQDN.

2a.2 Run

nerdctl compose up

or

docker-compose up

To run it in the background, add -d option.

2a.3 Browse

With your web browser, access http//localhost:<FSWIKI_PORT>/, such as http//localhost:8366/, where FSWIKI_PORT is specified in the .env file.

2a.4 Stop and remove the process

nerdctl compose down

or

docker-compose down

2b. Shell Script Version

2b.1 Build image

./docker_build.sh

Building the image on Alpine takes time, similar to the compose version.

2b.2 Run server for local use

./run_fswiki_local.sh

2b.3 Browse

With your web browser, access http//localhost:<FSWIKI_PORT>/, such as http//localhost:8366/, where FSWIKI_PORT is specified in the .env file.

2b.4 Stop and remove the process

nerdctl stop <container_name> && nerdctl rm <container_name>

or

docker stop <container_name> && docker rm <container_name>

where <container_name> is fswiki_alpine_local for Alpine image or fswiki_ubuntu_local for Debian/Ubuntu image.

<container_name> of the compose version ends with _dc.

2b.5 Remove the image

nerdctl rmi <image_name>

or

docker rmi <image_name>

where <image_name> is <container_name>:<fswiki_version> and <fswiki_version> is latest, 3_8_5, and os on.

3. Rebuild for update/upgrade

3.1 Update httpd

Depending on the base os of the docker container, run the following:

For Alpine image:

nerdctl pull httpd:alpine

or

docker pull httpd:alpine

For Debian/Ubuntu image:

nerdctl pull httpd:latest

or

docker pull httpd:latest

3.2 Update kati_dark theme

For the latest FSWiki in the git repo:

(cd ./tmp/wikilatest/theme/kati_dark && git pull)

For FSWiki 3.5.6:

(cd ./tmp/wiki3_6_5/theme/kati_dark && git pull)

3.3 Rebuild and run

Run step 2, depending on your environment.

To run multiple/additional services

There are two ways to realize this, one creates a new folder, and the other utilizes an existing folder.

Method 1: new folder

  1. In step 1.1, git clone to another folder.

  2. In the new folder, edit variables according to the following section in docker-compose.yml.

     ##### To launch multiple independent docker processes #####
  3. Run step 1.2 and later.

Method 2: existing folder

Edit FSWIKI_DATA_ROOT_PRIVATE and FSWIKI_PORT_PRIVATE in .env, then

nerdctl compose -f docker-compose-multiple.yml up

or

docker-compose -f docker-compose-multiple.yml up

or

./run_fswiki_private.sh

Differences between docker-compose and shell versions

Docker Image Sizes

tag_version fswiki base kernel httpd perl Image Size[MB]
0.0.5 latest (4ba68e3) Alpine 3.17 *1 5.15.79.1 2.4.54 *2 5.36.0 78.6
0.0.5 3_6_5 Alpine 3.17 *1 5.15.79.1 2.4.54 *2 5.36.0 73.5
0.0.5 latest (4ba68e3) Debian 11 5.15.79.1 2.4.54 *2 5.32.1 229
0.0.5 3_6_5 Debian 11 5.15.79.1 2.4.54 *2 5.32.1 224

The following versions have vulnerabilities. To update, cf. the above step 3.

The following commands show the sizes:

nerdctl images | grep fswiki_

or

docker images | grep fswiki_

and versions:

./check_ver_in_container.sh <container_name>

or the following test can show them too.

TEST

  1. Edit the following parameters in ./test.sh

     ## Uncomment one of them.
 TEST_PLATFORM="alpine ubuntu"
 # TEST_PLATFORM="alpine"
 # TEST_PLATFORM="ubuntu"

 ## Comment out if not to test
 TEST_COMPOSE_VER="Do"
 TEST_SHELL_VER="Do"
  2. Set FSWIKI_DATA_ROOT in .env (as an absolute path to test shell version).

  3. Run

     ./test.sh

Settings

Web Security Check

To allow access from other docker containers for web security check using OWASP ZAP, Nikto and so on, edit FSWIKI_PORT in .env and set their target IP addresses to any IP address assigned to the host OS.

Permissions and group

Check and edit FSWIKI_DATA_ROOT in .env. Then in the same folder as .env, run

./change_permissions.sh

Alternatively, set manually permissions and group of folders (and their files), which are under FSWIKI_DATA_ROOT folder set in .env, and where docker-compose.yml or run_fswiki_local.sh specifies. If the folders are attach/ config/ data/ log/, the commands are as follows:

  chmod -R a-rwx,ug+rwX attach/ config/ data/ log/
  chgrp -R <gid_of_httpd_sub-processes> attach/ config/ data/ log/

FSWiki, however, changes the files’ permission to 644 (regardless umask) and their owners to uid of httpd_sub-processes.

where <gid_of_httpd_sub-processes> is

(uid_of_httpd_sub-processes) group base httpd
33 (33) www-data Debian/Ubuntu 2.4.52
82 (82) www-data Alpine 2.4.52
1 (1) daemon Debian/Ubuntu 2.4.46
2 (2) daemon Alpine 2.4.46

NOTE: gid is needed since gid may differ between host and guest of the docker container. If you change it in the container, you can use group name instead of gid.

Permission to share data volume with multiple OSes

On each container OS, add the username of the httpd_sub-process of the OS to the group corresponding to the other OS, e.g., to share Alpine folders on Debian/Ubuntu:

  addgroup --gid 82 www-data-alpine
  adduser www-data www-data-alpine

and vice versa on Alpine:

  adduser www-data xfs

where gid of xfs is 33 whose group is www-data on Debian/Ubuntu.

Trouble-shooting

‘Permission denied’ or ‘Lock is busy’

If your web browser displays any of the following errors, check and change file permissions and group as above.

  Permission denied at lib/Wiki/DefaultStorage.pm line 114.

  Permission denied: ./log at lib/CGI2.pm line 34.

  You don't have permission to access this resource.

  Lock is busy. at plugin/core/ShowPage.pm line 69. at lib/Util.pm line 743.

Software Error

If your web browser displays the following error, check or change FSWIKI_DATA_ROOT in .env file. Docker for Windows does not mount some folders to docker containers.

  Software Error:
  HTML::Template->new() : Cannot open included file ./tmpl/site//. tmpl : file not found. at lib/HTML/Template.pm

Can’t locate CGI.pm

If the docker outputs the following log, install Perl CGI with apt-get install -y libcgi-session-perl for Debian/Ubuntu, apk add -y perl-cgi-fast for Alpine, and so on.

  Can't locate CGI.pm in @INC (you may need to install the CGI module) (...) at lib/CGI2.pm line 7.
  BEGIN failed--compilation aborted at lib/CGI2.pm line 7.

CHANGELOG

LICENSE