README
author Timm S. Mueller <tmueller@neoscientists.org>
Fri, 24 Oct 2008 01:35:27 +0200
changeset 251 2de5931b723d
parent 235 452ce747b7b1
child 256 8cd1538fbd18
permissions -rw-r--r--
tek.os.posix has been moved to tek.lib.posix, module initialization procedure
simplified, added statvfs() under Linux
     1 
     2 == LOona ==
     3 
     4 === Tiny CMS and Homepage Maker ===
     5 
     6 - Copyright © 2007, Timm S. Müller
     7 - Copyright © 2003-2006 The Kepler Project
     8 - LOona is released under the terms of the free MIT software license,
     9 see also COPYRIGHT
    10 
    11 
    12 === About ===
    13 
    14 LOona is halfway between a WIKI and a Content Management System (CMS)
    15 for managing website content. It is small, fast and extensible and
    16 written with security, robustness and a small resource footprint in
    17 mind. It requires no database, as pages are dynamically generated
    18 from plain text. In this way, website content can be created using a
    19 browser and a text editor in a similar fashion. LOona uses its own
    20 WIKI-like markup notation, but unlike a WIKI, its site structure is
    21 hierarchical.
    22 
    23 When running out of the box, LOona is a tool for producing simple
    24 sites for small projects and businesses. Using its extension
    25 facility, it can be employed for applications of all kinds. For
    26 example, LOona has recently been tailored to a telephony system under
    27 resource-constrained conditions.
    28 
    29 LOona was originally created during an employment at the LSE Leading
    30 Security Experts GmbH, and thanks to LSE's friendly support, it has
    31 been continued as an Open Source effort.
    32 
    33 
    34 === Selected features ===
    35 
    36  * Any number of text bodies, news boxes, etc.
    37  * Several users can modify a site at the same time
    38  * Different versions of a site can be edited without disturbing the
    39  published content
    40  * Sites can be multilingual and automatically detect the
    41  browser-preferred language
    42  * Full Unicode support, localized interfaces (English and German
    43  locales are included)
    44  * Non-varying website content is automatically rolled out to static
    45  pages and served right off the filesystem
    46  * Can restrict site modifications to HTTPS connections
    47  * Supports an extension mechanism for easy embedding of
    48  site-specific features, such as site search, contact forms,
    49  splash screens, prompts to accept a disclaimer, news, guestbooks and
    50  database-driven content
    51 
    52 
    53 == Prerequisites ==
    54 
    55 LOona has been developed and tested under Linux using the Apache 2.0
    56 webserver. Ports to different environments should be possible and
    57 straightforward, but this documentation will not try to go into
    58 detail about the peculiarities.
    59 
    60  * Make sure that your filesystem supports access times.
    61  LOona depends on this feature for session expiration.
    62 
    63  * Enable {{mod_unique}} in Apache.
    64  LOona obtains session IDs using this module.
    65 
    66  * Install the Lua 5.1 interpreter.
    67  The default build/install procedure on Linux looks like this:
    68 
    69    % wget http://lua.org/ftp/lua-5.1.2.tar.gz
    70    % tar -xzf lua-5.1.2.tar.gz
    71    % cd lua-5.1.2
    72    % make linux
    73    % sudo make install
    74 
    75 '''NOTE''': If you choose to install Lua somewhere else than in
    76 {{/usr/local/}}, you will have to adjust the shebang in
    77 {{cgi-bin/loona.cgi}} accordingly.
    78 
    79  * Optionally, get the Mercurial version control system to obtain a
    80  clone of LOona's source code repository. See references below.
    81 
    82 
    83 == Installation ==
    84 
    85 Aside from the Lua interpreter, LOona is largely self-contained and
    86 requires no system-wide installation.  The idea is that everything
    87 runs straight out of the directory in which LOona resides, therefore
    88 it is recommended to keep its structure intact. (Also note that an
    89 installation of Kepler is not required.)
    90 
    91  - 1. Clone the LOona repository to a location in your filesystem
    92  that you designate for serving website content. I suggest to create
    93  a local copy for each name-based virtual host, and to name it
    94  accordingly:
    95 
    96    % cd /www/loona
    97    % hg clone http://hg.teklib.org/loona mycompany.com
    98    % cd mycompany.com
    99 
   100  - 2. Adjust {{LANGUAGE}}, {{WWWUSER}} and {{GROUP}} in the top-level
   101  Makefile, or override these settings in the commandline to
   102  complement your setup. Use {{make help}} to verify your
   103  configuration, e.g.:
   104 
   105    % LANGUAGE=de GROUP=admin make help
   106 
   107   '''NOTE''': {{LANGUAGE}} is the default/fallback language for which
   108   the initial site structure will be generated. {{WWWUSER}} is the
   109   user under which the webserver is running (usually {{apache}} or
   110   {{wwwrun}}). For {{GROUP}} choose the group of site administrators,
   111   or your own group.
   112 
   113  - 3. Configure the site
   114 
   115   Enter the {{etc/}} directory and create a password file named
   116   {{passwd.lua}} using {{passwd.lua.sample}} as a template.
   117 
   118   Optionally, create a configuration file named {{config.lua}} (using
   119   {{config.lua.sample}} as a template), but this is not strictly
   120   required as long as you are happy with the default configuration.
   121 
   122   '''NOTE'''': If you plan on setting up a site with another
   123   default/fallback language than English, you need a configuration
   124   file with the {{deflang}} item set to this language.
   125 
   126  - 4. Back in the main directory, build modules:
   127 
   128    % make modules
   129 
   130  - 5. Setup an initial site structure:
   131 
   132    % make setup
   133 
   134  - 6. Adjust the permissions:
   135 
   136    % sudo make permissions
   137 
   138  - 7. Point your webserver's document root to the {{htdocs/}}
   139  directory and the script path to {{cgi-bin/}}. Add a script handler
   140  for the extension {{.lua}}, as follows:
   141 
   142    <VirtualHost *:80>
   143      ServerName mycompany.com
   144      DocumentRoot "/www/loona/mycompany.com/htdocs"
   145      ScriptAlias /cgi-bin/ "/www/loona/mycompany.com/cgi-bin/"
   146      <Directory "/www/loona/mycompany.com/htdocs">
   147        Options +MultiViews
   148        AddHandler lua-script .lua
   149        Action lua-script /cgi-bin/loona.cgi
   150        DirectoryIndex index.html index.lua
   151      </Directory>
   152    </VirtualHost>
   153 
   154  The {{MultiViews}} option is only needed for multilingual sites. If
   155  a profile exists for more than one language, LOona renders static
   156  HTML pages with a language suffix added to their filename, like so:
   157 
   158    index.html.en
   159    index.html.fr
   160    index.html.jp
   161 
   162  - 8. You should now be able to login to an empty LOona site at
   163  {{http://mycompany.com/}}, and complete your setup using a
   164  browser.
   165 
   166 
   167 === Completing the site setup using a browser ===
   168 
   169 Directly after the installation, the site is fully functional
   170 only when logged on; otherwise, all links (except for ''login'')
   171 should yield an error {{404 Not Found}}. That's because the site
   172 hasn't been ''unrolled to static pages'' yet.
   173 
   174 Follow these steps to finalize your installation:
   175 
   176  - 1. Enter the 'login' section and login to your site using the
   177  username and password you specified in {{etc/passwd.lua}}.
   178 
   179  - 2. Click 'Profile'. In the form 'Copy current profile to', enter
   180  the name of a new profile, e.g. {{20070311release}}.
   181 
   182  - 3. In the form 'Change to profile' pick the profile you just
   183  created.
   184 
   185  - 4. Click 'Publish profile'.
   186 
   187  - 5. Enter the 'login' section again, logout from the application
   188  and enjoy the unrolled site. All links should be working now.
   189 
   190 
   191 === Troubleshooting ===
   192 
   193  - 1. If {{make permissions}} gives you something like
   194 
   195    bash: test: content/current_de: binary operator expected
   196 
   197   Then there may be a stray blank after the {{LANGUAGE}} setting in
   198   the Makefile.
   199 
   200  - 2. When the website returns something like
   201 
   202    Application error
   203    ./tek/cgi/session.lua:39: Could not determine session ID
   204 
   205   Then you did not activate {{mod_unique}} in Apache.
   206 
   207  - 3. When you start editing the site and get errors like
   208 
   209    Application error
   210    ./loona.lua:747: Error opening section file for writing
   211 
   212  Then you did not adjust permissions properly. Simply correct the
   213  Makefile, run {{make permissions}} again, and reload.
   214 
   215 
   216 == Development model ==
   217 
   218 Since LOona is young and fresh and incomplete, you might want to
   219 contribute to its development.
   220 
   221 Using the Mercurial version control system, the development model is
   222 unintrusive; simply start off by creating a branch.
   223 
   224 Creating an 'incoming' repository:
   225 
   226   % mkdir loona
   227   % cd loona
   228   % hg clone http://hg.teklib.org/loona incoming
   229 
   230 Creating a 'development' branch:
   231 
   232   % hg clone incoming dev
   233 
   234 Once you consider your work to be worthy of inclusion to the main
   235 development branch, designate a place from where your branch can be
   236 pulled. (You will probably want to create another clone for your
   237 outgoing changes.)
   238 
   239 Finally, drop me a mail (see Contact section).
   240 
   241 
   242 == Contact ==
   243 
   244 LOona was written by Timm S. Müller. To contact the author, write an
   245 e-mail to '''tmueller at neoscientists.org'''.
   246 
   247 A development mailing-list is available, see
   248 http://lists.neoscientists.org/mailman/listinfo/loona-devel.
   249 
   250 If you are using LOona for your homepage or application, drop me a
   251 mail to get listed in the gallery.
   252 
   253 This project is hosted on http://www.neoscientists.org/.
   254 
   255 
   256 ---------------------------------------------------------------------
   257 
   258 References:
   259 
   260  - Lua scripting language:
   261  [[http://www.lua.org/]]
   262  - Mercurial version control system:
   263  [[http://www.selenic.com/mercurial/]]
   264  - Apache webserver:
   265  [[http://www.apache.org/]]
   266  - The Kepler project:
   267  [[http://www.keplerproject.org/]]
   268  - LOona homepage:
   269  [[http://loona.neoscientists.org/]]
   270  - Originally developed at:
   271  [[http://www.lsexperts.de/]]
   272  - Project hosted at:
   273  [[http://www.neoscientists.org/]]