Installation

1   Requirements

Password hashing requires the Digest::HMAC_SHA1 Perl module. If this module is not installed, the script will display an error message and stop. The Perl modules listed in Table 1 are optionally used.

Table 1: Useful Perl modules. * indicates core modules.
Perl modulePurposeIf not installed
POSIX*Time zone and formatUse scalar localtime
Encode*Decode diff lines to $CHARSETPrint undecoded diff lines
MIME::TypesFile downloadUse the $MIME_TYPE_COMMAND setting
MIME::LiteEmail notificationsPrint an error message and stop
Archive::ZipBackup and restorePrint an error message and stop
IO::Socket::INET*Embedded web serverPrint an error message and stop
IO::Socket::SSLEmbedded web server on HTTPSPrint an error message and stop

2   Protect important files

Uniqki was designed to be as simple to set up as possible. If you don’t want any customization, Uniqki requires no installation at all other than protecting some files from being served by the web server. Uniqki creates *.txt files to store page source and *.txt.v files to keep page history in the document root directory. The config and password files are u.cfg and u.pw, respectively. Optionally, the template directory u.tpl and the messages file u.msg can be created if the default template and messages need to be customized. Lastly, session information is stored in .sessions. These files and directories can be secured by Apache using the .htaccess directive shown in Figure 1. Place this .htaccess file in the directory where your Uniqki script will run.

<Files ~ "(^u\.(cfg|pw|msg)|^\.sessions|\.(tpl|txt|txt\.v))$">
        Deny from all
</Files>
Figure 1: File protection for Apache.

3   Set a CGI handler

Once the above files are protected, you have to add a CGI handler to the script file. Since the default name of the script is u, the .htaccess directive shown in Figure 2 can be added to execute the script as CGI.

<Files "u">
        SetHandler cgi-script
</Files>
Figure 2: CGI handler for Apache.

You can rename the script to whatever name you want because the script does not have its name hardcoded. For example, if you want to have the .cgi extension, just rename “u” to “u.cgi” and refresh all pages, if any.

4   Upload the script

Upload the file “u” to the same directory where you created the .htaccess file and change its permission to 755 (-rwxr-xr-x, the owner has all permissions and the owner’s group and others have read and execute permissions). If you want, you can rename the script now.

5   First login

Now, you can login into the new Uniqki site by browsing to http://example.com/u. You’ll see the error message in Figure 3 because there is no index.html yet.

first-access.png
Figure 3: First access. index.html does not exist yet.

Click the Login link and type “admin” in both username and password fields as shown in Figure 4.

first-login.png
Figure 4: First login. Both username and password are “admin”

Since the default password is known to anyone who sees this page or the source code of Uniqki, you must change the password to continue. Any admin actions will lead to the screen in Figure 5 to force you to change the password.

change-password.png
Figure 5: Manage myself. Change the admin password immediately in this screen.

6   Change the admin user (Optional)

If you want to rename the admin user, you have to create a new admin user and delete the default “admin” user in the Manage users screen shown in Figure 6. Browse to http://example.com/u?manage_users to see the user management page.

add-admin-user.png delete-admin.png
Figure 6: Manage users. You may want to have a different admin username. Add a new admin user and delete the default “admin” user.

7   Create the index page

At this point, you can create new pages. The first page you want to create is the index page or index.html. Go to http://example.com/u and you will see a “Create this page” link in Figure 7.

create-this-page.png edit-index.png
Figure 7: Create the index page.

8   Configuration

Visiting http://example.com/u?install_config will create a new config file called u.cfg in the same directory where the u script resides if it doesn’t already exist.

$SITE_TITLE
Site title. This title appears in the default theme and RSS feeds. The default value is Uniqki: A Personal Wiki Builder.
$SITE_DESCRIPTION
Short description of the site. This description appears in the default theme and RSS feeds. This variable allows HTML tags for the default theme. The default value is A <a href="http://uniqki.isnew.info">Uniqki</a> site.
$INDEX_PAGE
Name of the index page. The default value is index.
$LANG
HTML language code. The default language is en.
$CHARSET
Character set. The default character set is utf-8.
$LOCALE
Language locale used for Perl messages. For example, setting this variable to ko_KR.utf8 will print time in the Korean locale. The default locale is empty, which means the system default locale.
$TIME_ZONE
Time zone if different from the system time. The default time zone is empty, which is the system’s time zone.
$TIME_FORMAT
Time format interpreted by the POSIX::strftime function. This variable can be used with $LOCALE to print time in a different language than the system default language. The default value is %a %b %e %H:%M:%S %Y %Z.
$SHARE_COOKIES
You may want to share login cookies with other sites so that the user can login to and logout from multiple Uniqki sites at once. This shared login/logout is possible by sharing cookies with subdomains, subpaths, or all paths in the same domain. The following is possible values for this setting:
Empty
Cookies are not shared with any subdomains nor any paths. This is the default value.
subpaths
Share cookies with subpaths in the same domain. For example, cookies created by http://example.com/path1/u are shared with http://example.com/path1/subpath1/u, but not with http://example.com/u nor http://example.com/path2/u.
all_paths
Share cookies with all paths in the same domain. For example, cookies created by http://example.com/path1/u are shared with http://example.com/u, http://example.com/path2/u, and http://example.com/path1/subpath1/u.
subdomains
Share cookies with subdomains. For example, cookies created by http://example.com/u are shared with http://www.example.com/u.
subdomains:subpaths
Share cookies with subpaths in the same domain and subdomains. For example, cookies created by http://example.com/path1/u are shared with http://www.example.com/path1/subpath1/u, but not with http://www.example.com/path2/u.
subdomains:all_paths
Share cookies with all paths in the same domain and subdomains. For example, cookies created by http://example.com/path1/u are shared with http://www.example.com/path1/subpath1/u and http://www.example.com/path2/u.

Subdomains and specified paths have to use the password and sessions files in the current domain and path to share login sessions. Subpaths does not work with $doc_root because the script and document directories are different.
$PASSWORD_FILE
Password file. This file stores all user information including passwords. The default value is u.pw. The admin password can be embedded in the script as $adminpw to run the site using the script file u alone.
$SESSIONS_FILE
Sessions file. This file stores session information. The default value is .sessions.
$MESSAGES_FILE
Messages file. This file stores all messages generated by the script. The default value is u.msg. The default messages will be printed if this file does not exist.
$TEMPLATE_DIRECTORY
Template directory. This directory contains *.tpl, *.css, and *.js files that customize the look of the site. The default value is u.tpl. The default template will be used if this directory does not exist.
$PAGE_NAME_STYLE
Page name style. This variable determines how to name the HTML, source text and version files of pages. This setting has three parts: case, dots, and spaces separated by a colon (:).
Case
lower_case
All lower case (e.g., page in a uniqki site). This case is the deault.
upper_case
All upper case (e.g., PAGE IN A UNIQKI SITE).
mixed_case
No special handling of letter case or as-is (e.g., Page in a Uniqki site).
start_case
Start case (e.g., Page In A Uniqki Site).
lower_camel_case
Lower camel case (e.g., pageInAUniqkiSite).
upper_camel_case
Upper camel case (e.g., PageInAUniqkiSite).
Dots
dots
Replace a series of dots in page names with a dot. Dots separate words for a case conversion. This value is the default.
no_dots
Remove dots from page names. The lower_camel_case and upper_camel_case styles imply this option. For example, upper_camel_case is the same as start_case:no_dots:no_spaces.
Spaces
hyphens
Replace a series of whitespaces in page names with a hyphen. This value is the default.
underscores
Replace a series of whitespaces in page names with an underscore.
no_spaces
Remove whitespaces from page names. The lower_camel_case and upper_camel_case styles imply this option. For example, lower_camel_case is the same as lower_camel_case:no_dots:no_spaces.

Other than dots and spaces, the following special characters will be replaced with spaces and separate words before a case conversion: `~!@#$%^&*=+\|;:'",/?()[]{}<>. Hyphens (-) and underscores (_) will be converted to spaces and may be converted back to hyphens or underscores depending on the page name style.
For example, 'page' in a uniqki site!!! in the start_case style will create and link to Page-In-A-Uniqki-Site.html. The same page name in the upper_camel_case style will use PageInAUniqkiSite.html.
The default value is lower_case:dots:hyphens.
$INACTIVE_TIMEOUT
Login session will be extended by this number of minutes whenever any action is taken by the user. The default value is 24*60 minutes or 1 day.
$SET_PASSWORD_TIMEOUT
Change the password within this timeout in minutes. The default value is 60 minutes or 1 hour.
$RESET_PASSWORD_TIMEOUT
Reset the password within this timeout in minutes. The deault value is 1 minute.
$EMAIL_ADDRESS
Email address from which user notifications are sent. Your Name <you@example.com> is not supported. Enter your email address only as in you@example.com. Make sure to use single quotes instead of double quotes. The default value is empty.
$SMTP
SMTP settings for user notifications. If this variable is empty, email will be sent using sendmail. The format of this variable is server:port:username:password. The password may contain colons (:), but the username cannot. The default value is empty.
$MIME_TYPE_COMMAND
Fallback command to determine MIME types in case the MIME::Types module is not installed or fails to determine the type. Setting this variable to an empty string will return an empty MIME type. The default value is /usr/bin/file --brief --mime-type.
$READ_ACCESS
Read access control. The following settings can be used to restrict read access:
open
Opens both non-wiki and wiki pages to the public and anyone will be able to read those pages with or without a login.
closed
Requires a login to perform any read actions including search, diff, etc. The directives in .htaccess shown in Figure 8 are required to prevent direct access to *.html files, effectively making the entire site read-secured.
admin
Allows only admin users access to non-wiki and wiki pages. The .htaccess directives in Figure 8 are required.

Non-wiki and wiki pages can have different settings separated by a colon. For example, closed:open means closed non-wiki and open wiki pages. One setting applies to both non-wiki and wiki pages. That is, open is the same as open:open (open non-wiki and open wiki).
Unless this variable is open or open:open, the .htaccess directives in Figure 8 are required to secure *.html files.
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_URI} !^/u$
RewriteRule ^([^/]*)$ u/$1 [R,L]
RewriteRule ^u/$ u [R,L]
RewriteRule ^([^/]*)\.html$ u/$1 [R,L]
RewriteRule ^(u/[^/]*)\.html$ $1 [R,L]
RewriteCond %{REQUEST_URI} !^/u($|[/?]|\.tpl/)
RewriteRule .* "-" [F]
Figure 8: Restrict direct access to HTML files for Apache

The default value is open. See access controls for more details.
$WRITE_ACCESS
Write access control. This variable only affect wiki pages. Creating new wiki pages also depends on $WIKI_PAGES_ALLOWED. For security reasons, non-wiki pages are writable only by admin users and this variable cannot affect that behavior. One of the following settings is supported:
open
Allows anyone to edit or create wiki pages with or without a login.
closed
Requires a login to edit or create wiki pages.
admin
Requires admin rights to edit or create wiki pages.

The default value is open. See access controls for more details.
$PAGES_NOT_ALLOWED
Regular expression for page names that are not allowed. The default value is empty, which means that any page names are allowed.
$USER_PARSERS_FILE
User parsers file. Custom parsers can be defined in this file. The default value is empty. See how to create plugins for more details.
$HEADER_FILE
Header file for the non-wiki and wiki parsers. This file will be parsed before the main text. The default value is empty.
$FOOTER_FILE
Footer file for the non-wiki and wiki parsers. This file will be parsed after the main text. The default value is empty.
$NONWIKI_HEADER_FILE
Header file for the non-wiki parser. This file will be parsed before the main wiki text. The default value is empty.
$NONWIKI_FOOTER_FILE
Footer file for the non-wiki parser. This file will be parsed after the main wiki text. The default value is empty.
$WIKI_HEADER_FILE
Header file for the wiki parser. This file will be parsed before the main wiki text. The default value is empty.
$WIKI_FOOTER_FILE
Footer file for the wiki parser. This file will be parsed after the main wiki text. The default value is empty.
$WIKI_PAGES_ALLOWED
Regular expression for wiki page names that are allowed to be created by non-admin users. The default value is empty, which means that no wiki pages can be created by non-admin users. See access controls for more details.
$WIKI_FILES_ALLOWED
Regular expression for file names that are allowed to be uploaded by non-admin users to a wiki page. The default value is \.(png|gif|jpg|jpeg|txt|zip)$. See access controls for more details.

9   Template

The default template files can be installed by running http://example.com/u?install_template. See how to create templates.

10   Messages

The default messages file can be installed by running http://example.com/u?install_messages. See how to customize messages.