Flamenco Documentation

File Layout and Permissions

This section describes the files that are installed into the Flamenco target directory.

Flamenco Directory

Six directories are installed into the Flamenco target directory:

bin contains executable programs (the flamenco utility and its helper scripts, as well as the flamenco.cgi CGI script).
instances contains the instance directories. There is one subdirectory under target/instances for each instance, and the subdirectory name is the instance name.
java contains the Java code for Flamenco (just a couple of classes for interfacing with Lucene).
python contains the Python code for Flamenco (the bulk of the implementation).
software contains archive files of supporting software packages for Flamenco: the MySQLdb Python module, the Webware distribution, and JAR files for Lucene and the database access that Lucene uses.
webware contains the unpacked and configured Webware distribution.

With the exception of instances, all of these directories are readable and executable by all users and writable only by you (the user who performed the installation). The instances directory is writable by all users so that anyone can create a new instance, but also sticky so that other users cannot delete your instances.

Instance Directory

Each instance resides in a subdirectory of target/instances. Each instance directory contains the following files and directories, which are writable by all users so that any user (including the Web server user account) can run the WebKit server for the instance:

Cache, ErrorMsgs, Logs, and Sessions are directories where WebKit writes information as it runs.
address.text is created by WebKit while it is running, and it records the host address and port number of the WebKit server.
appserverpid.txt is created by WebKit while it is running, and it records the process ID number of the WebKit server. Removing this file or overwriting it with a zero-length file will cause the WebKit server to shut down. (This means that any user with an account on the machine can shut down the instance.)
log.txt is the log file written by the WebKit server. Examine this file for error messages if something goes wrong.

The instance directory also contains the following files and directories, which are writable only by the user who created the instance, not writable by all users.

Configs is a directory of configuration files for WebKit. There shouldn't ever be a need to edit these.
Collection.py provides instance-specific customizations to the Flamenco interface.
flamenco-example is the script that starts the WebKit server. Its name contains the instance name to make it easier to identify in a process list.
instance.py stores the configuration settings for the WebKit server. The variables DBHOST, DBUSER, DBPASS, and DBNAME give the parameters for the MySQL database connection. The variables MINPORT and MAXPORT give the port range for the WebKit server. You can edit this file if you need to change these settings.

Restricted Execution

Flamenco is normally set up so that anyone can start instances just by accessing any URL that would be generated by the instance. (Any URL that begins with the URL to the CGI script, followed by a slash, the name of the instance, and another slash, accesses a page generated by the instance.) Also, any user on the system where Flamenco resides can shut down a Flamenco instance by emptying the appserverpid.txt file.

If you do not want other users to be able to start or shut down a particular instance, turn off world-write permission for appserverpid.txt and turn off world-execute permission for flamenco-instance:

chmod go-w appserverpid.txt
chmod go-x flamenco-instance

These changes to the permissions will also prevent the CGI script from automatically starting up the instance whenever someone tries to access the instance; you will have to use flamenco start instance to start the instance.