Installing Archiveopteryx

If you're installing Archiveopteryx for the first time, these are the steps you have to follow:

If you're upgrading an existing installation, here's what you have to do instead:

These steps are explained in detail below. Any special release-specific considerations will be documented in the web page for that release. The release notes for Archiveopteryx 3.0.7 are available at 3.0.7.

Building the source code

Download the Archiveopteryx source code and untar it. For example, archiveopteryx-3.0.7.tar.bz2 will untar into a directory named archiveopteryx-3.0.7.

To compile, run make in the archiveopteryx-3.0.7 directory. (You need to have g++ and associated packages installed.) To install, run make install as root in the same directory. Executables and manual pages will be installed under /usr/local/archiveopteryx.

We test the build on Linux and FreeBSD, so you may encounter some errors if you compile elsewhere. We make few demands of the platform, so any errors are likely to be minor, and we'd be happy to help you resolve them. (Given enough demand, we'd be happy to add other platforms to our test ensemble.)

Running the installer

You'll need to have PostgreSQL installed and running before this step. We recommend using the latest 8.x release (but anything later than 8.1.0 should work).

Run lib/installer (in /usr/local/archiveopteryx) to create a Unix user and group for the servers to run as, a PostgreSQL user and a database with the necessary tables, and to generate the configuration file that's good enough to start and test the servers.

Run lib/installer -n to see exactly what commands the installer would run, without running those commands.

The configuration file generated is /usr/local/archiveopteryx/archiveopteryx.conf by default. (If it is elsewhere, aox show build reveals where.)

Remember to enable autovacuum to vacuum your database regularly (or at least set up a cron job to run vacuumdb -qaz periodically).

Starting the server

Run bin/aox start to start the server. (You should see log output eitber in /usr/local/archiveopteryx/logfile or in syslog.)

If you change anything in the configuration file, you can make the changes take effect with bin/aox restart.

Creating Archiveopteryx users

Create some users, e.g. with: bin/aox add user nirmala pwd

Archiveopteryx will create a user named nirmala (with password pwd) and accept mail sent to the given address, and store it in a mailbox named /users/nirmala/INBOX, which can be accessed via IMAP or POP. Use bin/aox list users to see a list of users; and aox help for usage instructions.

Configuring mail delivery

Configure your MTA to deliver incoming mail into Archiveopteryx via LMTP (or use deliver, if your MTA doesn't speak LMTP). We have detailed instructions on how to configure Postfix, Exim, and Qmail.

That's all!

The users you created should now be able to read their mail via IMAP. (If you want to use POP, you'll have to set use-pop to true in the configuration file.

Upgrading the schema

We sometimes change the database schema between releases, so you may need to stop the servers (aox stop) and run aox upgrade schema occasionally. aox show schema will display the current schema version and tell you if it needs to be upgraded. The newly-installed server will also refuse to start until the schema matches the version it expects.

It is safe to run aox upgrade schema when the server is stopped. If it doesn't need to do anything, it will just exit.

We try to keep schema upgrades fast, to minimise downtime.

Updating the database

Very rarely, we may need to make extensive changes to the database. In this case, you will need to run aox update database after you install and start the new server. The server will operate normally as the update proceeds. The release notes for a particular version will always mention it if you need to update the database.

It is safe to run aox update database, whether the server is stopped or running. If it doesn't need to do anything, it will exit. If the process is terminated, it is safe to restart it; it will pick up where it left off.

Binary packages

There are currently no binary packages available, but we hope to see that change soon. (If you're working on Unix/Linux distribution and want to include a Archiveopteryx package, please get in touch with

Development and patches

If you want to look at the latest development version of Archiveopteryx, or contribute a patch, you need to use the git repository. Anonymous access is available.

Relevant links

If you have problems or questions, please write to

About this page

Last modified: 2011-05-17