Documentation/public-inbox-extindex.pod

   1 =head1 NAME
   2
   3 public-inbox-extindex - create and update external search indices
   4
   5 =head1 SYNOPSIS
   6
   7 public-inbox-extindex [OPTIONS] EXTINDEX_DIR INBOX_DIR...
   8
   9 public-inbox-extindex [OPTIONS] [EXTINDEX_DIR] --all
  10
  11 =head1 DESCRIPTION
  12
  13 FIXME: behavior not finalized  It should probably write to the
  14 config file the first time --all is used.
  15
  16 public-inbox-extindex creates and updates an external search and
  17 overview database used by the read-only public-inbox PSGI (HTTP),
  18 NNTP, and IMAP interfaces.  This requires either the
  19 L<Search::Xapian> XS bindings OR the L<Xapian> SWIG bindings,
  20 along with L<DBD::SQLite> and L<DBI> Perl modules.
  21
  22 =head1 OPTIONS
  23
  24 =over
  25
  26 =item -j JOBS
  27
  28 =item --jobs=JOBS
  29
  30 ... TODO, see L<public-inbox-index(5)>
  31
  32 =item --all
  33
  34 Index all C<publicinbox> entries in C<PI_CONFIG>.
  35
  36 C<publicinbox> entries indexed by C<public-inbox-extindex> can
  37 have full Xapian searching abilities with the per-C<publicinbox>
  38 C<indexlevel> set to C<basic> and their respective Xapian
  39 (C<xap15> or C<xapian15>) directories removed.  For multiple
  40 public-inboxes where cross-posting is common, this allows
  41 significant space savings on Xapian indices.
  42
  43 =item --gc
  44
  45 Perform garbage collection instead of indexing.  Use this if
  46 inboxes are removed from the extindex, or if messages are
  47 purged or removed from some inboxes.
  48
  49 =item --reindex
  50
  51 Forces a re-index of all messages in the extindex.  This can be
  52 used for in-place upgrades and bugfixes while read-only server
  53 processes are utilizing the index.  Keep in mind this roughly
  54 doubles the size of the already-large Xapian database.
  55
  56 The extindex locks will be released roughly every 10s to
  57 allow L<public-inbox-mda(1)> and L<public-inbox-watch(1)>
  58 processes to write to the extindex.
  59
  60 =item --fast
  61
  62 Used with C<--reindex>, it will only look for new and stale
  63 entries and not touch already-indexed messages.
  64
  65 =back
  66
  67 =head1 FILES
  68
  69 L<public-inbox-extindex-format(5)>
  70
  71 =head1 CONFIGURATION
  72
  73 ... TODO, see L<public-inbox-index(5)>
  74
  75 =head1 ENVIRONMENT
  76
  77 =over 8
  78
  79 =item PI_CONFIG
  80
  81 Used to override the default "~/.public-inbox/config" value.
  82
  83 =item XAPIAN_FLUSH_THRESHOLD
  84
  85 The number of documents to update before committing changes to
  86 disk.  This environment is handled directly by Xapian, refer to
  87 Xapian API documentation for more details.
  88
  89 Setting C<XAPIAN_FLUSH_THRESHOLD> or
  90 C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
  91 L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
  92 L<public-inbox-watch(1)> tasks to wait long and unpredictable
  93 periods of time during C<--reindex>.
  94
  95 Default: none, uses C<publicinbox.indexBatchSize>
  96
  97 =back
  98
  99 =head1 UPGRADING
 100
 101 Occasionally, public-inbox will update it's schema version and
 102 require a full index by running this command.
 103
 104 =head1 CONTACT
 105
 106 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 107
 108 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 109 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 110
 111 =head1 COPYRIGHT
 112
 113 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 114
 115 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 116
 117 =head1 SEE ALSO
 118
 119 L<Search::Xapian>, L<DBD::SQLite>