about summary refs log tree commit homepage
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL150
1 files changed, 101 insertions, 49 deletions
diff --git a/INSTALL b/INSTALL
index 11d844cf..87aa6961 100644
--- a/INSTALL
+++ b/INSTALL
@@ -8,60 +8,117 @@ if they want to import mail into their personal inboxes.
 TODO: this still needs to be documented better,
 also see the scripts/ and sa_config/ directories in the source tree
 
-It should also be possible to use public-inbox with only IMAP
-(or even POP(!)) access to a mailbox.
-
-standard MakeMaker installation (Perl)
---------------------------------------
-
-        perl Makefile.PL
-        make
-        make test
-        make install # root permissions may be needed
-
 Requirements
 ------------
 
-* git
-* Perl and several modules:    (Debian package name)
-  - Date::Parse                libtimedate-perl
-  - Email::MIME                libemail-mime-perl
-  - Email::MIME::ContentType   libemail-mime-contenttype-perl
-  - Encode::MIME::Header       perl
+public-inbox requires a number of other packages to access its full
+functionality.  The core tools are, of course:
 
-Optional components:
+* Git
+* Perl
+* SQLite (needed for Xapian use)
+
+To accept incoming mail into a public inbox, you'll likely want:
 
 * MTA - postfix is recommended (for public-inbox-mda)
 * SpamAssassin (spamc/spamd)   (for public-inbox-watch/public-inbox-mda)
 
-Optional Perl modules:
-
-  - Plack[1]                   libplack-perl
-  - URI::Escape[1]             liburi-perl
-  - Search::Xapian[2][3]       libsearch-xapian-perl
-  - IO::Compress::Gzip[3]      perl-modules (or libio-compress-perl)
-  - DBI[3]                     libdbi-perl
-  - DBD::SQLite[2][3]          libdbd-sqlite3-perl
-  - Danga::Socket[4]           libdanga-socket-perl
-  - Net::Server[5]             libnet-server-perl
-  - Filesys::Notify::Simple[6] libfilesys-notify-simple-perl
-  - Inline::C[7]               libinline-c-perl
-  - Plack::Middleware::ReverseProxy[8] libplack-middleware-reverseproxy-perl
-  - Plack::Middleware::Deflater[8] libplack-middleware-deflater-perl
-
-[1] - Optional, needed for serving/generating Atom and HTML pages
-[2] - Optional, only required for NNTP server
-[3] - Optional, needed for gzipped mbox support over HTTP
-[4] - Optional, needed for bundled HTTP and NNTP servers
-[5] - Optional, needed for standalone daemonization of HTTP+NNTP servers
-[6] - Optional, needed for public-inbox-watch Maildir watcher
-[7] - Optional, allows speeds up spawning on Linux (see public-inbox-daemon(8))
-[8] - Optional, recommended for PSGI interface
+Beyond that, there is a long list of Perl modules required, starting with:
+
+* Date::Parse                   deb: libdatetime-perl
+                                rpm: perl-Time-ParseDate
+
+* Email::MIME                   deb: libemail-mime-perl
+                                rpm: perl-Email-MIME
+
+* Email::MIME::ContentType      deb: libemail-mime-contenttype-perl
+                                rpm: perl-Email-MIME-ContentType
+
+* Encode::MIME::Header          deb: libencode-perl
+                                rpm: perl-Encode
+
+Where "deb" indicates package names for Debian-derived distributions and
+"rpm" is for RPM-based distributions (only known to work on Fedora).
+
+Numerous optional modules are likely to be useful as well:
+
+  - Plack                      deb: libplack-perl
+                               rpm: perl-Plack, perl-Plack-Test,
+                               (for HTML/Atom generation)
+
+  - URI::Escape                deb: liburi-perl
+                               rpm: perl-URI
+                               (for HTML/Atom generation)
+
+  - Search::Xapian             deb: libsearch-xapian-perl
+                               rpm: perl-Search-Xapian
+                               (for NNTP service or gzipped mbox over HTTP)
+
+  - IO::Compress::Gzip         deb: perl-modules (or libio-compress-perl)
+                               rpm: perl-PerlIO-gzip
+                               (for gzipped mbox over HTTP)
+
+  - DBI                        deb: libdbi-perl
+                               rpm: perl-DBI
+                               (for gzipped mbox over HTTP)
+
+  - DBD::SQLite                deb: libdbd-sqlite3-perl
+                               rpm: perl-DBD-SQLite
+                               (for NNTP service or gzipped mbox over HTTP)
+
+  - Danga::Socket              deb: libdanga-socket-perl
+                               rpm: perl-Danga-Socket
+                               (for bundled HTTP and NNTP servers)
+
+  - Net::Server                deb: libnet-server-perl
+                               rpm: perl-Net-Server
+                               (for HTTP/NNTP servers as standalone daemons)
+
+  - Filesys::Notify::Simple    deb: libfilesys-notify-simple-perl
+                               rpm: perl-Filesys-Notify-Simple
+                               (for public-inbox-watch)
+
+  - Inline::C[7]               deb: libinline-c-perl
+                               (speeds up spawning on Linux
+                                (see public-inbox-daemon(8))
+
+  - Plack::Middleware::ReverseProxy
+
+                               deb: libplack-middleware-reverseproxy-perl
+                               rpm: perl-Plack-Middleware-ReverseProxy
+                               (ensures redirects are correct when running
+                                behind nginx or Varnish)
+
+  - Plack::Middleware::Deflater
+
+                               deb: libplack-middleware-deflater-perl
+                               rpm: perl-Plack-Middleware-Deflater
+                               (saves bandwidth on responses)
+
+
+On Fedora systems, you'll probably also end up wanting
+perl-Test-HTTP-Server-Simple, perl-Devel-Peek, and perl-IPC-Run to run the
+test suite.  On Debian systems, libxml-feed-perl and libipc-run-perl(*)
+will aid in running the test suite (XML::Feed and IPC::Run respectively,
+on CPAN).
+
+(*) we hope to drop this dependency someday
+
+standard MakeMaker installation (Perl)
+--------------------------------------
+
+Once the dependencies are installed, you should be able to build and
+install the system (into /usr/local) with:
+
+        perl Makefile.PL
+        make
+        make test
+        make install # root permissions may be needed
 
 When installing Search::Xapian, make sure the underlying Xapian
 installation is not affected by an index corruption bug:
 
-        https://bugs.debian.org/808610
+        https://bugs.debian.org/808610
 
 For Debian 8.x (jessie), this means using Debian 8.5 or later.
 
@@ -69,13 +126,8 @@ public-inbox will never store unregeneratable data in Xapian
 or any other search database we might use; Xapian corruption
 will not destroy critical data.
 
-Optional Perl modules (for developers):
-
-  - XML::Feed[9]               libxml-feed-perl
-  - IPC::Run[10]               libipc-run-perl
-
-[9] - Optional, for testing Atom feeds
-[10] - Optional, for some tests (we hope to drop this dependency someday)
+See the public-inbox-overview(7) man page for the next steps once the
+installation is complete.
 
 Copyright
 ---------