== LOona ==

 === Tiny CMS and Homepage Maker ===

 - Copyright © 2007, Timm S. Müller

 - Copyright © 2003-2006 The Kepler Project

 - LOona is released under the terms of the free MIT software license,

 see also COPYRIGHT

 === About ===

 LOona is halfway between a WIKI and a Content Management System (CMS)

 for managing website content. It is small, fast and extensible and

 written with security, robustness and a small resource footprint in

 mind. It requires no database, as pages are dynamically generated

 from plain text. In this way, website content can be created using a

 browser and a text editor in a similar fashion. LOona uses its own

 WIKI-like markup notation, but unlike a WIKI, its site structure is

 hierarchical.

 When running out of the box, LOona is a tool for producing simple

 sites for small projects and businesses. Using its extension

 facility, it can be employed for applications of all kinds. For

 example, LOona has recently been tailored to a telephony system under

 resource-constrained conditions.

 LOona was originally created during an employment at the LSE Leading

 Security Experts GmbH, and thanks to LSE's friendly support, it has

 been continued as an Open Source effort.

 === Selected features ===

  * Any number of text bodies, news boxes, etc.

  * Several users can modify a site at the same time

  * Different versions of a site can be edited without disturbing the

  published content

  * Sites can be multilingual and automatically detect the

  browser-preferred language

  * Full Unicode support, localized interfaces (English and German

  locales are included)

  * Non-varying website content is automatically rolled out to static

  pages and served right off the filesystem

  * Can restrict site modifications to HTTPS connections

  * Supports an extension mechanism for easy embedding of

  site-specific features, such as site search, contact forms,

  splash screens, prompts to accept a disclaimer, news, guestbooks and

  database-driven content

 == Prerequisites ==

 LOona has been developed and tested under Linux using the Apache 2.0

 webserver. Ports to different environments should be possible and

 straightforward, but this documentation will not try to go into

 detail about the peculiarities.

  * Make sure that your filesystem supports access times.

  LOona depends on this feature for session expiration.

  * Enable {{mod_unique}} in Apache.

  LOona obtains session IDs using this module.

  * Install the Lua 5.1 interpreter.

  The default build/install procedure on Linux looks like this:

    % wget http://lua.org/ftp/lua-5.1.2.tar.gz

    % tar -xzf lua-5.1.2.tar.gz

    % cd lua-5.1.2

    % make linux

    % sudo make install

 '''NOTE''': If you choose to install Lua somewhere else than in

 {{/usr/local/}}, you will have to adjust the shebang in

 {{cgi-bin/loona.cgi}} accordingly.

  * Optionally, get the Mercurial version control system to obtain a

  clone of LOona's source code repository. See references below.

 == Installation ==

 Aside from the Lua interpreter, LOona is largely self-contained and

 requires no system-wide installation.  The idea is that everything

 runs straight out of the directory in which LOona resides, therefore

 it is recommended to keep its structure intact. (Also note that an

 installation of Kepler is not required.)

  - 1. Clone the LOona repository to a location in your filesystem

  that you designate for serving website content. I suggest to create

  a local copy for each name-based virtual host, and to name it

  accordingly:

    % cd /www/loona

    % hg clone http://hg.teklib.org/loona mycompany.com

    % cd mycompany.com

  - 2. Adjust {{LANGUAGE}}, {{WWWUSER}} and {{GROUP}} in the top-level

  Makefile, or override these settings in the commandline to

  complement your setup. Use {{make help}} to verify your

  configuration, e.g.:

    % LANGUAGE=de GROUP=admin make help

   '''NOTE''': {{LANGUAGE}} is the default/fallback language for which

   the initial site structure will be generated. {{WWWUSER}} is the

   user under which the webserver is running (usually {{apache}} or

   {{wwwrun}}). For {{GROUP}} choose the group of site administrators,

   or your own group.

  - 3. Configure the site

   Enter the {{etc/}} directory and create a password file named

   {{passwd.lua}} using {{passwd.lua.sample}} as a template.

   Optionally, create a configuration file named {{config.lua}} (using

   {{config.lua.sample}} as a template), but this is not strictly

   required as long as you are happy with the default configuration.

   '''NOTE'''': If you plan on setting up a site with another

   default/fallback language than English, you need a configuration

   file with the {{deflang}} item set to this language.

  - 4. Back in the main directory, build modules:

    % make modules

  - 5. Setup an initial site structure:

    % make setup

  - 6. Adjust the permissions:

    % sudo make permissions

  - 7. Point your webserver's document root to the {{htdocs/}}

  directory and the script path to {{cgi-bin/}}. Add a script handler

  for the extension {{.lua}}, as follows:

    <VirtualHost *:80>

      ServerName mycompany.com

      DocumentRoot "/www/loona/mycompany.com/htdocs"

      ScriptAlias /cgi-bin/ "/www/loona/mycompany.com/cgi-bin/"

      <Directory "/www/loona/mycompany.com/htdocs">

        Options +MultiViews

        AddHandler lua-script .lua

        Action lua-script /cgi-bin/loona.cgi

        DirectoryIndex index.html index.lua

      </Directory>

    </VirtualHost>

  The {{MultiViews}} option is only needed for multilingual sites. If

  a profile exists for more than one language, LOona renders static

  HTML pages with a language suffix added to their filename, like so:

    index.html.en

    index.html.fr

    index.html.jp

  - 8. You should now be able to login to an empty LOona site at

  {{http://mycompany.com/}}, and complete your setup using a

  browser.

 === Completing the site setup using a browser ===

 Directly after the installation, the site is fully functional

 only when logged on; otherwise, all links (except for ''login'')

 should yield an error {{404 Not Found}}. That's because the site

 hasn't been ''unrolled to static pages'' yet.

 Follow these steps to finalize your installation:

  - 1. Enter the 'login' section and login to your site using the

  username and password you specified in {{etc/passwd.lua}}.

  - 2. Click 'Profile'. In the form 'Copy current profile to', enter

  the name of a new profile, e.g. {{20070311release}}.

  - 3. In the form 'Change to profile' pick the profile you just

  created.

  - 4. Click 'Publish profile'.

  - 5. Enter the 'login' section again, logout from the application

  and enjoy the unrolled site. All links should be working now.

 === Troubleshooting ===

  - 1. If {{make permissions}} gives you something like

    bash: test: content/current_de: binary operator expected

   Then there may be a stray blank after the {{LANGUAGE}} setting in

   the Makefile.

  - 2. When the website returns something like

    Application error

    ./tek/cgi/session.lua:39: Could not determine session ID

   Then you did not activate {{mod_unique}} in Apache.

  - 3. When you start editing the site and get errors like

    Application error

    ./loona.lua:747: Error opening section file for writing

  Then you did not adjust permissions properly. Simply correct the

  Makefile, run {{make permissions}} again, and reload.

 == Development model ==

 Since LOona is young and fresh and incomplete, you might want to

 contribute to its development.

 Using the Mercurial version control system, the development model is

 unintrusive; simply start off by creating a branch.

 Creating an 'incoming' repository:

   % mkdir loona

   % cd loona

   % hg clone http://hg.teklib.org/loona incoming

 Creating a 'development' branch:

   % hg clone incoming dev

 Once you consider your work to be worthy of inclusion to the main

 development branch, designate a place from where your branch can be

 pulled. (You will probably want to create another clone for your

 outgoing changes.)

 Finally, drop me a mail (see Contact section).

 == Contact ==

 LOona was written by Timm S. Müller. To contact the author, write an

 e-mail to '''tmueller at neoscientists.org'''.

 A development mailing-list is available, see

 http://lists.neoscientists.org/mailman/listinfo/loona-devel.

 If you are using LOona for your homepage or application, drop me a

 mail to get listed in the gallery.

 This project is hosted on http://www.neoscientists.org/.

 ---------------------------------------------------------------------

 References:

  - Lua scripting language:

  [[http://www.lua.org/]]

  - Mercurial version control system:

  [[http://www.selenic.com/mercurial/]]

  - Apache webserver:

  [[http://www.apache.org/]]

  - The Kepler project:

  [[http://www.keplerproject.org/]]

  - LOona homepage:

  [[http://loona.neoscientists.org/]]

  - Originally developed at:

  [[http://www.lsexperts.de/]]

  - Project hosted at:

  [[http://www.neoscientists.org/]]