Installing Krang

This document describes how to install Krang on your system.

Supported Platforms

Krang supports the following operating system platforms:

Redhat Linux 7.3 and 9
Fedora Core 1 and 2
Gentoo Linux 1.4.3
FreeBSD 5.2.1
Debian 3.0 (Woody)

Krang will likely compile fine on other similar platforms, but you'll need to download the source distribution and build it yourself. See Building Krang from Source.

Software Requirements

Before you can install Krang you'll need Perl version 5.6.1 or later and MySQL version 4.0.13 or later. You can download Perl here:

  http://www.perl.com/download.csp

And MySQL 4 can be found here:

  http://www.mysql.com/downloads/mysql-4.0.html

Krang may require additional software, depending on your operating system. Be sure to read the platform-specific README (eg. README.Redhat9) included with Krang.

Choosing a Distribution

When you download Krang you must choose a distribution that matches your operating system and version of Perl. If you don't know what version of Perl you have, run this command on your command-line:

  perl -MConfig -e 'printf "perl%d.%d.%d-%s",
                    (map { ord($_) } split("", $^V, 3)), $Config{archname}'

This will print something like:

  perl5.6.1-i686-linux

Using this information, if you wanted to install Krang 1.013 on Redhat 7.3 you would download:

  krang-1.013-Redhat7_3-perl5.6.1-i686-linux.tar.gz

Krang also has a special source distribution with -src instead of a platform description (ex: krang-1.013-src.tar.gz). You can download this release and attempt to build Krang from source. Of course, this may require porting work if Krang doesn't support your platform.

Building Krang from Source

If you downloaded the source distribution (ex: krang-1.013-src.tar.gz) then you'll need to build Krang before you can install it. If you've got a binary distribution, skip ahead to Installation.

First, untar the source tar-ball and enter the directory:

  tar zxvf krang-1.013-src.tar.gz
  cd krang-1.013-src

If there's a README file for your platform (ex: README.FreeBSD5), read that now. It will tell you about software you'll need to install before building Krang.

Now try building Krang using the bin/krang_build script:

  bin/krang_build

To build a version of krang that supports SSL, then supply the with-ssl option.

  bin/krang_build --with-ssl

If Krang complains that it doesn't know what platform to build for you can pass it a platform name:

  bin/krang_build Redhat9

If that works, you can now build a binary distribution for your platform and proceed to the next step:

  bin/krang_makedist

If not, you'll have to do some porting work to get Krang working on your system. To learn more about porting Krang, read this:

  http://krang.sourceforge.net/docs/porting.html

Installation

Once you've downloaded a Krang binary distribution, or built one from source, un-tar it and enter the directory created:

  tar zxvf krang-1.013-Redhat7_3-perl5.6.1-i686-linux.tar.gz
  cd krang-1.013-Redhat7_3-perl5.6.1-i686-linux

To install, run bin/krang_install as root, providing options describing how to setup Krang:

  # ./bin/krang_install \
         --HostName             $HostName            \
         --IPAddress            $IPAddress           \
         --AdminPassword        $AdminPassword       \
         --DBUser               $DBUser              \
         --DBPass               $DBPass              \
         --InstanceDBName       $InstanceDBName      \
         --InstanceHostName     $InstanceHostName    \
         --InstanceElementSet   $InstanceElementSet

These options are described below.

Localization

After installing Krang, you may optionally install localization distributions. To install the localization distribution for German, download Krang-Localization-Deutsch-VERSION.tar.gz and install it using lang/bin/krang_lang_installer:

  lang/bin/krang_lang_installer Krang-Localization-Deutsch-VERSION.tar.gz

Note that the VERSION number must be the same as the Version of Krang itself.

Required Variables

Before you install you must gather the following information. The following variables should be replaced in example shell commands with the appropriate values.

• HostName
  
Host name used for Krang's main Apache virtual host (e.g., ``cms23.foo.com''). This is the master host which provides a list of all configured Krang instances. Often this is the hostname of the machine itself, although systems with multiple Krang installations must choose different HostNames for each.
• IPAddress
  
IP address used for the Krang Apache server and FTP server. You'll need to arrange DNS to point this IPAddress at HostName.
• AdminPassword
  
Password assigned to the ``admin'' Krang user (e.g., ``whale''). This is the password you'll provide when you first log-in to the Krang system.
• DBUser
  
Name of MySQL user which is used by this CMS installation (e.g., ``krangdb''). This user will be created if it does not exist.
• DBPass
  
MySQL user password which is used by this Krang installation (e.g., ``xyzzy''). If the MySQL user already exists this must be the correct password for the user.
• InstanceDBName
  
Krang can contain multiple instances, but just one is setup by krang_install. This parameter names that database. Typically this will be the name of your first site, eg. ``coolmagazine1''.
• InstanceHostName
  
Host name for the virtual host connected directly to the instance powered by InstanceDBName, typically something like ``cms.coolmagazine1.com''. You'll need to arrange DNS to point IPAddress at InstanceHostName.
• InstanceElementSet
  
Name of element set used by this instance. Possible values are directories under the element_lib directory. If you're not ready to choose an element set yet, just use ``Default''.

Optional Variables

Other variables may be required, depending on your installation needs:

• MySQLRootPassword
  
Defaults to ``'' (none). The password for the MySQL user ``root'' who is assumed to exist, and to have full access to MySQL. If the ``root'' user doesn't exist or has restricted access you must change your MySQL configuration before installing Krang.
• InstallPath
  
Defaults to ``/usr/local/krang''. Directory into which Krang should be installed.
• KrangUser
  
Defaults to ``krang''. UNIX user for process ownership (Apache, etc.), file ownership and install location. This user will be created if it does not exist.
• KrangGroup
  
Defaults to ``krang''. UNIX group for process ownership (Apache, etc.), file ownership and install location. This group will be created if it does not exist.
• FTPPort
  
Defaults to 21. Port on which FTP server should run.
• ApachePort
  
Defaults to 80. Port on which the Apache server should run.
• SMTPServer
  
Defaults to localhost (127.0.0.1). Address of SMTP mail server used by Krang for sending email alerts.
• InstanceDisplayName
  
Defaults to $InstanceHostName. Name of the Instance, displayed on the CMS interface for informational purposes.
• WithAddon
  
This option provides an addon which will be installed with Krang. Krang addons can provide element sets, libraries and other services. You can specify multiple addons to install by repeating this option.
• DBSock
  
This option is used to specify the location of your MySQL server's socket file. You should only need to specify this directive if you get errors such as ``DBI connect(...) failed: Can't connect to local MySQL server through socket '/some/nonexistent/file''' in DBI.pm whenever krang tries to connect to your (local) MySQL server.

How to determine the correct socket path and filename to specify here, that will correct the error above on a given system is a troubleshooting task that is beyond the scope of these docs, but your MySQL server's my.cnf file might be a good place to begin looking for clues.

• EnableSSL
  
Boolean flag indicating whether or not this instance of Krang will run over SSL (will only work if this Krang was built with the with-ssl option. See Building Krang from Source.)

When SSL is enabled and Krang is restarted, it will look for it's SSL certificate and key in the following locations:

    KRANG_ROOT/conf/ssl.crt/server.crt
    KRANG_ROOT/conf/ssl.key/server.key

If your server.key is encrypted, then you should look at setting the SSLPassPhraseDialog in your krang.conf (see http://www.modssl.org/docs/2.8/ssl_reference.html for more details).

• SSLApachePort
  
Defaults to 443. Port on which the Apache server will listen for SSL requests.
• DefaultLanguage
  
Defaults to 'en' (English). This must be a RFC3066-style language tag representing either the English default or the root directory of some localization distribution you are going to install below lang/. The DefaultLanguage will be used on the Login screen and when a user has not yet set his language preference.
• AvailableLanguages
  
A list of RFC3066-style language tags (at a minimum 'en', the English default). The specified languages will show up in the language selector on the preferences screen and allow the user to select the language of the Krang UI. For this to work, you have to install the corresponding Krang localization distributions after installing Krang itself. To install a localization distribution use the script lang/bin/krang_lang_installer.

Some definitions

• Installation
  
A particular version of Krang installed on a server. A single host server may have multiple installations, but this would be rare outside of development. A single installation may have multiple ``Instances''.
• Instance
  
A particular database, host name and element set within Krang. Multiple instances may exist within a particular Krang installation. A single instance may have multiple ``Sites''.
• Site
  
A website managed by Krang. Multiple sites may exist within a particular Krang instance. Unlike Installations and Instances, Sites are not installed via this installation process. Sites are configured from the Krang web interface.