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
.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
.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.