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 2.13 are available at 2.13.

Building the source code

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

To compile, run make in the archiveopteryx-2.13 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.

The compile-time variables are archiveopteryx-2.13/Jamsettings. You shouldn't ordinarily need to change them, and most of these values can be overriden at runtime in the configuration file. (We use Jam to build the software, and provide the Makefile in release tarballs only as a convenience. If you need to change any of the settings, you'll need to install Jam.)

If you're installing on a cluster, you can split the executables up almost as you like - but in that case, we strongly suggest getting some help from us.

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.

See installer(8) for details, or run "lib/installer -n" to see exactly what commands the installer would run, without running them.

The configuration file generated is /usr/local/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 servers

Run "bin/aox start" to start the servers. (You should see log output in /usr/local/archiveopteryx/logfile.)

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 nirmala@example.com"

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, Sendmail, 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 info@oryx.com.)

Relevant links

If you have problems or questions, please write to info@oryx.com.