The Flamenco Project

Flamenco Documentation

Software Prerequisites

Flamenco is a Web application. Once you have set up a Flamenco server, clients will be able to view your Flamenco collections using a Web browser on any platform.

You do not need an administrator account to install and run Flamenco, though you may need to ask an administrator to install other required software or provide you with database access.

Required Software

To run the Flamenco server, you will need a computer running Linux or Mac OS X with:

Flamenco also uses the MySQLdb module for Python, but if you don't already have it, the Flamenco installer will build and install it automatically for you, using a copy of MySQLdb that is included in the Flamenco distribution.

Alternatively, or if MySQLdb fails to build automatically, you can install it yourself. On Linux systems that use Debian packages, you can install the module with a single command: apt-get install python-mysqldb. For other Linux systems and for Mac OS X, download and unpack the latest release of MySQL-python, cd into the newly created directory, and give the command python install.

Database Access

You will need a MySQL account that either has permission to create new databases or has access to an existing database where Flamenco will store your collection. You need a separate database within your MySQL account for each instance (collection) you install. The MySQL server doesn't have to run on the same computer as Flamenco; you can use a MySQL database administered by someone else or on another machine, as long as you have a MySQL account there.

If you are running MySQL yourself, use MySQL version 3.23 or higher. MySQL is available for both Mac OS X and Linux from, and is also preinstalled on many Linux systems.

Optional Software

Lucene is optionally used to provide a full-text search feature (full-text search is still available via MySQL even without Lucene). If you want to use the Lucene search engine, you will also need:

Software Architecture

Flamenco is written in Python and uses the Webware application toolkit. The following diagram illustrates the Flamenco software architecture. The blocks labelled in a monospaced font are Python modules. The blocks in colour are part of Flamenco; the blocks in grey are not.

Flamenco, Floogle, FrankenMatrix, etc.   FlamencoStyle
components InterfaceBase Style
metadb Page logging Page
query lucene html store css
Lucene MySQLdb WebKit MySQLdb WebKit
Faceted Metadata User Interface UI Persistence Stylesheets

Metadata about items in the collection is stored in a SQL database. Flamenco uses MySQL, though any SQL database would be sufficient. MySQLdb is the Python interface module to MySQL. Flamenco also uses the Lucene search engine, written in Java, for its full-text search feature. If Java or Lucene is unavailable, full-text search is implemented using MySQL. The metadb module is the core of Flamenco's faceted metadata implementation, providing an abstraction layer on top of the SQL database and text search functionality.

The html module provides utility functions for generating HTML. The components module uses information from the database to build parts of Flamenco's user interface. These parts are combined and laid out into Web pages by the Flamenco module. Floogle and FrankenMatrix are other variations of the user interface that were tested and compared in our user studies.

The CSS for the user interface is dynamically generated by the FlamencoStyle module, which builds on css, a CSS rule generator, and Style, a special kind of Page for delivering CSS instead of HTML.

WebKit, which is part of Webware, serves the generated pages and stylesheets.


Flamenco Project

Software Packages

Continue to the next section: Preparing Your Data.