Contents

• Contents
• Introduction
• Mirroring Instructions
• Archiving Old Releases
• Step By Step Guide To Archiving Unmirrored Releases

This is a guide to converting existing Apache projects to use the mirrors. It may also prove useful for new projects who need to release distributions through the system of mirrors for the first time. This guide contains short step-by-step instructions aimed at ensuring no steps are forgotten. Familiarity with the principles presented in the ASF mirroring guidelines and Stefan Bodewig's Guide is assumed.

Throughout the guide, the examples will consistently assume that the project is called xxx with current release version m.n, that the Apache user is rdonkin who has karma for www.apache.org. It is also assumed that the user is already in a suitable working directory. The examples are for *nix (anyone want to supply some instructions for windoz?) Please remember to check that your umask and group for www.apache.org are set appropriately before beginning.

The examples also assume that gpg is used for code signing. If you use pgp, then some changes will be necessary. They also use openssl for the md5 sums. md5sum (or any other sum generator) could be used instead. Please use a secure local machine to perform the signing. Please remember to use a good passphrase to secure your code signing private key.

(Conversion Only) Only copy the most modern releases onto the mirrored directories. This helps to conserve disc space both on the ASF servers and on the mirrors. The others should be preserved through archive.apache.org (see below).

1. (Conversion Only) Check that releases are not already mirrored. If the release being converted is found in a directory below /www/www.apache.org/dist/ then the release is already mirrored. (You may still need to set up appropriate download scripts.)
2. Gain approval from project PMC. All Apache releases must be formally approved by the PMC responsible for them. (New Releases Only) Having got this far in the release process, this approval should already have been sought and received.
3. Ensure all releases are signed. It is vitally important that both OpenPGP signatures and md5sums are created for every mirrored release. So, check that these have been created and if necessary, sign and create md5 sums for each releasable:

   $ tar xzvf ~/release.tar.gz
   $ gpg --armor --output xxx-m.n.tgz.asc --detach-sig xxx-m.n.tgz  
   user: "Robert Burrell Donkin (CODE SIGNING KEY)
   <rdonkin.AT.apache.DOT.org>"
   1024-bit DSA key, ID B1313DE2, created 2003-01-15
   $ openssl md5 < xxx-m.n.tgz > xxx-m.n.tgz.md5
   

4. Test signatures and sums. Ideally, test by verifying from second account and calculating sums using second method. For example:

   robert% gpg --verify xxx-m.n.zip.asc xxx-m.n.zip
   gpg: Signature made 09/01/03 21:31:21 BST using DSA key ID B1313DE2
   gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY)
   <rdonkin.AT.apache.DOT.org>"
   

5. Tar then upload to www.apache.org:

   $ tar czvf ~/release.tar.gz .
   [localhost:jakarta/release/xxx]% scp release.tar.gz rdonkin@www.apache.org:
   

6. Log on to www.apache.org and change to the appropriate (mirrored) releases directory

   % ssh -l rdonkin www.apache.org
   > cd /www/www.apache.org/dist/xxx/
   

7. Create product directory (if necessary) then change to that directory. Create binaries and source directories. The directory structure should match the standard layout.
8. Untar releases and copy to appropriate subfolders

   > tar xzfv ~/release.tar.gz .
   > mv xxx-m.n.src* source
   > mv xxx-m.n* binaries
   

9. Do not use symbolic links in mirrored directories! If you want to provide "current" links, then use redirects.
10. Update KEYS file. The standard directory layout contains a KEYS list. This file should contain the public keys used to sign any release that has ever been signed. Make sure that the key used to sign the releases is included in the KEYS file. Please do not delete old keys from the file. This is a good time to check that your public key is available from at least one public key server. It is also wise (at this point) to review your web of trust. If your key does not have signatures linking it into the wider ASF web of trust, then please strongly consider taking steps next time the opportunity arises to cross sign the key with other ASF release managers.
11. Wait 24 hours for the mirrors to update.
12. Update websites. (New Releases Only) If this is the first time that the project has created a release, it will be neccessary to set up a page from which the mirrored distributables can be downloaded. There are various options for this and it may be wisest to consult with the community and seek the advice of your mentor. The details are too involved to be included here.
13. Inform developers with a polite email to their list.

Over time, old releases start to take up up valuable disc space on the servers of ASF and of it's mirrors. Once a release is no longer widely downloaded, the advantages of mirroring are outweighed by these disadvantages.

To solve this problem, the Apache Software Foundation has now created a permanent place where older releases can retire to. The infrastructure crew will ensure that these release continue to be made available to the general public and also that they are preserved for posterity.

Older releases (which have never been mirrored) should be placed directly under archive.apache.org/dist/. Once a release is placed under www.apache.org/dist/ it will automatically be copied over to archive.apache.org and held there permanently: even after it is deleted from www.apache.org. So, all that is required to archive any mirrored release is to delete it from www.apache.org. Adding a permanent redirect for the release to the .htaccess file should be considered.

1. Log on to www.apache.org

   robert% ssh -l rdonkin www.apache.org                        
   

2. Change to the directory containing the releases

                   
   > cd /www/xxx.apache.org/builds/release
   

3. Create a new directory in the archive directory in the archives to contain the old releases. (You may need to create the product directory as well.)

                   
   > mkdir /www/archive.apache.org/dist/xxx/old
   

4. Move all releases from the old distribution directory to the archive

                   
   > mv * /www/archive.apache.org/dist/xxx/old
   

5. Change to the root build directory for the project

                   
   > cd ..
   

6. Create a text file called .htaccess (using the text editor of your choice) if one does not exist already. Add an entry to permanently redirect those trying to download the old releases. For more details on how to do this, please see the Apache HTTP Server Documentation.