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:


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:

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.

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.