== 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. Its main purpose is to allow your boss

to play with his/her website without being able to break things,

while for you it's easy enough to maintain and to add new features as

you see fit. (Besides, it can be fun to create webpages without

writing HTML.)

LOona is small and fast and extensible and written with security,

robustness and a small resource footprint in mind. It requires no

database, as webpages are dynamically generated from plain text

files, hence website content can be edited using a browser and a text

editor in a similar way. LOona uses its own WIKI-like markup

notation, but unlike a WIKI, LOona's site structure is hierarchical.

LOona is a simple and effective tool for producing homepages for

small projects and businesses.

== 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)

 * Most website content is automatically rolled out to static HTML

 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 and news boxes

  * Prompts to accept a disclaimer before continuing

  * News, guestbooks, database-driven content, etc.

  * ... while fully retaining the WIKI

  ''you-can't-break-it-by-editing'' paradigm.

=== Planned features ===

 * Support for a version control system

 * Upload and management of objects (such as images and downloadable

 documents)

 * Publicly editable sections

 * Switching site languages when editing

 * Edit-/delete protection for individual text nodes

== 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.1.tar.gz

   % tar -xzf lua-5.1.1.tar.gz

   % cd lua-5.1.1

   % 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.

 * You need the Mercurial version control system to obtain a copy of

 LOona's 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.

 - 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://loona.neoscientists.org:8000 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 filenames, 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' and confirm.

 - 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

simple and unintrusive. Simply start off by creating a branch.

Creating an 'incoming' repository:

  % mkdir loona

  % cd loona

  % hg clone http://loona.neoscientists.org:8000 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 ==

To contact the author, write an electronic mail to

'''loona at 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/]]

 - Project hosted at:

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