Archiveopteryx
http://www.archiveopteryx.org


See http://www.archiveopteryx.org/overview for an introduction
and http://www.archiveopteryx.org/3.1.3 for information about
version 3.1.3.


Requirements
------------

You need g++ (and associated packages) to build this software.

You need to have PostgreSQL installed to use Archiveopteryx. We
recommend the latest 8.x version (but anything newer than 8.1.0
should work; see http://www.archiveopteryx.org/postgresql/).


Installation
------------

For detailed installation instructions, see:
http://www.archiveopteryx.org/installation

Here's a brief overview of the steps to follow while installing
Archiveopteryx for the first time (see below if you're upgrading):

1. Type "make" to compile the software.

   We test the build on Linux and FreeBSD. 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 if you tell us about them, we'd be
   happy to help you resolve them.

2. Type "make install" as root to install the software into /usr/local
   (then switch to that directory to continue).

   The archiveopteryx(7) manual page introduces the software.

   (You may want to add /usr/local/man to your MANPATH.)

3. Run "lib/installer" to create a Unix user and group, a PostgreSQL
   user, the necessary database tables, and to generate an initial
   configuration file.

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

   The generated configuration file should work fine, but you may need
   to edit it, for example, to enable POP3, or make the servers listen
   on some interface other than localhost. See archiveopteryx.conf(5)
   for more details.

4. Start the servers: "bin/aox start".

   aox is the command-line administration tool for Archiveopteryx.
   See aox(8) or run "bin/aox help" for usage instructions.

   The servers write log output to syslog/mail.

   (To start the servers automatically at boot, use lib/archiveopteryx
   as an init script.)

5. 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.

6. Configure your MTA to deliver incoming mail into Archiveopteryx via
   LMTP (or via bin/deliver, if your MTA doesn't speak LMTP). See, e.g.
   http://www.archiveopteryx.org/postfix and .../exim for details.

7. Add an entry to root's crontab to run "aox vacuum" daily. Remember to
   enable PostgreSQL's "autovacuum" feature too (strongly recommended),
   or at least to run "vacuumdb -qaz" from the postgres user's crontab.
   You'll also need to adjust the memory settings in postgresql.conf
   (shared_buffers, effective_cache_size) for better performance.


Upgrading Archiveopteryx
------------------------

1. "make" and "make install" as above.

2. Upgrade the schema, if necessary: "aox stop; aox upgrade schema"

   We sometimes change the database schema between releases, so you may
   need to stop the server and upgrade the schema. You can check if the
   schema is up to date with "aox show schema". The new server will not
   start until the schema is at 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.

3. Restart the servers: "aox restart"

4. Update the database, if necessary: "aox update 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 always 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.


Mailing Lists
-------------

There are mailing lists for Archiveopteryx users and announcements. To
subscribe to the users list (which also gets announcements), send mail:

    echo|mail -s subscribe users-request@aox.org

To subscribe instead to the low-volume announcements list:

    echo|mail -s subscribe announce-request@aox.org


If you encounter any problems or have any suggestions, please write to
info@aox.org. Your comments help us improve Archiveopteryx.
