Apache renames environment variables with a REDIRECT_ prefix when redirecting or rewriting URLs, you need a SetEnvIf directive to copy it when executing the CGI binary:
Code:
<Directory /usr/lib/cgi-bin/omega>
SetEnvIf REDIRECT_OMEGA_CONFIG_FILE ^(.+)$ OMEGA_CONFIG_FILE=$1
</Directory>
Note that this has to done
after the redirections have been done; doing it in the actual cgi-bin directory should work well.
__________________
Here is a yet another example configuration, even further simplified, and slightly more adaptable (to your needs -- any paths you wish can be used with this one).
I've only tested this with a dummy CGI program on top of default Apache (with only
alias authz_host cgi dir env rewrite setenvif modules enabled), but it should work if you modify the query templates to match the URLs.
There is only one Apache configuration file,
/etc/apache2/conf.d/docoll, shared by all search engine versions:
Code:
DirectorySlash On
RewriteEngine On
Alias /docoll/results /srv/docoll
Alias /docoll /var/www/docoll
<Directory /srv/docoll>
AllowOverride None
Options FollowSymlinks
Order Allow,Deny
Allow From all
</Directory>
<Directory /var/www/docoll>
AllowOverride None
Options FollowSymlinks ExecCGI
Order Allow,Deny
Allow From all
<Files omega>
SetHandler cgi-script
SetEnvIf REDIRECT_OMEGA_CONFIG_FILE ^(.+)$ OMEGA_CONFIG_FILE=$1
</Files>
RewriteEngine On
RewriteBase /docoll
RewriteRule ^/*$ omega?DB=docoll&FMT=docoll [L,QSA,E=OMEGA_CONFIG_FILE:/etc/opt/docoll/search/omega.conf]
RewriteRule ^/*search$ omega?DB=docoll&FMT=docoll [L,QSA,E=OMEGA_CONFIG_FILE:/etc/opt/docoll/search/omega.conf]
RewriteRule ^/*search-([^/]+)$ omega?DB=docoll&FMT=docoll [L,QSA,E=OMEGA_CONFIG_FILE:/etc/opt/docoll/search-$1/omega.conf]
</Directory>
The
/var/www/docoll directory contains only a symlink
omega to
/usr/lib/cgi-bin/omega/omega . You can use any directory you wish instead of
/var/www/docoll, as long as you edit every occurrence of the directory name above.
Using a symlink for the
omega CGI binary, rather than aliasing the entire omega cgi-bin directory, has two important benefits in my opinion. First, your package then refers to only the files in the xapian-omega package it uses, rather than blindly publishing the entire xapian-omega interface. There may be additional xapian-omega -derived packages installed by your end users that reside in the same /usr/lib/cgi-bin/omega/ directory, and it is better to not enable those by default. Second, it is easier for debugging (by changing the symlink to a CGI binary that just dumps the environment variables), and porting to custom-compiled versions of xapian-omega. For example, an end user might wish to use a specific version of xapian-omega for docoll. Changing the one symlink will achieve that.
/etc/opt/docoll/search should be a symlink to the current search version subdirectory,
/etc/opt/docoll/search-0.2 . If you prefer to not have the symlink, just replace both occurrences of
/etc/opt/docoll/search/omega.conf above with the desired default configuration file path.
The default search page URL is
/docoll,
/docoll/, and
/docoll/search. If you drop the
DirectorySlash On directive, you do not need the
dir module, but the
/docoll URL will not work.
If you replace the first
RewriteRule with
DirectoryIndex index.html then
/docoll and
/docoll/ URLs will load page
/var/www/docoll/index.html instead of the search page. Note that it can contain a search form too. For example, you can use the HTML code from the actual search form (
wget -O - http://localhost/docoll/search) and use it as a starting point for the page.
To use any specific version of the search engine, you can use any
/docoll/search-version URL, where
version does not contain a slash. It will run the same (symlinked)
omega CGI binary, but with
OMEGA_CONFIG_FILE set to
/etc/opt/docoll/search-version/omega.conf . It does not verify that the configuration file actually exists. (However, you can catch those by changing
/etc/omega.conf to use a template page that just redirects back to the proper default search page.)
If you want to enable only specific versions, replace the last
RewriteRule with the ones that match the desired versions.
The search results are under URL
/docoll/results/, published from the
/srv/docoll tree. If you have file
/srv/docoll/foo then it is published as
/docoll/results/foo. You can use any tree you wish, simply by modifying every occurrence of
/srv/docoll in the above configuration to match.
__________________
Now that I'm a bit more familiar with xapian-omega, I would like to modify my suggestion for the installation tree. Assuming the base package name is
docoll, and it relies on the xapian-omega package, I would use
- /var/www/docoll/ for the omega CGI binary symlink and the search index page (index.html).
I would use the index page modification to above config.
Static media such as images and stylesheets and so on I would put in one or more subdirectories there. If themed, I'd put the media for each theme under their own subdirectory here.
- /etc/docoll/ for the configuration files, including templates.
- /var/lib/docoll/files/ for the collected files (instead of /srv/docoll)
- /var/lib/docoll/index/ (or perhaps omindex or something) for the indexing of the collected files
It is usually best to replace a complex search index by replacing the entire directory. Having the index in a single subdirectory makes it easier.
- /usr/share/docoll/ for the search engine scripts
- /var/log/docoll for search engine log files
Note that this does not include any Apache log files; Apache takes care of its own logging.
I think I might also just split the
docoll package into semi-independent ones:
- docoll-base would provide the base tree structure, the omega CGI binary symlink, documentation files, and so on.
- docoll-search would provide the search engine. It would allow multiple parallel installations, so it would use versioned directory names. The contents it would provide would include /etc/docoll/search-version (default configuration files) and /usr/share/docoll/search-version (search engine scripts).
The post-installation hook would create symlinks /etc/docoll/search and /usr/share/docoll/search pointing to the subdirectory owned by the latest stable installed version, and /etc/docoll/search-version/style pointing to ../style-default. The search engine configuration would use /etc/docoll/search-version/style as the template directory path.
- docoll-style-default would contain the default templates, under /etc/docoll/style-default/. Other templates (style packages) can be installed in parallel, with the symlink determining the variant.
The base package installs /var/www/docoll/default.html, /var/www/docoll/index.html being a symlink to it. Then any style package can provide another search engine front page (style.html), and the user can pick the preferred one by changing the symlink. Any images, stylesheets and media the templates use would go under /var/www/docoll/style/ for example.
The dependency tracking is a bit complicated (the base package requires
apache2-common,
xapian-omega, any one
docoll-search package version, and at least one
docoll-style package).
The above would assume the objective is to eventually get
docoll included in upstream Debian (or variant like Ubuntu) or Red Hat (or Red Hat variants like CentOS or Scientific Linux) distributions. As I see it, the same config is typical for other similar packages in all these distributions, and is FHS compliant. If you are unsure, you can always contact the Debian developers on the
debian-devel mailing list, and ask if Debian Maintainers consider the scheme acceptable, or have better suggestions.
A point I missed earlier is well stated in the
Debian New Maintainers' Guide, installation chapter:
Quote:
|
Originally Posted by Debian New Maintainers' Guide
On Debian [/usr/local] is reserved for private use by the system administrator, so packages must not use directories such as /usr/local/bin but should instead use system directories such as /usr/bin, obeying the Filesystem Hierarchy Standard (FHS).
|
This does mean that all Debian packages should use the system directories, as opposed to say /usr/local or /opt. The key point is
system directories .. obeying FHS. Debian package guidelines therefore do not adopt FHS as-is, but point to a specific
part of FHS.
As to the search scripts,
/usr/bin is really intended for general-use scripts, those that users are expected to be able to run directly. Scripts and extensions that are part of a specific package belong under
/usr/share/package , at least for architecture-independent files (like shell, Perl, and Python scripts). In your case, users should not be able to run most of the scripts
docoll provides -- only some specific commands like database refresh et cetera --, so most of your scripts clearly belong under
/usr/share/docoll.
__________________
Still, there is no single solution or convention that is "correct" or even "the best" for
docoll. There are numerous choices acceptable to FHS, Debian, and users in general. You do have a lot of freedom here -- and really, very few solid rules. My "objections" to using opt are quite weak, more to the tune of "but it would be easier or more familiar for me as an end user if you do this instead" rather than actual objections.
My own approach to development is modular and adaptive rather than framework-based. This seems to be evident in the way I value guidelines and established practices higher than e.g. FHS, but will break either given even a halfway decent reason. As you can see in this thread alone, my "solutions" tend to evolve, sometimes through ridiculous, weird, unwieldy, or even stupid options, slowly converging to something I can be happy with. Testing and experimentation is very important. Everything I have written or stated here is my own opinion, and is based on limited experience with xapian-omega, and none with your docoll variant/configuration. With increased experience with it, my suggestions would likely evolve. Radical changes are quite possible. Based on your willingness to entertain other notions, the amount of background research you have done for this, and in general the amount of thought and effort you put into this, I'm absolutely convinced you will make the most suitable choices regarding docoll, even if they were totally different from anything I have suggested here.
One thing you might consider is to add a short chapter in the documentation, describing the reasons behind the choices you've made. In the future, you may wish to revisit your choices -- it is not terribly rare for a package to radically change its configuration scheme; as long as there is a good reason for that, users tend to not complain too much --, and having the background information is very useful then.
