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.
Perl module | Purpose | If not installed |
---|---|---|
POSIX * | Time zone and format | Use scalar localtime |
Encode * | Decode diff lines to $CHARSET | Print undecoded diff lines |
MIME::Types | File download | Use the $MIME_TYPE_COMMAND setting |
MIME::Lite | Email notifications | Print an error message and stop |
Archive::Zip | Backup and restore | Print an error message and stop |
IO::Socket::INET * | Embedded web server | Print an error message and stop |
IO::Socket::SSL | Embedded web server on HTTPS | Print 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.
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.
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.
Click the Login link and type “admin” in both username and password fields as shown in Figure 4.
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.
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.
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.
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 fileu
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 toPage-In-A-Uniqki-Site.html
. The same page name in the upper_camel_case style will usePageInAUniqkiSite.html
.
The default value islower_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 inyou@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 isopen
oropen:open
, the .htaccess directives in Figure 8 are required to secure *.html files.
The default value isopen
. 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 isopen
. 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.