Apache configuration and URLs in ACIS / ACIS documentation

# Apache configuration and URLs in ACIS

### Table of contents

## Introduction

ACIS is a pretty complicated application. It both gives a web interface to users and it produces web-accessible objects. For all this to work, it needs to know how to reference itself and where to create other objects and how to reference them.

If you are making a real-world public ACIS-based service, you’ll want ACIS to be available via a short URL and you’ll want it to produce short and nice URLs. Then you’ll need to adapt Apache configuration. Particular adaptation depends on your choices for the ACIS configuration parameters. In most simple case you don’t need to do that, but then your URLs will be a bit messy.

Exact reasons to touch Apache configuration:

1. You may want ACIS to sit at the root address of a website. E.g. `http://web.site.org/` versus `http://web.site.org/cgi-bin/acis.pl` . See configuration parameter base-url.

2. You may want ACIS to generate short and clean URLs for the users’ profile pages. Short and clean would be something like `http://web.site.org/pro/pcl2/`, long and dirty would be like `http://web.site.org/pro/p/c/l/2/` or even worse. See configuration options compact-redirected-profile-urls and profile-pages-dir.

3. You may want to have the same URL value as your static-base-url and your base-url. Which means simply shorter and nicier URLs.

## What to do

Here are the instructions for Apache 1.3+. If you want ACIS to work with Apache 2, there is a little difference.

OK, let’s say you have `web.site.org` website and want to run ACIS on it and you have default settings for most parameters.

A normal CGI script has address of something like, `…/cgi-bin/script.pl`, but you want your users to access ACIS through the shortest, niciest `http://web.site.org/` address. Then we have to do the following.

First, we enable mod_rewrite in our <VirtualHost> section:

      RewriteEngine on

Second, we rewrite all incomming requests so that Apache transfers them all to ACIS. Let’s assume the actual ACIS CGI script is at `http://web.site.org/cgi-bin/acis.pl` address. Add this:

      RewriteRule ^(/.*)$ /cgi-bin/acis.pl$1 [L,T=application/x-httpd-cgi]

Let us call this line “the terminal rule line”; although it is the first rule we introduce, it actually always must be the last one of all rewrite rules used. This rule means: pass all requests for the website to ACIS.

But ACIS includes and produces some static files, which also have to be web-accessible. Personal profile pages — most important of all. We need to configure Apache to serve those requests by itself, without involving ACIS. One of the ways to do that is to add

      RewriteRule ^/static/ - [L]

before the previous RewriteRule. So together that may look like this:

      RewriteEngine on
      # static files:
      RewriteRule ^/static/ - [L]
      # terminal rule:
      RewriteRule ^(/.*)$ /cgi-bin/acis.pl$1 [L,T=application/x-httpd-cgi]

Then Apache will pass to `/cgi-bin/acis.pl` all requests, but those starting with `/static/`. So you can set static-base-url to `http://web.site.org/static` and static-base-dir to a corresponding directory name.

The personal profile URLs will then have form of `http://web.site.org/static/profile/p/s/i/d/1/`, which is not very nice, but if its OK for you, let it be so. In case you don’t like that, read on.

### Making personal profile URLs shorter

First thing we could do is remove `static/` part. For that we replace the respective RewriteRule with several others.

      RewriteEngine on

      # static files:
      RewriteRule ^/style/   - [L]
      RewriteRule ^/script/  - [L]
      RewriteRule ^/profile/ - [L]

      # terminal rule:
      RewriteRule ^(/.*)$ /cgi-bin/acis.pl$1 [L,T=application/x-httpd-cgi]

This will make requests for stylesheets, javascript files and for profile pages served directly by Apache, and everything else will be taken by ACIS. Now we can set static-base-url to `http://web.site.org` and static-base-dir to its apporpriate docroot, e.g. `/home/user/public_html`.

Second thing we could do to make personal profile URLs human friendly is eliminate the slash characters in `p/s/i/d/1` part. Here comes the next set of rewrite rules:

      RewriteRule ^/profile/p([a-z][a-z0-9]+[0-9])(/(.*))?$ /P/$1/$3
      RewriteRule ^/P/(.)(.)(.)(.)(.)/(.*) /profile/p/$1/$2/$3/$4/$5/$6 [L]
      RewriteRule ^/P/(.)(.)(.)(.)/(.*)    /profile/p/$1/$2/$3/$4/$5    [L]
      RewriteRule ^/P/(.)(.)(.)/(.*)       /profile/p/$1/$2/$3/$4       [L]

If placed before our static files rules in Apache conf, it will make requests like `/profile/psid1/` map to actual files as if it was a request for `/profile/p/s/i/d/1/`. Now to let ACIS know we did that, we set compact-redirected-profile-urls to a true value.

Now we have a reasonably good setup: the URLs are clean of cruft. To summarize we have the foolowing in our Apache conf <VirtualHost> section:

      RewriteEngine on

      # compact-redirected unique part of personal profile URLs
      RewriteRule ^/profile/p([a-z][a-z0-9]+[0-9])(/(.*))?$ /P/$1/$3
      RewriteRule ^/P/(.)(.)(.)(.)(.)/(.*) /profile/p/$1/$2/$3/$4/$5/$6 [L]
      RewriteRule ^/P/(.)(.)(.)(.)/(.*)    /profile/p/$1/$2/$3/$4/$5    [L]
      RewriteRule ^/P/(.)(.)(.)/(.*)       /profile/p/$1/$2/$3/$4       [L]

      # static files:
      RewriteRule ^/style/   - [L]
      RewriteRule ^/script/  - [L]
      RewriteRule ^/profile/ - [L]

      # terminal rule:
      RewriteRule ^(/.*)$ /cgi-bin/acis.pl$1 [L,T=application/x-httpd-cgi]

And we have something like the following in our main.conf:

      base-url        = http://web.site.org
      base-cgi-script-filename = /var/apache/htdoc/user-cgi-bin/acis.pl
      home-url        = http://web.site.org/
      static-base-url = http://web.site.org
      static-base-dir = /home/user/public_html

      +compact-redirected-profile-urls

### A note on suEXEC

For security and common-sense considerations it makes a lot of sense to run ACIS CGI under suexec in Apache. This way you avoid a lot of permissions trouble.

One of the things you need to use suexec is your CGI scripts must reside somewhere below global DocumentRoot directory. That’s why in main.conf snippet above the base-cgi-script-filename param points to a file in `/var/apache/htdoc/user-cgi-bin/` (assuming that the global DocumentRoot is `/var/apache/htdoc`). To make this directory correspond to your virtual host’s `/cgi-bin/` you use the following in apache conf <VirtualHost> section:

       ScriptAlias /cgi-bin/ /var/apache/htdoc/user-cgi-bin/

### Even shorter profile URLs

With all the above you have a very reasonable setup. But there is one more little thing to know about making URLs short and clean.

We could do to make personal profile URLs even shorter by replacing `"/profile/"` part with something like `"/pro/"`. For that, we use profile-pages-dir parameter. We set it to `"pro/"` and we rewrite the Apache conf to read:

      ...
      # compact-redirected unique part of personal profile URLs
      RewriteRule ^/pro/p([a-z][a-z0-9]+[0-9])(/(.*))?$ /P/$1/$3
      RewriteRule ^/P/(.)(.)(.)(.)(.)/(.*) /pro/p/$1/$2/$3/$4/$5/$6 [L]
      RewriteRule ^/P/(.)(.)(.)(.)/(.*)    /pro/p/$1/$2/$3/$4/$5    [L]
      RewriteRule ^/P/(.)(.)(.)/(.*)       /pro/p/$1/$2/$3/$4       [L]

      # static files:
      RewriteRule ^/style/   - [L]
      RewriteRule ^/script/  - [L]
      RewriteRule ^/pro/ - [L]
      ...

Which is a straight `"profile/"` -> `"pro/"` replacement. Off you go.

### Changing configuration of a running sytem

An important thing to know about personal profile URLs is that once system generates and assigns a profile URL, is stores it in the user’s profile and uses it since. If you change your setup, the previously-assigned profile URLs will still have the old format and ACIS will not rebuild them. The only case when ACIS rebuilds a profile URL is when it finds that it can’t write the profile page file to its place. Then it tries to generate new URL and new file pathname for it (using current configuration) and uses that.

That’s why you better settle static-base-dir, static-base-url, profile-pages-dir and compact-redirected-profile-urls configuration values from the start. And, of course, base-url and home-url.

### Other files that might need to be served statically

If you run ACIS at a website’s top address, you may need or prefer to serve some other files by Apache itself, without involving ACIS. For instance, you may want to create favourites icon `/favicon.ico` for your website, or you want to create `/robots.txt` file. ACIS will not serve such files and such requests will only burden the system and clutter the logs. You have to serve these files with Apache. For that you simply have to add appropriate RewriteRules to your config, before the terminal rule line:

      RewriteRule ^/favicon.ico   - [L]
      RewriteRule ^/robots.txt    - [L]

## Apache 2 specific configuration

Do everything as described above.

If you have lines

      # terminal rule:
      RewriteRule ^(/.*)$ /cgi-bin/acis.pl$1 [L,T=application/x-httpd-cgi]

replace it with

      # terminal rule:
      RewriteRule ^/(.*)$ /cgi/acis.cgi/$1  [NS,PT]

It worked for me. I hope it helps you as well.