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