Viki Hosting

Overview

This document briefly describes how to setup an environment on a Debian 11.2 (Bookworm) installation, hosting Viki on an nginx web-server.

It is intended to be a brief set of instructions, so does not include all the necessary features you should install on a public facing system. See the PHP page on the Debian Wiki and the Securing Debian Manual for information.

Debian Packages

Required Packages

markdown - Text-to-HTML conversion tool
nginx-light - nginx web/proxy server (basic version)
php-fpm - server-side, HTML-embedded scripting language (FPM-CGI binary)

Recommended Packages

emacs-nox - GNU Emacs editor (without GUI support)
git - fast, scalable, distributed revision control system
libhtml-gentoc-perl - module that generates a Table of Contents for HTML documents
make - utility for directing compilation
net-tools - NET-3 networking toolkit
patch - Apply a diff file to an original
screen - terminal multiplexer with VT100/ANSI terminal emulation
ssh - secure shell client and server (metapackage)
vim - Vi IMproved - enhanced vi editor

Installation and Configuration

Install the required packages, together with any of the optional recommended packages.

e.g.

  $ sudo apt-get install nginx-light php-fpm markdown \
    emacs-nox git libhtml-gentoc-perl make net-tools patch screen ssh vim

Stop the nginx and php services

$ sudo systemctl stop nginx php8.2-fpm
Create a configuration file /etc/nginx/sites-available/viki

$ sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/viki

Add `index.php` to the following entry in `/etc/nginx/sites-available/viki`:

      index index.html index.htm index.nginx-debian.html;

to read:

      index index.html index.htm index.nginx-debian.html index.php;

Add a rewrite rule after the `server_name` entry in the new configuration file:

  rewrite ^/viki/(Viki|Tech|Business)/search.*$ /viki/search.php?web=$1&$args last;

Enable PHP scripts by uncommenting the following section:

      # pass PHP scripts to FastCGI server
      #
      #location ~ \.php$ {
      #       include snippets/fastcgi-php.conf;
      #
      #       # With php-fpm (or other unix sockets):
      #       fastcgi_pass unix:/run/php/php7.4-fpm.sock;
      #       # With php-cgi (or other tcp sockets):
      #       fastcgi_pass 127.0.0.1:9000;
      #}

to read:

      # pass PHP scripts to FastCGI server
      #
      location ~ \.php$ {
          include snippets/fastcgi-php.conf;
  #
          # With php-fpm (or other unix sockets):
          fastcgi_pass unix:/run/php/php-fpm.sock;
      #       # With php-cgi (or other tcp sockets):
      #       fastcgi_pass 127.0.0.1:9000;
      }

Create a symbolic link to enable the configuration and remove the symbolic link for the default configuration

$ cd /etc/nginx/sites-enabled/ $ sudo ln -s ../sites-available/viki 01-viki $ sudo rm -i default
Create a PHP test page:

$ cd /var/www/html $ sudo tee test.php<<EOF EOF
Start the services

$ sudo systemctl start nginx php8.2-fpm
Use a browser to navigate to http://ip.address/test.php

If the browser downloads the page, then PHP support has not been enabled
  in Nginx.  The page should render in the browser showing all the PHP
  variable settings.  Once you have tested the page succesfully, delete
  `test.php` as it would be a security risk if a bad actor obtained the
  details it displays.

  $ sudo rm /var/www/html/test.php

Clone Viki

$ mkdir ~/Projects $ cd ~/Projects $ git clone git://www.fdsd.co.uk/viki
Build the HTML versions of the source Markdown pages

$ cd ~/Projects/viki $ make
Create a symbolic link under /var/www/html to the Viki clone:

$ cd /var/www/html $ sudo ln -s ~/Projects/viki
Use a browser to navigate to http://ip.address/viki/
The main index page should be displayed. If not, check the /var/log/nginx/error.log for errors. /var/log/nginx/access.log may also help analyse any issues.
Check that the search functionality works. If there is a 404 “page not found” error, it is most likely an issue with the rewrite rule added to /etc/nginx/sites-availabl/viki. If you’ve installed Viki to a different sub-directory of the web-server root than viki, you will need to modify at least the two references to viki in the rewrite rule.

These instructions have been tested by following them on a fresh minimal install of Debian 10 (Buster).

See Also:

– Frank Dean - 11-Feb-2020