Tokyo Promenade: a content management system

Copyright (C) 2008-2010 FAL Labs
Last Update: Thu, 05 Aug 2010 15:55:46 +0900

Table of Contents

  1. Introduction
  2. Installation
  3. Deployment
  4. Administration
  5. License

Introduction

Tokyo Promenade is a kind of content management system. That is, Tokyo Promenade is a system in order to manage Web contents easily by providing total functions of browsing, authoring, editing Web contents on the Web interface itself. Tokyo Promenade has the following features.

Tokyo Promenade is available on platforms which have API conforming to C99 and POSIX. Tokyo Promenade is a free software licensed under the GNU General Public License.

Installation

Install the latest version of Tokyo Cabinet beforehand and get the package of Tokyo Promenade.

When an archive file of Tokyo Promenade is extracted, change the current working directory to the generated directory and perform installation.

Run the configuration script. To enable the Lua extension, add the `--enable-lua' option. To enable the FastCGI script, add the `--enable-fcgi' option.

./configure

Build programs.

make

Perform self-diagnostic test.

make check

Install programs. This operation must be carried out by the root user.

make install

When a series of work finishes, the following files will be installed.

/usr/local/bin/prommgr
/usr/local/libexec/promenade.cgi
/usr/local/libexec/promscrcount.lua
/usr/local/libexec/promupdiff.sh
/usr/local/libexec/promupping.sh
/usr/local/share/tokyopromenade/...
/usr/local/man/man1/...
/usr/local/man/man3/...

Deployment

Install an arbitrary web server which supports the CGI mechanism. Then, create a directory where CGI scripts can be executed. We call it the base directory, which contains some files of Tokyo Promenade.

mkdir -p /path/to/the/base/directory
cd /path/to/the/base/directory

Copy the CGI script and some configuration files into the base directory.

cp /usr/local/libexec/promenade.cgi .
cp /usr/local/share/tokyopromenade/promenade.* .
cp /usr/local/share/tokyopromenade/passwd.txt .

Create the database file where articles are stored.

prommgr create promenade.tct

Import the help articles into the database.

prommgr import promenade.tct /usr/local/share/tokyopromenade/misc/help-*.tpw

Create a directory where uploaded files are stored.

mkdir upload

The CGI script should have permissions to read/write the database file, the upload directory and the password file. To achieve the purpose, one of the following is suggested.

When all steps above are finished, access the CGI script with a Web browser.

Administration

The account for the administrator is prepared by default. The name is "admin" and the default password is "nimda". After the deployment of the site, what to do first is to login as the administrator and change the password.

To login, select the "Login" link in the navigation bar on the top of the page. The login form is shown and then input the user name and the password. After the login operation, some links are added to the navigation bar. Select the "Users" link and the user management form is shown and then input the new password twice in the "change password" column for the administrator and press the "change" button.

To update the site contents, authorization by the login operation is needed. And, the administrator only has privilege of the user management and freezing articles. Adding the "*" tag to the tag attribute of each article means freezing the article. Such frozen articles is not editable by users except for administrator.

By default, an anchor string "About" in the navigation bar links to an article whose name is "tp-about". Because the article is not defined, you should select the link and write it at the start. Note that the "?" tag means to hide the article from the timeline page.

The command `prommgr' is a command line utility. The usage is the following.

prommgr create [-fts] dbpath [scale]
Create the database.
`dbpath' specifies the path of the database.
`scale' specifies the expected number of articles.
prommgr import [-suf str] dbpath file ...
Import article files into the database.
`dbpath' specifies the path of the database.
`file' specifies the input file. If it is a directory, the content files whose suffix is ".tpw" are processed.
`-suf str' specifies the suffix described above.
prommgr export [-dir str] dbpath [id]
Export article files from the database.
`dbpath' specifies the path of the database.
`id' specifies the ID number of the target article. If it is specifies, the result is printed into the standard output.
`-dir str' specifies the path of the output directory.
prommgr update dbpath id [file]
Update an article in the database.
`dbpath' specifies the path of the database.
`id' specifies the ID number of the target article. If it is 0, the ID is generated and automatically.
`file' specifies the path of the wiki data of the article. If it is omitted, the standard input is read.
prommgr remove dbpath id
Remove an article from the database.
`id' specifies the ID number of the target article.
prommgr convert [-fw|-ft] [-buri str] [-duri str] [-page] [file]
Convert an article file into other formats. By default, the HTML format is specified.
`file' specifies the input file.
`-fw' specifies the Wiki format.
`-ft' specifies the plain-text format.
`-buri str' specifies the base URI.
`-duri str' specifies the URI of the data directory.
`-page' specifies to output the page header and the page footer.
prommgr passwd [-salt str] [-info str] name pass
Generate password strings.
`name' specifies the user name.
`pass' specifies the user password.
`-salt str' specifies the salt string.
`-info str' specifies the miscellaneous information field.
prommgr version
Print the version information.

To add users by batch processing, the `passwd' subcommand is useful. Take the following for example.

prommgr passwd -salt tokyopromenade -info "John Doe" "john" "iloveyou"

To backup the database and the upload directory, simply use the `tar' command.

tar zcvf mybackup-20090810.tar.gz promenade.tct* upload

To customize the behavior of the CGI script, edit the template file `promenade.tmpl'. The following configuration variables are defined there.

The other sections of the template file describes the output data in HTML and Atom. The file `promenade.css' is the CSS file to decorate HTML. You can modify them arbitrary to customize the user interface.

If the `password' is omitted or empty, authentication is disabled and all visitors can update all contents without the login operation.

The `mimerule' can be "auto", "xhtml", or "html". "auto" means that the MIME type is detected with adapted to the ability to user agents. "xhtml" means the MIME type is always XHTML. "html" means the MIME type is always HTML.

The `commentmode' can be "all", "riddle", "login", or "none". "all" means that all visitors can write comments. "riddle" means that users who cleared a riddle can write comments. "login" means that login users only can write comments. "none" means no user can write comments. If the `frontpage' does not specified, the top page shows the timeline of recent articles.

The `scrext' specifies the path of a Lua script file. It works only when Tokyo Promenade was built with enabling the Lua extension. There is naming convention of functions to be called. The function "_begin" is called before the database is opened, and receives no parameter, and returns a message string to be shown by the template variable "beginmsg". The function "_end" is called before the database is opened, and receives no parameter, and returns a message string to be shown by the template variable "endmsg". The function "_procart" is called for each article to be printed, and receives the Wiki string of the article, and returns the converted Wiki string. The function "_procpage" is called to convert the HTML string of the whole page to be printed, and receives the HTML string of the whole page, and returns the converted HTML string. The configuration variables of the template file are given as a table of the global variable "_conf". The parameters of the CGI script are given as a table of the global variable "_params". The login user information is given as a table of the global variable "_user". The built-in functions "_strstr" and "_regex" are provided for pattern matching and replacement. The both takes three parameters; the first is the source string, the second is the matching pattern, and the third is the replacement string. The third is optional and matching is just checked if it is omitted. The following Lua script files are installed under "/usr/local/libexec" by default.

The `updatecmd' specifies the path of a command file, which is called after every article is updated. The script receives seven parameters. The first is one of the following operation modes: "new", "update", "comment", and "remove". The second is the ID number of the updated article. The third is the name of the cache file of the new content. The fourth is the name of the cache file of the old content. The fifth is the timestamp in microseconds. The sixth parameter is the name of the user of the update operation. The seventh parameter is the absolute URL of the SGI script. The configuration variables of the template file are given as environment variables whose names are led with the prefix "TP_" and transformed into upper cases. The following shell script files are installed under "/usr/local/libexec" by default.

According to this tutorial, the password file is placed under the document root of the web server and it is revealed to the internet. However, it is safer to hide the password file into another directory which is not published, though each password is ciphered.

License

Tokyo Promenade is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

Tokyo Promenade is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see `http://www.gnu.org/licenses/'.

Tokyo Promenade was written by FAL Labs. You can contact the author by e-mail to `info@fallabs.com'.