public-inbox (server-side) installation
---------------------------------------

This is for folks who want to setup their own public-inbox instance.
Clients should use normal git-clone/git-fetch, or NNTP clients
if they want to import mail into their personal inboxes.

public-inbox is developed on Debian GNU/Linux systems and will
never depend on packages outside of the "main" component of
the "stable" distribution, currently Debian 9.x ("stretch")

Most packages are available in other GNU/Linux distributions
and FreeBSD.

TODO: this still needs to be documented better,
also see the scripts/ and sa_config/ directories in the source tree

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

public-inbox requires a number of other packages to access its full
functionality.  The core tools are, of course:

* Git (1.8.0+, 2.6+ for writing v2 repositories)
* Perl 5.10.1+
* DBD::SQLite (needed for NNTP, message threading, and v2 repositories)

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)

Beyond that, there is a long list of Perl modules required, starting with:

* Date::Parse                      deb: libtimedate-perl
                                   pkg: p5-TimeDate
                                   rpm: perl-TimeDate

* Digest::SHA                      typically installed with Perl
                                   rpm: perl-Digest-SHA

* Email::MIME                      deb: libemail-mime-perl
                                   pkg: p5-Email-MIME
                                   rpm: perl-Email-MIME

* Plack                            deb: libplack-perl
                                   pkg: p5-Plack
                                   rpm: perl-Plack, perl-Plack-Test,
                                   (for HTML/Atom generation)

* URI::Escape                      deb: liburi-perl
                                   pkg: p5-URI
                                   rpm: perl-URI
                                   (for HTML/Atom generation)

Where "deb" indicates package names for Debian-derived distributions,
"pkg" is for the FreeBSD package (maybe other common BSDs, too), and
"rpm" is for RPM-based distributions (only known to work on Fedora).

Numerous optional modules are likely to be useful as well:

- DBD::SQLite                      deb: libdbd-sqlite3-perl
                                   pkg: p5-DBD-SQLite
                                   rpm: perl-DBD-SQLite
                                   (for v2, NNTP, or gzipped mboxes)

- Search::Xapian                   deb: libsearch-xapian-perl
                                   pkg: p5-Search-Xapian
                                   rpm: perl-Search-Xapian
                                   (HTTP search)

- Net::Server                      deb: libnet-server-perl
                                   pkg: pkg-Net-Server
                                   rpm: perl-Net-Server
                                   (for HTTP/NNTP background daemons,
                                    not needed as systemd services or
                                    foreground servers)

- Inline::C[7]                     deb: libinline-c-perl
                                   pkg: pkg-Inline-C
                                   (speeds up process spawning on Linux,
                                    see public-inbox-daemon(8))

- Plack::Middleware::ReverseProxy  deb: libplack-middleware-reverseproxy-perl
                                   pkg: p5-Plack-Middleware-ReverseProxy
                                   rpm: perl-Plack-Middleware-ReverseProxy
                                   (ensures redirects are correct when running
                                    behind nginx or Varnish)

- Plack::Middleware::Deflater      deb: libplack-middleware-deflater-perl
                                   pkg: p5 -Plack-Middleware-Deflater
                                   rpm: perl-Plack-Middleware-Deflater
                                   (saves bandwidth on responses)

* highlight                        deb: libhighlight-perl
                                   (for syntax highlighting with coderepo)

* xapian-compact (tool)            deb: xapian-tools
                                   pkg: xapian-core
                                   rpm: xapian-core
                                   (optional, for public-inbox-compact(1))

The following modules are typically pulled in by dependencies listed
above, so there is no need to explicitly install them:

- Email::MIME::ContentType         deb: libemail-mime-contenttype-perl
                                   pkg: p5-Email-MIME-ContentType
                                   rpm: perl-Email-MIME-ContentType
                                   (pulled in by Email::MIME)

- Email::Simple                    deb: libemail-simple-perl
                                   pkg: p5-Email-Simple
                                   rpm: perl-Email-Simple
                                   (pulled in by Email::MIME)

* Encode                           deb: libperl5.$MINOR (or libencode-perl)
                                   pkg: perl5
                                   rpm: perl-Encode
                                   (likely installed with Perl)

- DBI                              deb: libdbi-perl
                                   pkg: p5-DBI
                                   rpm: perl-DBI
                                   (pulled in by DBD::SQLite)

* Devel::Peek                      deb: libperl5.$MINOR (e.g. libperl5.24)
                                   pkg: perl5
                                   rpm: perl-Devel-Peek
                                   (optional for stale FD cleanup in daemons,
                                    typically installed alongside Perl5)

- Filesys::Notify::Simple          deb: libfilesys-notify-simple-perl
                                   pkg: pkg-Filesys-Notify-Simple
                                   rpm: perl-Filesys-Notify-Simple
                                   (for public-inbox-watch, pulled in by Plack)

- IO::Compress::Gzip               deb: perl-modules (or libio-compress-perl)
                                   pkg: perl5
                                   rpm: perl-IO-Compress
                                   (for gzipped mbox over HTTP)

Uncommonly needed modules:

- Socket6                          deb: libsocket6-perl
                                   pkg: p5-Socket6
                                   rpm: perl-Socket6
                                   (pulled in by SpamAssassin and Net::Server,
                                    only necessary if using IPv6 with
                                    Plack::Middleware::AccessLog or similar
                                    on Perl <= 5.12)

- Crypt::CBC                       deb: libcrypt-cbc-perl
                                   pkg: p5-Crypt-CBC
                                   (for PublicInbox::Unsubscribe (rarely used))

Optional packages testing and development:

- IPC::Run                         deb: libipc-run-perl
                                   pkg: p5-IPC-Run
                                   rpm: perl-IPC-Run

- Plack::Test                      deb: libplack-test-perl
                                   pkg: p5-Plack
                                   rpm: perl-Plack-Test

- Test::Simple                     deb: perl-modules-5.$MINOR
                                   pkg: perl5
                                   rpm: perl-Test-Simple

- XML::Feed                        deb: libxml-feed-perl
                                   pkg: p5-XML-Feed
                                   rpm: perl-XML-Feed

standard MakeMaker installation (Perl)
--------------------------------------

To use MakeMaker, you need to ensure ExtUtils::MakeMaker is available.
This is typically installed with Perl, but RPM-based systems will likely
need to install the `perl-ExtUtils-MakeMaker' package.

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

For Debian 8.x (jessie), this means using Debian 8.5 or later.

public-inbox will never store unregeneratable data in Xapian
or any other search database we might use; Xapian corruption
will not destroy critical data.

See the public-inbox-overview(7) man page for the next steps once
the installation is complete.

Copyright
---------

Copyright 2013-2019 all contributors <meta@public-inbox.org>
License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>