README
1Archiveopteryx
2http://archiveopteryx.org
3
4
5See http://archiveopteryx.org/overview for an introduction
6and http://archiveopteryx.org/$VERSION for information about
7version $VERSION.
8
9
10Requirements
11------------
12
13You need g++ (and associated packages) to build this software.
14
15You need to have PostgreSQL installed to use Archiveopteryx. We
16recommend the latest 9.x version (but anything newer than 9.1
17should work; see http://archiveopteryx.org/postgresql/).
18
19
20Installation
21------------
22
23For detailed installation instructions, see:
24http://archiveopteryx.org/installation
25
26Here's a brief overview of the steps to follow while installing
27Archiveopteryx for the first time (see below if you're upgrading):
28
291. Type "make" to compile the software.
30
31 We test the build on Linux and FreeBSD. You may encounter some errors
32 if you compile elsewhere. We make few demands of the platform, so any
33 errors are likely to be minor, and if you tell us about them, we'd be
34 happy to help you resolve them.
35
362. Type "make install" as root to install the software into $PREFIX
37 (then switch to that directory to continue).
38
39 The archiveopteryx(7) manual page introduces the software.
40
41 (You may want to add $MANDIR to your MANPATH.)
42
433. Run "lib/installer" to create a Unix user and group, a PostgreSQL
44 user, the necessary database tables, and to generate an initial
45 configuration file.
46
47 See installer(8) for details, or run "lib/installer -n" to see what
48 commands the installer would run, without running them.
49
50 The generated configuration file should work fine, but you may need
51 to edit it, for example, to enable POP3, or make the servers listen
52 on some interface other than localhost. See archiveopteryx.conf(5)
53 for more details.
54
554. Start the servers: "bin/aox start".
56
57 aox is the command-line administration tool for Archiveopteryx.
58 See aox(8) or run "bin/aox help" for usage instructions.
59
60 The servers write log output to $LOGFILE.
61
62 (To start the servers automatically at boot, use lib/archiveopteryx
63 as an init script.)
64
655. Create some users, e.g. with:
66
67 bin/aox add user nirmala pwd nirmala@example.com
68
69 Archiveopteryx will create a user named nirmala (with password "pwd")
70 and accept mail sent to the given address, and store it in a mailbox
71 named /users/nirmala/INBOX, which can be accessed via IMAP or POP.
72
736. Configure your MTA to deliver incoming mail into Archiveopteryx via
74 LMTP (or via bin/deliver, if your MTA doesn't speak LMTP). See, e.g.
75 http://archiveopteryx.org/postfix and .../exim for details.
76
777. Add an entry to root's crontab to run "aox vacuum" daily. Remember to
78 enable PostgreSQL's "autovacuum" feature too (strongly recommended),
79 or at least to run "vacuumdb -qaz" from the postgres user's crontab.
80 You'll also need to adjust the memory settings in postgresql.conf
81 (shared_buffers, effective_cache_size) for better performance.
82
83
84Upgrading Archiveopteryx
85------------------------
86
871. "make" and "make install" as above.
88
892. Upgrade the schema, if necessary: "aox stop; aox upgrade schema"
90
91 We sometimes change the database schema between releases, so you may
92 need to stop the server and upgrade the schema. You can check if the
93 schema is up to date with "aox show schema". The new server will not
94 start until the schema is at the version it expects.
95
96 It is safe to run "aox upgrade schema" when the server is stopped. If
97 it doesn't need to do anything, it will just exit.
98
99 We try to keep schema upgrades fast, to minimise downtime.
100
1013. Restart the servers: "aox restart"
102
1034. Update the database, if necessary: "aox update database"
104
105 Very rarely, we may need to make extensive changes to the database.
106 In this case, you will need to run "aox update database" after you
107 install and start the new server. The server will operate normally
108 as the update proceeds. The release notes for a particular version
109 will always mention it if you need to update the database.
110
111 It is always safe to run "aox update database", whether the server is
112 stopped or running. If it doesn't need to do anything, it will exit.
113 If the process is terminated, it is safe to restart it; it will pick
114 up where it left off.
115
116
117Mailing Lists
118-------------
119
120There are mailing lists for Archiveopteryx users and announcements. To
121subscribe to the users list (which also gets announcements), send mail:
122
123 echo|mail -s subscribe users-request@aox.org
124
125To subscribe instead to the low-volume announcements list:
126
127 echo|mail -s subscribe announce-request@aox.org
128
129
130If you encounter any problems or have any suggestions, please write to
131info@aox.org. Your comments help us improve Archiveopteryx.
132