The Flamenco Project

Flamenco Documentation

Administering Flamenco

The Flamenco administration utility is a script called flamenco located in the target/bin directory, where target is the target directory in which you chose to install Flamenco. You may find it convenient to add this directory to your PATH variable so that you can run this utility just by typing flamenco. (Otherwise, you will need to type the complete path to the utility: target/bin/flamenco.)

If you use bash as your shell, adjust your PATH with the command:

export PATH=$PATH:target/bin
Put this command in your .bashrc file to make this PATH setting apply automatically every time you log in.

If you use csh or tcsh as your shell, adjust your PATH with the command:

setenv PATH ${PATH}:target/bin
Put this command in your .cshrc or .tcshrc file to make this PATH setting apply automatically every time you log in.

When you give the command flamenco by itself, you'll get a menu of administration actions.

Available actions are:
    status  - list all processes and instances
    start   - start an instance
    stop    - stop an instance
    restart - stop and then restart an instance
    kill    - kill all instances (last resort, run as root)
    import  - import a collection and create a new instance
    index   - enable text search using Lucene instead of MySQL

The action should be given as the first argument to flamenco. For example, type flamenco status to get a list of processes and instances.

Starting and Stopping Instances

The start, stop, and restart actions each take at least one additional argument, an instance name. You can specify more than one instance name or the special name ALL to mean all available instances.

Flamenco sets up each instance so that it starts automatically when it is first accessed by a Web browser. So, although you can use the flamenco start instance command to start an instance when it's convenient, you don't need to.

If an instance is started automatically due to a browser accessing it, the WebKit server process will run in the Web server user account (which is usually named www, www-data, apache, or nobody). If you start an instance using the flamenco start instance command, the WebKit server process will run in your user account.

Regardless of how an instance was started, the flamenco stop instance command stops the instance. If you are testing changes to your customization code or editing the Flamenco code itself, you may want to use the flamenco restart instance command, which stops and restarts an instance.

Flamenco Processes

When you're looking at a process listing, you can identify the WebKit server process for an instance by its command line, which will look like python flamenco-instance. The flamenco status command will list all Flamenco processes and all available instances and indicate which instances are running.

If something goes wrong and you cannot stop an instance normally, the flamenco kill command will forcibly terminate all Flamenco processes that you own. To terminate all Flamenco processes with certainty, run the flamenco kill command as the root user.

Managing Collections

The flamenco import directory command, as described in the installation section, imports a collection and creates a new instance.

The flamenco index instance command builds a Lucene index of the keywords in a collection for the full-text search feature in Flamenco. Instances are initially created without a Lucene index. If Java is available on your machine, you can create a Lucene index using this command, after which the full-text search will use the Lucene search engine.

Continue to the next section: Software Prerequisites and Architecture.