Shellwiki Installation

~$ git clone https://git.plutz.net/git/shellwiki /opt/shellwiki
~$ mkdir /srv/wikidata

You can serve multiple sites from one installation, by assigning each site its own _DATA-Directory

Configuration is done via environment variables

Running via Busybox netcat

~$ export _EXEC=/opt/shellwiki
~$ export _DATA=/srv/wikidata
~$ busybox nc -llp 1080 -c /opt/shellwiki/index.cgi

Running via inetd

# <service_name>	<sock_type>	<proto>	<flags>	<user>	<server_path>		<args>
1080			stream		tcp	nowait	user	/opt/shellwiki/index.cgi	/opt/shellwiki/index.cgi --exec=/opt/shellwiki --data=/srv/wikidata

In Apache httpd

<VirtualHost *:80>
  ServerName example.com

  <Location />
    Require	All	granted
    SetEnv	_EXEC	/opt/shellwiki/index.cgi
    SetEnv	_DATA	/srv/wikidata
  </Location>

  ScriptAlias	/	/opt/shellwiki/index.cgi/
</VirtualHost>

Configuration

Shellwiki is configured via Environment variables. Those variables can ususally be set in the web server configuration. If this is impractical for you, you can also write a wrapper script that exports the settings variables, and then calls index.cgi.

Some of the environment variables are common to the cgilite framework, and some are specific for shellwiki. This does not really make a difference, but knowing this can improve you understanding of the mechanics behind the system.

Cgilite Variables

$_EXEC (file system path)

a path pointing to the installation sirectory of the application (shellwiki). I.e. the directory containing index.cgi. If you run multiple sites using shellwiki, then this path will be identical for all sites.

# Example:
_EXEC=/opt/shellwiki
$_DATA (file system path)

a path pointing to the directory where you site data is stored. If you run multiple sites, this path will be different for every site.

# Example:
_DATA=/srv/www.example.com/wiki
$_BASE (url local part)

if you do not run your shellwiki installation at the root URL of you site, then you can set the local URL path leading to you site here. This path will be used in http redirection. In most cases you will not need to set anything here.

# Example:
# e.g. if your shellwiki intallation can be reached under https://example.com/MyWiki/
_BASE=/MyWiki/
$SESSION_TIMEOUT (seconds)
time in seconds after which inactive user sessions become invalid. By default this is 7200 seconds (two hours).
$MD_HTML (true/false)
set this to true if you want wiki users to be able to write plain inline HTML code. Do this only if user registration is private, and all users with write access are trusted. Inserting HTML code directly enables users to include malicious code, harming other visitors of the site and eroding your security and trust environment. Defaults to false.
$USER_REGISTRATION (true/false)
whether anonymous users can create user accounts by themselfes. Defaults to true. Note that if the user database is empty, the first user can always self register, regardless of the value set here.
$USER_REQUIREEMAIL (true/false)
whether users need to confirm their account via an email link. Defaults to true. This will make user registration impossible, if you are not able to send emails. See also $SENDMAIL. For public wikis you usually want this set to true, but if you are running an intranet or invite-only site, then you may find it convenient to set this to false.
$USER_ACCOUNTEXPIRE (seconds)
time after which registered user accounts will become invalid on their own if a user does not log in. Usually you want this in the range of months or years. Defaults to 62208000 (720 days, or ~ two years). When a user does not login for this period, the account will be deleted, and the user name will become available again to be newly registered.
$USER_CONFIRMEXPIRE (seconds)
time afer which an unclaimed user account will expire, if users do not react to their confirmation email or invitation link. Defaults to 86400 (1 day).
$SENDMAIL (path to executable)

the servers sendmail program, which will be used to send confirmation and invitation emails. Defaults to just sendmail, which means it will be looked for in the shells default PATH. The program is expected as a standard UNIX sendmail program, i.e. to understand the parameters -t and -f, and read an email message from stdin, which will then be sent.

# Example
SENDMAIL=/usr/local/sbin/crazymailer

Shellwiki Variables

$REV_PAGES (true/false)
use page revisioning via GIT. Defaults to true. Note that if a git binary is not available in the shells search PATH, then this will be treated as false regardless of its value.
$REV_ATTACHMENTS (true/false)
revision page attachments. Defaults to false. Requres $REV_PAGES to be true as well, otherwise it will always be false. Note that it is possible for page attachments to be huge binary files and GIT recommends against putting those into revisioning. You can enable it anyway.
$WIKI_THEME (theme name)
base name of a .sh file under the intstallations theme/ directory. Defaults to default. Also see ../theming/.
$SEARCH_INDEX (true/false)
whether a page index will be created and dynamic search will be available. Defaults to true. The search indexes size will usually be in the megabytes range and can reach several hundred megabytes for large wikis. In all other regards however, indexing and search operations are cheap! You will want to set up a cron job for occasional index pruning. See ../search/ for details.
$LANGUAGE_DEFAULT (language tag)
if set will enable multilanguage support. When multilanguage support is enabled, then any page starting named by a colon and a language tag (e.g. :it) will be regarded as a translation of its parent page. The parent page itself will contain the default text, which is displayed when the translation page does not exist. Language tags should follow the iso 639 schema because they are used in the lang attribute of a pages parent html element. For the wiki however langauge tags are completely arbitrary. By default this variable is empty, which means pages starting with a colon will not be treated specially. $LANGUAGE_DEFAULT will also be used to load localization files for the default view, providing another reason to use iso 639 names.
$SITE_TITLE (text)
the tile string rendered in the documents <title> attribute, i.e. displayed on the browser tab. Empty by default. The site title is always displayed in addition to a page title derived from the document.
$CACHE_AGE (seconds)
time for which rendered pages are cached. Default 300 (5 minutes). Caching prevents constant rerendering of pages and will improve page load performance significantly, especially for pages with expensive macro calls. However, macro output will also be cached, meaning that things like pagelists and inclusions will not be updated until the cache expires (or the page itself is updated). Setting this to a few minutes is usually a good idea.