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