NAME

       public-inbox-tuning - tuning public-inbox

DESCRIPTION

       public-inbox intends to support a wide variety of hardware.  While we strive to provide
       the best out-of-the-box performance possible, tuning knobs are an unfortunate necessity in
       some cases.

       1.  New inboxes: public-inbox-init -V2

       2.  Process spawning

       3.  Performance on rotational hard disk drives

       4.  Btrfs (and possibly other copy-on-write filesystems)

       5.  Performance on solid state drives

       6.  Read-only daemons

   New inboxes: public-inbox-init -V2
       If you're starting a new inbox (and not mirroring an existing one), the -V2 requires
       DBD::SQLite, but is orders of magnitude more scalable than the original "-V1" format.

   Process spawning
       Our optional use of Inline::C speeds up subprocess spawning from large daemon processes.

       To enable Inline::C, either set the "PERL_INLINE_DIRECTORY" environment variable to point
       to a writable directory, or create "~/.cache/public-inbox/inline-c" for any user(s)
       running public-inbox processes.

       More (optional) Inline::C use will be introduced in the future to lower memory use and
       improve scalability.

   Performance on rotational hard disk drives
       Random I/O performance is poor on rotational HDDs.  Xapian indexing performance degrades
       significantly as DBs grow larger than available RAM.  Attempts to parallelize random I/O
       on HDDs leads to pathological slowdowns as inboxes grow.

       While "-V2" introduced Xapian shards as a parallelization mechanism for SSDs; enabling
       "publicInbox.indexSequentialShard" repurposes sharding as mechanism to reduce the kernel
       page cache footprint when indexing on HDDs.

       Initializing a mirror with a high "--jobs" count to create more shards (in "-V2" inboxes)
       will keep each shard smaller and reduce its kernel page cache footprint.  Keep in mind
       excessive sharding imposes a performance penalty for read-only queries.

       Users with large amounts of RAM are advised to set a large value for
       "publicinbox.indexBatchSize" as documented in public-inbox-index(1).

       "dm-crypt" users on Linux 4.0+ are advised to try the "--perf-same_cpu_crypt"
       "--perf-submit_from_crypt_cpus" switches of cryptsetup(8) to reduce I/O contention from
       kernel workqueue threads.

   Btrfs (and possibly other copy-on-write filesystems)
       btrfs(5) performance degrades from fragmentation when using large databases and random
       writes.  The Xapian + SQLite indices used by public-inbox are no exception to that.

       public-inbox 1.6.0+ disables copy-on-write (CoW) on Xapian and SQLite indices on btrfs to
       achieve acceptable performance (even on SSD).  Disabling copy-on-write also disables
       checksumming, thus "raid1" (or higher) configurations may be corrupt after unsafe
       shutdowns.

       Fortunately, these SQLite and Xapian indices are designed to recoverable from git if
       missing.

       Disabling CoW does not prevent all fragmentation.  Large values of
       "publicInbox.indexBatchSize" also limit fragmentation during the initial index.

       Avoid snapshotting subvolumes containing Xapian and/or SQLite indices.  Snapshots use CoW
       despite our efforts to disable it, resulting in fragmentation.

       filefrag(8) can be used to monitor fragmentation, and "btrfs filesystem defragment -fr
       $INBOX_DIR" may be necessary.

       Large filesystems benefit significantly from the "space_cache=v2" mount option documented
       in btrfs(5).

       Older, non-CoW filesystems are generally work well out-of-the-box for our Xapian and
       SQLite indices.

   Performance on solid state drives
       While SSD read performance is generally good, SSD write performance degrades as the drive
       ages and/or gets full.  Issuing "TRIM" commands via fstrim(8) or similar is required to
       sustain write performance.

       Users of the Flash-Friendly File System F2FS <https://en.wikipedia.org/wiki/F2FS> may
       benefit from optimizations found in SQLite 3.21.0+.  Benchmarks are greatly appreciated.

   Read-only daemons
       public-inbox-httpd(1), public-inbox-imapd(1), and public-inbox-nntpd(1) are all designed
       for C10K (or higher) levels of concurrency from a single process.  SMP systems may use
       "--worker-processes=NUM" as documented in public-inbox-daemon(8) for parallelism.

       The open file descriptor limit ("RLIMIT_NOFILE", "ulimit -n" in sh(1), "LimitNOFILE=" in
       systemd.exec(5)) may need to be raised to accommodate many concurrent clients.

       Transport Layer Security (IMAPS, NNTPS, or via STARTTLS) significantly increases memory
       use of client sockets, sure to account for that in capacity planning.

CONTACT

       Feedback encouraged via plain-text mail to <mailto:meta@public-inbox.org>

       Information for *BSDs and non-traditional filesystems especially welcome.

       Our archives are hosted at <https://public-inbox.org/meta/>,
       <http://hjrcffqmbrq6wope.onion/meta/>, and other places

COPYRIGHT

       Copyright 2020 all contributors <mailto:meta@public-inbox.org>

       License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>