README_FOR_APP

Path: doc/README_FOR_APP
Last Update: Sat Aug 21 22:34:50 +0100 2010

LogiLogi Manta documentation and installation instructions

LogiLogi Manta is an hypertext web-platform developed for LogiLogi.org by the LogiLogi Foundation. It tries to combine the virtues of good conversations and the written word by providing a form of quick, informal publication and annotation of short texts (so called Logis) via the web.

Its central values are openness and quality of content. Contrarily to early websystems it does not make use of forum-threads (avoiding their many problems), but of tags and links that can also be added to logis by others than the original author.

LogiLogi wants to meet the need of philosophers, students, and others for in-depth, quick-turnaround, high quality discussions without taking the fun out of it by making things too complicated.

LogiLogi Manta is Free/Open Source Software (Affero GPLed).

This Documentation

To explore the API documentation you can best start by looking at Logi and Link.

This documentation is updated automatically as we improve and extend the code.

Related documentation of the gems we created can be browsed here: Diff LCS, Position Range and Text Weaver, and of the Rails plugins here: Thorny Form, Magick Corners and Body Builder.

A video of a presentation on LogiLogi can be seen here: video.google.nl/videoplay?docid=865414300290684342

Papers and presentations on LogiLogi plus their source can be checked out here:

  svn co https://logilogi.svn.sourceforge.net/svnroot/logilogi/docs

They will also be noted and available on the Foundation Blog.

LogiLogi Community

If you need help, want to get involved with the project, or want to discuss it, you are welcome to join our low volume mailing-list.

And of course you can also create an account on LogiLogi.org and start using it.

Installation

You can install LogiLogi in 3 steps. For the first step you can choose between two ways of downloading it: a developer-snapshot (A) and the slightly more complicated manual installlation (B).

Step 1: Getting it

For both the the developer snapshot and the manual install, the first few things are the same:

LogiLogi requires ruby, and a few other things. So you first need to install the stable ruby version, mysql, libopenssl for ruby, and the xapian search-library.

(If you are using Ubuntu or Debian as your OS see the notes at the bottom for which packages you need).

For the manual install, subversion is used for getting the code, and for the snapshot install, it is used to keep the code up-to- date. So it‘s best if you install subversion if you don‘t have it yet.

Then you need to install Ruby Gems. You can install it by downloading it from here:

  http://rubyforge.org/frs/?group_id=126 (the newest)
  then untar with tar -xzvf rubygems*.tgz
  and install it with cd rubygems*; ruby setup.rb (as root)

Way A: Developer snapshot

Next you download the newest developer snapshot from SourceForge:

  https://sourceforge.net/projects/logilogi/files/ (the newest)
  then untar with tar -xzvf logilogi*.tgz
  and optionally 'svn update' from trunk (to update it to the
  latest development version)

It contains LogiLogi, Ruby on Rails and all gems that LogiLogi needs, except rack.

This last gem could not be included because Rails will not allow one to to (a bug). You can install it in the following way:

  gem install rack (with the '-v 1.0.1' option currently)

All done. Skip to step 2.

As a side-note, note that it does not include RMagick, which is used to generate new images for the user interface. This is not a problem, unless you want to change things in the UI (and you can always do the manual installation later). Neither does it include Ratom (for Atom), so the XML API does not work in your local install (but not used during development anyway).

Way B: Manual install

You can get Manta directly from our Subversion repository

  svn co https://logilogi.svn.sourceforge.net/svnroot/logilogi/trunk

LogiLogi Manta requires Rails.

You can install Rails with ruby gems (gem1.8, or gem<version number> on some OSses):

  gem install rails
  (as root, if gem command is not found you might have to type gem1.8
  instead)

And it requires the rack, daemons, rubyzip, ruby-openid, binarylogic-authlogic, authlogic-oid, quantipay-authlogic_haapi, ratom, json, mislav-will_paginate, positionrange, difflcs, textweaver, mysql, rmagick (version > 2.2.2, *with svg*, this one is optional but important for the UI), ya2yaml, mysql, gems (version >= 1.0).

First you need to add github as a source for gems:

  gem sources -a http://gems.github.com

Then You can install them with:

  gem install rack daemons rubyzip ruby-openid binarylogic-authlogic \
    authlogic-oid quantipay-authlogic_haapi ratom json \
    mislav-will_paginate positionrange difflcs textweaver mysql \
    rmagick ya2yaml
  (as root, same here as with Rails installation)

Also see the Installation Notes at the bottom for how to meet the few dependencies of the gems.

Step 2: Configuring it

Go to the config dir and copy the template (not needed with snapshot install, because already there)

  cp config.rb.tmpl config.rb

…and change settings as you see fit (usually no changes are needed, and for development no changes are recommended. Note that after initializing the database some settings cannot be changed anymore).

Copy the template

  cp database.yml.tmpl database.yml

…and add your database-username and -password. Making changes is only needed if you did set a root-password for your database.

Then with rake dev:check you can test if you installed everything correctly.

LogiLogi does not work before it‘s database and search-index is initialized. Thus to initialize the development-database with the configuration, an intro-page and to set up the xapian search-index (stored in the db/search_index directory), you should run:

  rake db:initialize

(For the production environment you need to run rake db:initialize RAILS_ENV=production)

To (re-)initialize the test- and development-database with the config and fixture data for development and manual testing you should run (handiest for development):

  rake db:dev:redo

(not to be used for the production environment)

Now you can run the unit-tests…

To get going with the GUI you should add something like the following to your /etc/hosts:

  0.0.0.0 logi-manta.org en.logi-manta.org de.logi-manta.org

Then start the included WEBRick server with script/server from the trunk directory.

Step 3: Enjoying it

Then you can point your browser to en.logi-manta.org:3000/

You‘re all set.

If you want to do development always run rake dev:update before you start. This pulls in changes from svn and updates your config and db (overwrites them).

Building the documentation/presentations

To build the documentation and/or the presentations you need latex (texlive & latex-beamer), tex2pdf (tex2pdf.berlios.de/) and b-rex (included in the doc‘s svn, in the b-rex dir, but also available on: en.logilogi.org/Logi_Logi/Tools/Beamer_Rex)

Then where you checked out the docs you can build the presentation- file beamer.tex:

  cd b-rex; ./b-rex ../presentation/ECAP08/beamer.tex

While the handout.tex builds the handouts for most presentations.

Installation FAQ

Answers to Frequently Asked Questions.

How to install on Ubuntu ?

If you are on Ubuntu you need to install the following packages to get a standard Ruby installation:

  sudo apt-get install ruby ruby1.8-dev libzlib-ruby rdoc irb rake

And to get MySQL, Subversion, libopenssl, Xapian and libxml2

  sudo apt-get install make mysql-server mysql-client \
      libmysqlclient15-dev libmysql-ruby subversion \
      libopenssl-ruby1.8 libxapian15 libxapian-ruby1.8 \
      libxml2

If you do the manual install, and want to use ImageMagick, you get it and libxml2:

  sudo apt-get install imagemagick librsvg2-dev \
      libmagickwand-dev

RMagick will build extensions from source. If you have to install ImageMagick from source (because it is out of date compared to RMagick), then see the ImageMagick problems section.

How to install on Xandros

(incomplete)

On Xandros you need libruby1.8 and rdoc & ruby1.8-dev.

How to fix problems with RMagick ?

If you get an error saying that RMagick cannot open a file in /tmp, and find this: "wmf2eps: not found" in your logs, it likely is because the svg extension is not working. You will need librsvg2-dev and then re-install Rmagick (see below).

If you see strange blue lines around tags or other background-images, then you probably are using an old version of imagemagick. In that case you should download imagemagick, and build it from source with:

  ./configure --disable-openmp; make; sudo make install;

And then re-install the rmagick gem with:

  sudo gem install rmagick

I get a ‘Xapian Database not opened’ error

Most likely the search-index is not initialized. If you don‘t mind losing your data, and want a fresh start, then the folliwing will work:

rake db:initialize (possibly followed by RAILS_ENV=production)

If you do mind your data, then you can rebuild the index with:

rake index:create (possibly followed by RAILS_ENV=production)

This Documentation

This documentation can be browsed online at:

Copyrights

LogiLogi Manta and these docs are Copyright (c) 2006-2009 The LogiLogi Foundation. LogiLogi is licensed under the Affero General Public License. These docs are available under the Creative Commons Attribution-Share Alike License.

While our plugins and gems are, LogiLogi Manta is not available under any other license than the Affero GPL.

[Validate]