Flamenco Documentation
Software Prerequisites
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:
- A Web server that runs CGI scripts (Apache works well, and is preinstalled with Mac OS X and most Linux systems).
- Python 2.3 or higher (already present on almost all Linux and Mac OS X systems).
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 setup.py 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 mysql.com, 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:
- Java (JRE) 1.2 or higher.
- Access to your MySQL server on TCP port 3306 (some machines have this turned off by default).
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 | |||||||
| Java | MySQL | MySQL | |||||||||
| 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.