INSTALL

   1 public-inbox / lei installation
   2 -------------------------------
   3
   4 This is for people who want to run public-inbox on their server or
   5 lei as a command-line tool.  Any HTTP, IMAP, NNTP, or POP3 client can
   6 access public-inbox servers, as can git-{clone,fetch} on the HTTP(S)
   7 endpoint.
   8
   9 Since our marketing sucks, ease of installation is an important goal
  10 for this project and we only depend on distro-provided packages.
  11
  12 As of 2024, public-inbox is packaged by several OS distributions,
  13 listed in alphabetical order: Debian, GNU Guix, NixOS, and Void Linux.
  14
  15 public-inbox is developed on Debian GNU/Linux systems and will
  16 never depend on packages outside of the "main" component of
  17 the "oldstable" distribution, currently Debian 11.x ("bullseye"),
  18 but older versions of Debian remain supported (as are newer ones).
  19
  20 Most packages are available in other GNU/Linux distributions,
  21 Alpine Linux, FreeBSD, NetBSD, OpenBSD, and DragonflyBSD.
  22 CentOS 7.x users will likely want newer git and Xapian for
  23 better performance and v2 inbox support:
  24 https://public-inbox.org/meta/20210421151308.yz5hzkgm75klunpe@nitro.local/
  25
  26 As of 2.0, install/deps.perl makes it easier to install target
  27 dependencies needed for certain features.  See install/README in
  28 the source tree for more info.
  29
  30 Also see sa_config/ directories in the source tree for recommended
  31 SpamAssassin configuration examples if using public-inbox-mda or
  32 public-inbox-watch.
  33
  34 Requirements
  35 ------------
  36
  37 public-inbox requires a number of other packages to access its full
  38 functionality.  The core tools are, of course:
  39
  40 * Git (1.8.0+, 2.6+ for writing v2 inboxes)
  41 * Perl 5.12.0+
  42 * DBD::SQLite (needed for IMAP, NNTP, message threading, and v2 inboxes)
  43
  44 To accept incoming mail into a public inbox, you'll likely want:
  45
  46 * MTA - postfix is recommended (for public-inbox-mda)
  47 * SpamAssassin (spamc/spamd)   (for public-inbox-watch/public-inbox-mda)
  48
  49 Beyond that, there is one non-standard Perl package required:
  50
  51 * URI                              deb: liburi-perl
  52                                    pkg: p5-URI
  53                                    rpm: perl-URI
  54                                    (for HTML/Atom generation)
  55
  56 Where "deb" indicates package names for Debian-derived distributions,
  57 "pkg" is for the FreeBSD package (and some other common BSDs, too),
  58 "pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
  59 distributions (only known to work on Fedora).
  60
  61 Most users will likely also want the following:
  62
  63 - DBD::SQLite                      deb: libdbd-sqlite3-perl
  64                                    pkg: p5-DBD-SQLite
  65                                    rpm: perl-DBD-SQLite
  66                                    (for v2, IMAP, NNTP, or gzipped mboxes)
  67
  68 - Xapian(.pm) (or Search::Xapian)  deb: libsearch-xapian-perl
  69                                    pkg: p5-Xapian (FreeBSD, NetBSD)
  70                                         xapian-bindings-perl (OpenBSD)
  71                                    rpm: perl-Search-Xapian
  72                                    (required for lei; HTTP and IMAP search)
  73
  74 Other modules might be useful as well, depending on your use case and
  75 preferences:
  76
  77 - Plack                            deb: libplack-perl
  78                                    pkg: p5-Plack
  79                                    rpm: perl-Plack, perl-Plack-Test,
  80                                    (for WWW interface, public-inbox-httpd(1))
  81
  82 - Inline::C                        deb: libinline-c-perl
  83                                    pkg: p5-Inline-C
  84                                    rpm: perl-Inline (or perl-Inline-C)
  85                                    (required for lei on *BSD;
  86                                     speeds up process spawning on Linux,
  87                                     see public-inbox-daemon(8))
  88
  89 - Email::Address::XS               deb: libemail-address-xs-perl
  90                                    pkg: p5-Email-Address-XS
  91                                    (correct parsing of tricky email
  92                                     addresses, phrases and comments)
  93
  94 - Parse::RecDescent                deb: libparse-recdescent-perl
  95                                    pkg: p5-Parse-RecDescent
  96                                    rpm: perl-ParseRecDescent
  97                                    (for public-inbox-imapd(1))
  98
  99 - Mail::IMAPClient                 deb: libmail-imapclient-perl
 100                                    pkg: p5-Mail-IMAPClient
 101                                    rpm: perl-Mail-IMAPClient
 102                                    (only for lei and public-inbox-watch
 103                                     when reading from IMAP)
 104
 105 - BSD::Resource                    deb: libbsd-resource-perl
 106                                    pkg: p5-BSD-Resource
 107                                    rpm: perl-BSD-Resource
 108                                    (only for PSGI limiters,
 109                                     see public-inbox-config(5))
 110
 111 - Plack::Middleware::ReverseProxy  deb: libplack-middleware-reverseproxy-perl
 112                                    pkg: p5-Plack-Middleware-ReverseProxy
 113                                    rpm: perl-Plack-Middleware-ReverseProxy
 114                                    (ensures redirects are correct when running
 115                                     behind nginx or Varnish)
 116
 117 * highlight                        deb: libhighlight-perl
 118                                    (for syntax highlighting with coderepo)
 119
 120 * xapian-tools                     deb: xapian-tools
 121                                    pkg: xapian-core
 122                                    pkgin: xapian
 123                                    rpm: xapian-core
 124                                    (for public-inbox-compact(1) and
 125                                     public-inbox-cindex(1))
 126
 127 * Xapian development files         deb: libxapian-dev
 128                                    pkg: xapian-core
 129                                    pkgin: xapian
 130                                    apk: xapian-core-dev
 131                                    rpm: xapian-core-devel / xapian14-core-libs
 132                                    (for public-inbox-cindex(1) and future
 133                                     performance enhancements)
 134
 135 * curl (tool)                      deb, pkg, rpm: curl
 136                                    (for lei HTTP(S) externals with curl and
 137                                     public-inbox-clone(1))
 138
 139 - Linux::Inotify2                  deb: liblinux-inotify2-perl
 140                                    rpm: perl-Linux-Inotify2
 141                                    (for lei, public-inbox-watch and -imapd
 142                                     on Linux; not required as of 2.0))
 143
 144 - IO::KQueue                       pkg: p5-IO-KQueue
 145                                    (for lei, public-inbox-watch and -imapd
 146                                     on *BSDs only)
 147
 148 - Net::Server                      deb: libnet-server-perl
 149                                    pkg: p5-Net-Server
 150                                    rpm: perl-Net-Server
 151                                    (for HTTP/IMAP/NNTP background daemons,
 152                                     not needed as systemd services or
 153                                     foreground servers)
 154
 155 The following module is typically pulled in by dependencies listed
 156 above, so there is no need to explicitly install it:
 157
 158 - DBI                              deb: libdbi-perl
 159                                    pkg: p5-DBI
 160                                    rpm: perl-DBI
 161                                    (pulled in by DBD::SQLite)
 162
 163 Uncommonly needed modules (see HACKING for development-only modules):
 164
 165 - Socket6                          deb: libsocket6-perl
 166                                    pkg: p5-Socket6
 167                                    rpm: perl-Socket6
 168                                    (pulled in by SpamAssassin and Net::Server,
 169                                     only necessary if using IPv6 with
 170                                     Plack::Middleware::AccessLog or similar
 171                                     on Perl <= 5.12)
 172
 173 - Crypt::CBC                       deb: libcrypt-cbc-perl
 174                                    pkg: p5-Crypt-CBC
 175                                    (for PublicInbox::Unsubscribe (rarely used))
 176
 177 - Date::Parse                      deb: libtimedate-perl
 178                                    pkg: p5-TimeDate
 179                                    rpm: perl-TimeDate
 180                                    (for broken, mostly historical emails)
 181
 182 standard MakeMaker installation (Perl)
 183 --------------------------------------
 184
 185 To use MakeMaker, you need to ensure ExtUtils::MakeMaker is available.
 186 This is typically installed with Perl, but RPM-based systems will likely
 187 need to install the `perl-ExtUtils-MakeMaker' package.
 188
 189 Once the dependencies are installed, you should be able to build and
 190 install the system (into /usr/local) with:
 191
 192         perl Makefile.PL
 193         make
 194         make test    # see HACKING for faster tests for hackers
 195         make install # root permissions may be needed
 196
 197 symlink-install (public-inbox.git and 1.7.0+)
 198 ---------------------------------------------
 199
 200 For users who lack permissions and/or wish to minimize their
 201 installation footprint, the "symlink-install" target is available in
 202 public-inbox.git.  The following installs symlinks to $HOME/bin
 203 pointing to the source tree:
 204
 205         perl Makefile.PL
 206         make symlink-install prefix=$HOME
 207
 208 Other installation notes
 209 ------------------------
 210
 211 Debian 8.x (jessie) users, use Debian 8.5 or later if using Xapian:
 212         https://bugs.debian.org/808610
 213
 214 public-inbox-* commands will never store unregeneratable data in
 215 Xapian nor any other search database we might use; Xapian
 216 corruption will not destroy critical data.  Note: `lei' DOES store
 217 unregeneratable data in Xapian and SQLite.
 218
 219 See the public-inbox-overview(7) man page for the next steps once
 220 the installation is complete.
 221
 222 The following required packages are part of the Perl standard
 223 library.  Debian-based distros put them in "libperl5.$MINOR" or
 224 "perl-modules-5.$MINOR"; and FreeBSD puts them in "perl5".
 225 RPM-based distros split them out into separate packages:
 226
 227 * autodie                          rpm: perl-autodie
 228 * Digest::SHA                      rpm: perl-Digest-SHA
 229 * Data::Dumper                     rpm: perl-Data-Dumper
 230 * IO::Compress                     rpm: perl-IO-Compress
 231 * Sys::Syslog                      rpm: perl-Sys-Syslog
 232 * Text::ParseWords                 rpm: perl-Text-Parsewords
 233
 234 Copyright
 235 ---------
 236
 237 Copyright all contributors <meta@public-inbox.org>
 238 License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>