Running Krang on Your Local Desktop

This document is a guide on how to set up Krang in your local desktop environment.

If you are doing any sort of Krang development (element library, templates, Krang itself), this document is of interest to you. Being able to run Krang locally can make development a much faster process, and you don't need to worry about clobbering other people if you make changes during development.

Before you start, you should be comfortable with a Unix/Linux environment - you may need to install software packages that Krang depends on.

NOTE: This document assumes that you're not currently running a local webserver on port 80 (go to http://localhost:80 with any web browser to confirm if you're unsure - you should get a ``Connection Refused''-type message).

What you need:

root access on a Krang-friendly machine (A number of flavors of Linux, FreeBSD, Mac OSX and Solaris all fit the bill).

It may be possible to configure Krang without root access, but that's beyond the scope of this document at the moment.

A binary release of Krang tailored for your system, or the source tarball.

Initial Setup

The process for building and installing Krang is covered in Installing Krang. A few things to keep in mind as you go through the process.

When running krang_install:

• HostName
  
localhost is fine.
• IPAddress
  
Use 127.0.0.1 - 127.0.0.1 is ALWAYS the current machine.
• KrangUser
  
Your user account is a good choice. This will give your user account permissions to modify any file in your installed copy of Krang.
• KrangGroup
  
The default group for your user account is also a good choice.
• InstanceHostName, InstanceDBName, InstanceElementSet
  
Every Krang installation needs a minimum of one instance. This guide will use ``cms.testsite.kra'', ``testsite'', and ``Default'', respectively.

The resulting installation string should look something like this:

  # ./bin/krang_install \
         --HostName             localhost            \
         --IPAddress            127.0.0.1            \
         --AdminPassword        $AdminPassword       \
         --DBUser               $DBUser              \
         --DBPass               $DBPass              \
         --InstanceDBName       testsite             \
         --InstanceHostName     cms.testsite.kra     \
         --InstanceElementSet   Default              \
         --KrangUser            joeuser              \
         --KrangGroup           users

Once krang_install is done, you should be on your way!

Open up a web browser, and go to

  http://localhost

You should be presented with a ``Welcome to Krang'' page, and a listing for cms.testsite.kra. Click on the link. At the login, your username will be admin, your password is the $AdminPassword that you set when calling krang_install.

Congratulations, you are in!

NOTE: Don't worry about the .kra extension - it was chosen simply to make sure that we wouldn't clobber a real site you might use - like testsite.com, testsite.net, you get the idea.

Configuring a Site

With Krang now up and running, the first thing you need to do is create a site.

Under the sites menu (underneath Admin), choose the ``Add a site'' option.
• URL
  
The URL of your ``live'' site:

  testsite.kra:8080

• Preview URL
  
The URL for the preview version of your site:

  preview.testsite.kra:8080

• Publish Path
  
The website root for testsite.kra. You want to choose a directory path that KrangUser has write-access to.

I generally choose a path in /tmp, such as:

  /tmp/krang/testsite.kra

The drawback to using /tmp on some systems is that it may be too small for real use. A directory in your home directory works just as well, or even a path in the Krang install path (e.g. KRANG_ROOT)!

  /path/to/installed/krang/tmp/testsite.kra

Is a good choice as well.

• Preview Path
  
Same as Publish Path - put it in the same location, just call it preview.testsite.kra.

NOTE: Notice the :8080 on the end of the publish and preview URLs? That is intentional. Pay attention to the next step.

Configuring SiteServer

SiteServer was created to make it easy for developers to see preview/publish website functionality without having to delve into configuring Apache.

SiteServer is part of Krang::Handler, and works as an apache transhandler, mapping requests to the preview and publish paths that we configured above.

Add the following lines to the main section (before the <Instance> section) of conf/krang.conf:

  #
  # EnableSiteServer: the site server offers developers a means to test
  # preview and publish without requiring a separate Apache setup.  If
  # set to 1 then SiteServerAddr and SiteServerPort must be defined and
  # must differ from the ApacheAddr and ApachePort settings.
  #
  EnableSiteServer 1
  SiteServerAddr 127.0.0.1
  SiteServerPort 8080

This tells SiteServer to listen on port 8080 (consistent with the :8080 in the Publish URL and Preview URL directives above) and attempt to map incoming requests.

Restart Krang to have the changes take effect.

REMEMBER: you most likely need to be root to restart Krang - look into using sudo to make things easier.

As root:

  # bin/krang_ctl restart

As your everyday user w/ sudo properly configured:

  $ sudo bin/krang_ctl restart

The /etc/hosts file

The last thing to change - the /etc/hosts file.

The /etc/hosts file, if you're not familiar with it, is a way to shortcut DNS lookups. When your system tries to resolve a machine name (e.g. krang.sourceforge.net), the first place it will look is the /etc/hosts file.

Add the following to your /etc/hosts file (you will most likely need to be root to do this):

  # Local Krang CMS, and test publish/preview sites.
  127.0.0.1     cms.testsite.kra
  127.0.0.1     testsite.kra
  127.0.0.1     preview.testsite.kra

Re-start your web browser. The reason is this - most web browsers (IE and Mozilla/Firefox included) cache IP addresses after a lookup. If by any chance your browser already has an IP address for testsite.kra, it will ignore the changes you just made to /etc/hosts.

Log back into the Krang UI. Rather than using http://localhost, try http://cms.testsite.kra - you should be taken directly to the login screen you saw previously.

You now have a fully configured Krang instance running on your local machine. Preview and Publish should now work as designed, and your setup should behave like any normal Krang setup.