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