;; This document is written in WiLiKi format.
;; See: http://practical-scheme.net/wiliki/wiliki.cgi?WiLiKi&l=en
;;
;; $Id: INSTALL,v 1.14.2.1 2007/01/18 05:26:15 bizenn Exp $

* Setup Kahua

** Preparation

*** Installing Gauche

To use Kahua, you need Gauche 0.8.8 or later that supports pthread.
But Gauche 0.8.8 has several serious bugs, so we strongly recommend
to use Gauche 0.8.9 or later.
{{{
$ gosh -V
Gauche scheme interpreter, version 0.8.9 [utf-8,pthreads]
}}}

If you have not installed proper version of Gauche, please install new
version.

----
** Let's try Kahua

*** Building from tarball

If you just want to try Kahua, a recommended way is to install
under your home directroy.  By this way you don't need to
care about permissions and user/group settings.

{{{
% tar xvzf Kahua-1.0.1.tgz
% cd Kahua-1.0
% ./configure --prefix=$HOME/kahua
% make
% make check
% make install
% make install-examples
}}}

This will build the system from the source code and install it under
the ${HOME}/kahua directory.  It will help you to add
${HOME}/kahua/bin directory to your PATH.

*** Starting Kahua

After having installed, you can easily try Kahua by running the
standalone server: 

% ($HOME/kahua/bin/kahua-spvr --httpd localhost:8888 >>/tmp/kahua-error.log &)

You can set any port number except privileged ones.
If you appoint only port number, you can bind server socket to 0.0.0.0(or[::]).

Then, start a browser and visit http://localhost:8888/.
You will see and can use one of sample applications, "lambdabooks".


----

** Proper Installation procedure

If you'd like to install Kahua as root into the system area,
you should know about Kahua a little more, and need to follow
several steps.

*** Users and Processes in Kahua

In Kahua system, there are 3 categories processes.
They run under different user privileges and communicate with
each other.

# Kahua Servers(Process: kahua-spvr, kahua-server, kahua-keyserv)
# Kahua Bridges(Process: kahua.cgi, kahua.fcg, kahua-httpd)
# Kahua Administrator and Application Developer
  (Real users use kahua-admin and kahua-user)

All of them must be able to read and write the same UNIX domain
socket.  And Kahua Servers and Kahua Bridges must be able to
read and write temporary files under the same directory.

*** Create group "kahua"

You should create a new group, and add all above users to it,
so that all Kahua processes communicate with each other via
the same UNIX domain socket.
{{{
# groupadd kahua
}}}

Some operating system have some different commands to do the
same task.  Please see your system manuals.

*** Create user "kahua"

You should run Kahua Servers(kahua-spvr and scripts invoked by it)
under a UNIX user privilege only for them.  Now we assume the user
is "kahua".
{{{
# useradd -g kahua kahua
}}}

*** Add other users to group "kahua"

Now you should add the user under which Kahua Bridges run and
Kahua administorators and application developers (they are real users)
to group "kahua" created above.

Kahua Bridge CGI scripts (kahua.cgi/kahua.fcg) are generally
invoked by Web server(like Apache httpd or lighttpd).  We assume that
the Web server runs as user "www" (and you don't use suEXEC).
{{{
# usermod -G kahua www
}}}
You may need to restart the Web server to reflect this change.

Kahua administrators and application developers should be added
to group "kahua" in the same way.
{{{
# usermod -G kahua taro
# usermod -G kahua hanako
}}}
and so on.

*** Configuration and building

Kahua is made up of almost pure Scheme(Gauche) scripts and a few shell
scripts, but its configuration requires a careful attention.

This is configuration and building process on a real site.
{{{
% tar xzvf Kahua-1.0.1.tgz
% cd Kahua-1.0.1
% ./configure \
    --with-kahua-user=kahua --with-kahua-group=kahua --with-cgi-user=www \
    --prefix=/usr/local/kahua \
    --sysconfdir=/usr/local/etc \
    --localstatedir=/var/local \
    --with-cgidir=/var/local/www/cgi-bin \
    --with-cgilogdir=/var/log/kahua/cgi \
    --with-staticdir=/var/local/www/htdocs/kahua-data \
    --with-fastcgi=yes
% make
}}}
You can use GNU make or BSD make.  If you fail with BSD make, Please
try GNU make and report us what is wrong with BSD make.

**** configure options

Please see message of
{{{
% ./configure --help
}}}
but we describe some important options.
{{{
 --with-kahua-user

     User name under which Kahua Servers run.  Default: not specified.

 --with-kahua-group

     Group name that all users related to Kahua System must belong to.
     Default: not specified.

 --with-cgi-user

     User name under which Kahua Bridge CGI scripts(kahua.cgi/kahua.fcg)
     run. Generally it is the same user under which the Web server runs.
     Default: not specified.

 --with-cgidir

     Directory path where Kahua Bridge CGI scripts are installed.
     It depends on your Web server configuration.
     Default: ${libexecdir}/kahua

 --with-cgilogdir

     Directory path where Kahua Bridge CGI scripts write out log
     files.  Default: ${localstatedir}/kahua/cgilog

 --prefix, --exec-prefix, ...

     Standard configure options.  Generally you'd like to set --prefix,
     --localstatedir, --sysconfdir and so on.  Kahua applications,
     Kahua databases, log directories are normally deployed under
     ${localstatedir}/kahua, and the configuration file is
     ${sysconfdir}/etc/kahua.conf.

 --with-staticdir

     Kahua Servers and kahua-httpd search static contents(image files,
     CSS files, etc...) under this directory.
     Default: ${localstatedir}/kahua/static

 --with-fastcgi

     Install kahua.fcg, a Kahua Bridge FastCGI script.  You must
     install Gauche-fastcgi extension in advance.  Default: no
}}}

*** Self check

Just do this:
{{{
% make check
}}}

*** Installation

Execute these commands as root.
{{{
% su
# make install
}}}

If you'd like to install sample applications,
you should execute this command as a Kahua developer(not root).
{{{
% make install-examples
}}}
And you must fix owner/group of the sample database like this:
{{{
% su
# chown -R kahua:kahua /usr/local/kahua/var/kahua/db*
}}}
You need * tail of above command line.  Don't forget it.

*** Starting Kahua Servers

Congratulations!  Now you can start Kahua Servers.
Kahua Servers should be invoked under "kahua" user privilege.
{{{
# su kahua -c ${prefix}/bin/kahua-spvr
}}}
This command invokes kahua-spvr, Kahua Supervisor command, and
it invokes kahua workers(kahua-server) and a key server(kahua-keyserv).
If you want to use it with Kahua Web Server(kahua-httpd), you
just do this:
{{{
# su kahua -c ${prefix}/bin/kahua-spvr --httpd localhost:8888
}}}
If you want that Kahua Servers run as background processes,
you just do like this:
{{{
# su kahua -c "(${prefix}/bin/kahua-spvr >>${localstatedir}/kahua/logs/kahua-error.log 2>&1 &)"
}}}

Kahua System doesn't yet have any mechanism that registers its startup
scripts to the operating system.  You must create them by hand, or you can
use "daemontools" to manage Kahua Servers processes.

----

** Use "Site-Bundle"

"Site-Bundle" is the new feature mounted from Kahua 0.8.  It is an
abstraction of the working directory where kahua servers are
activating. By this feature, you can control several kahua servers,
kahua-spvr and its following servers, under the single kahua install
base.

*** Create a "Site-Bundle"

Execute following command with kahua-spvr authorization that meets to
the site to create.
{{{
% kahua-package create /var/tmp/kahua
}}}
The Skelton of site is created with this.  Followings are the
explanation of directory structure.
{{{
% find /var/tmp/kahua
/var/tmp/kahua
/var/tmp/kahua/app
/var/tmp/kahua/app-servers
/var/tmp/kahua/database
/var/tmp/kahua/etc
/var/tmp/kahua/etc/kahua.conf
/var/tmp/kahua/etc/user.conf
/var/tmp/kahua/logs
/var/tmp/kahua/plugins
/var/tmp/kahua/run
/var/tmp/kahua/socket
/var/tmp/kahua/static
/var/tmp/kahua/tmp
}}}
It seems to be same as standard working directory, but there are some
different points.

# '''app''':
For historical background, "checkout" is used in the standard working
directory. Dig sub directory here for each application and deploy
source file.
# '''database''':
The database is deployed under the file-system-database directory
instead of under the working directory.
# '''etc''':
The configuration files which "kahua-* scripts", activating on the
"Site-Bundle", refer to, and developer user database are deployed
here.  If you use "Site-Bundle", "kahua-* scripts" do not refer to
standard configuration files.
# '''logs''':
Store log files.
# '''plugins''':
Deploy plug-in files.  Under the current situation, if you want to use
standard plug-in installed with Kahua in "Site-Bundle", you need to
copy.
# '''run''':
Store PID files.
# '''socket''':
Deploy UNIX domain socket to use in connection by Kahua servers.
# '''static''':
Deploy static contents.
# '''tmp''':
This is a temporary directory.

*** Activate kahua-spvr on "Site-Bundle"

Execute following command with same authorization that creates "Site-Bundle".
{{{
% kahua-spvr -S /var/tmp/kahua --httpd 8889
}}}
Set full path to "Site-Bundle" after "-S".

Execute following command to connect kahua-admin to this kahua-spvr.
{{{
% kahua-admin -S /var/tmp/kahua
}}}

Additionally, you can set to use "Site-Bundle" by default in its
environment variable, KAHUA_DEFAULT_SITE.
{{{
% export KAHUA_DEFAULT_SITE=/var/tmp/kahua
% kahua-spvr --httpd 8889
}}}
By this new feature, "Site-Bundle", user-mode was abolished.
