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. (Also note that an installation of Kepler is not required.)

  • 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://hg.teklib.org/loona mycompany.com
% cd mycompany.com
    Alternatively, download and unpack the archive from the download section and rename it accordingly.
  • 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 filename, 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'.
  • 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.

Next: Markup