Operating BSCW on Unix

Operating BSCW on Unix

Running BSCW on a Unix system generally requires little administrative effort. However, there are a few things that should be taken into consideration when installing and configuring the BSCW system.

Note:  Below are some general hints on installation and operation of BSCW servers. Further details are provided in the  Administrator Manual which should be read when installing a BSCW server.

BSCW Installation

Before installing BSCW please ensure the Python interpreter and the Apache web server are installed. On Linux systems you will additionally require a C compiler. Next extract the BSCW distributuion and run the BSCW installation script ("install.sh") as super user ("root"):

# tar xf bscw-5.1.?-4????-py27.tar.gz
# cd bscw-5.1.?-4????-py27
# ./install.sh

First the installation procedure looks for a BSCW system user "bscw" resp. requests a BSCW user name. If the specified user name does not exist, an according BSCW user account is created. Throughout the installation you will be asked for further defaults values.

We recommend the installation of the BSCW software for a dedicated user account. It doesn't matter where you install BSCW, but the host machine of the web server you wish to use must have access to the file system where BSCW is installed. For optimal performance, install BSCW on a file system local to the host where your web server runs.

The BSCW installation script ("install.sh") should be executed on this host, because the installation procedure will also start the BSCW database server that must run on the same host as the web server. The BSCW directory should not be accessible via the "DocumentRoot" of your web server, however.

The BSCW CGI scripts invoked by your web server will run with the "set-group-id" bit set. This means access rights will be inherited during execution. The directory, including all files and sub-directories, should belong to this group.

Note: Some Unix systems (for example Linux) refuse to execute scripts with "set-group-id". In this case a binary wrapper is installed (the BSCW installation script should do this automatically).

Configuration

The configuration includes your web server and the BSCW server. Furthermore, server administrator registration should be considered part of the initial configuration process.

Configuring your BSCW server requires editing a number of configuration files (see the admin manual for details). Most changes in the configuration files take immediate effect.

In case of any configuration problems, you may instruct BSCW to check the configuration by invoking the command

$ cd /opt/bscw/srv/[hostname]
$ ./bin/bsadmin chkconfig

Administration

The BSCW-System includes its own database server. The database server is operated via commandline (shell script: "bsadmin"). The most important commands are

$ cd /opt/bscw/srv/[hostname]
$ ./bin/start_servers
        starts the BSCW-Server
$ ./bin/start_servers -k 
        stops the BSCW-Server
$ ./bin/start_servers -gc 
        runs the garbage collector (the database server must be running)
$ ./bin/bsadmin 
        shows further commands.

It is recommended to start the BSCW-Server automatically while system boot using the "start_servers" command. The BSCW distribution offers boot scripts for several Unix derivatives. Furthermore the garbage collection should be automated to run periodically (daily).

Web server

To configure your web server, you must edit your web server configuration file and restart the server. For the Apache server, the BSCW installation process will automatically generate a configuration file ("bscw.conf"). In case of configuration changes to your BSCW server (e.g. modified script names), you may need to update this configuration file by invoking the command:

$ cd /opt/bscw/srv/[hostname]
$ ./bin/bsadmin conf_apache

We recommend to include the contents of this file in your Apache configuration file ("http.conf") by using the following directive

Include "/opt/bscw/srv/[hostname]/conf/apache24/bscw.conf"  

Additional configuration tips are provided in the README.txt file.