Making your downloads mirrorable

This is a step-by-step guide that shows what I have done to make Ant's releases mirrorable. The process should be the same for other Jakarta and XML projects, but if I have missed something, please tell me (and maybe submit a patch to this page).

Prepare for the move

Going live on www.apache.org

Send your users to the mirrors

If your-project is a Jakarta project and has no download pages of its own, all you need to do is to add a link to the "Using a mirror" list under "Release" on /xdocs/site/binindex.xml and /xdocs/site/sourceindex.xml in the jakarta-site2 module, regenerate the HTML pages and commit everything. For the links you'd simply replace http://www.apache.org/dist with [preferred] in your download URL.

If you want something more sophisticated (or simply have download pages of your own or are not under the Jakarta umbrella), read on.

The old way to send people to the mirrors has been a link to http://www.apache.org/dyn/closer.cgivirtual-path where virtual-path would be replaced by your download URL minus http://www.apache.org/dist. This still works but has the drawbacks that you don't have control over the layout of that page and that users may use the signatures found on the mirrors to verify the releases instead of picking them up from www.apache.org.

To solve the layout problem, Justin Erenkrantz (and others?) have written http://www.apache.org/dyn/mirrors/mirrors.cgi which parses a template and replaces certain [expression]s with something useful. To write and use a template of your own, you currently need to do three things.

  1. Write your template. It should be straight forward to do so by looking at examples like httpd's, Ant's or Jakarta's pages. These all use Anakia, but it should be possible to integrate it with different technologies as well. For example, Forrest uses Forrest for the template. There even is a tutorial on creating such templates with Forrest.
  2. For each template, add a CGI script (with extension .cgi) to your site. This script must look like this:
    #!/bin/sh
    # Wrapper script around mirrors.cgi script
    # (we must change to that directory in order for python to pick up the
    #  python includes correctly)
    cd /www/www.apache.org/dyn/mirrors
    /www/www.apache.org/dyn/mirrors/mirrors.cgi $*
    
    Well, you could probably trim the comments. Ensure that the checked out file on minotaur is executable and has Unix line-ends. CVS will translate the line-ends for you while Subversion in general will not (unless you tell it).
  3. Tell mirrors.cgi where to find your template. To do so, you need to add a line to /docs/dyn/mirrors/mirrors.conf in the site module (in https://svn.apache.org/repos/asf/infrastructure/site/trunk/) This file is under SVN control, don't edit the checked out copy on minotaur directly. If there is no section for your virtual host, add it. Next add the virtual path to your CGI script from above (replacing / with -) as key and the full physical path of your template as value. You will need commit access to the site module to do this (all ASF members have) - if you don't have karma for it, send a patch to infrastructure at apache.

After updating both /www/www.apache.org/dyn/mirrors/mirrors.conf and your site, your new download page should show up, when you access your CGI script.

How to deal with old releases

Old releases should be copied to http://archive.apache.org/dist/ - simply follow the same directory layout that your distribution under www.apache.org uses. You find the site in /www/archive.apache.org on minotaur.

Once you start distributing via www.apache.org you can forget carying for your old releases as archive.apache.org will automatically archive everything that has been on www.apache.org.


Stefan Bodewig
Last modified: Thu Oct 7 14:50:16 CEST 2004