Documentation/public-inbox-index.pod

   1 =head1 NAME
   2
   3 public-inbox-index - create and update search indices
   4
   5 =head1 SYNOPSIS
   6
   7 public-inbox-index [OPTIONS] INBOX_DIR...
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-index creates and updates the search, overview and
  12 NNTP article number database used by the read-only public-inbox
  13 HTTP and NNTP interfaces.  Currently, this requires
  14 L<DBD::SQLite> and L<DBI> Perl modules.  L<Search::Xapian>
  15 is optional, only to support the PSGI search interface.
  16
  17 Once the initial indices are created by public-inbox-index,
  18 L<public-inbox-mda(1)> and L<public-inbox-watch(1)> will
  19 automatically maintain them.
  20
  21 Running this manually to update indices is only required if
  22 relying on L<git-fetch(1)> to mirror an existing public-inbox;
  23 or if upgrading to a new version of public-inbox using
  24 the C<--reindex> option.
  25
  26 Having the overview and article number database is essential to
  27 running the NNTP interface, and strongly recommended for the
  28 HTTP interface as it provides thread grouping in addition to
  29 normal search functionality.
  30
  31 =head1 OPTIONS
  32
  33 =over
  34
  35 =item --compact / -c
  36
  37 Compacts the Xapian DBs after indexing.  This is recommended
  38 when using C<--reindex> to avoid running out of disk space
  39 while indexing multiple inboxes.
  40
  41 While option takes a negligible amount of time compared to
  42 C<--reindex>, it requires temporarily duplicating the entire
  43 contents of the Xapian DB.
  44
  45 This switch may be specified twice, in which case compaction
  46 happens both before and after indexing to minimize the temporal
  47 footprint of the (re)indexing operation.
  48
  49 =item --reindex
  50
  51 Forces a re-index of all messages in the inbox.
  52 This can be used for in-place upgrades and bugfixes while
  53 NNTP/HTTP server processes are utilizing the index.  Keep in
  54 mind this roughly doubles the size of the already-large
  55 Xapian database.  Using this with C<--compact> or running
  56 L<public-inbox-compact(1)> afterwards is recommended to
  57 release free space.
  58
  59 This does not touch the NNTP article number database or
  60 affect threading.
  61
  62 =item --prune
  63
  64 Run L<git-gc(1)> to prune and expire reflogs if discontiguous history
  65 is detected.  This is intended to be used in mirrors after running
  66 L<public-inbox-edit(1)> or L<public-inbox-purge(1)> to ensure data
  67 is expunged from mirrors.
  68
  69 =item --max-size SIZE
  70
  71 Sets or overrides L</publicinbox.indexMaxSize> on a
  72 per-invocation basis.  See L</publicinbox.indexMaxSize>
  73 below.
  74
  75 =back
  76
  77 =head1 FILES
  78
  79 For v1 (ssoma) repositories described in L<public-inbox-v1-format>.
  80 All public-inbox-specific files are contained within the
  81 C<$GIT_DIR/public-inbox/> directory.
  82
  83 v2 inboxes are described in L<public-inbox-v2-format>.
  84
  85 =head1 CONFIGURATION
  86
  87 =over 8
  88
  89 =item publicinbox.indexMaxSize
  90
  91 Prevents indexing of messages larger than the specified size
  92 value.  A single suffix modifier of C<k>, C<m> or C<g> is
  93 supported, thus the value of C<1m> to prevents indexing of
  94 messages larger than one megabyte.
  95
  96 This is useful for avoiding memory exhaustion in mirrors.
  97
  98 Default: none
  99
 100 =back
 101
 102 =head1 ENVIRONMENT
 103
 104 =over 8
 105
 106 =item PI_CONFIG
 107
 108 Used to override the default "~/.public-inbox/config" value.
 109
 110 =item XAPIAN_FLUSH_THRESHOLD
 111
 112 The number of documents to update before committing changes to
 113 disk.  This environment is handled directly by Xapian, refer to
 114 Xapian API documentation for more details.
 115
 116 Default: our indexing code flushes every megabyte of mail seen
 117 to keep memory usage low.  Setting this environment variable to
 118 any positive value will switch to a document count-based
 119 threshold in Xapian.
 120
 121 =back
 122
 123 =head1 UPGRADING
 124
 125 Occasionally, public-inbox will update it's schema version and
 126 require a full index by running this command.
 127
 128 =head1 CONTACT
 129
 130 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 131
 132 The mail archives are hosted at L<https://public-inbox.org/meta/>
 133 and L<http://hjrcffqmbrq6wope.onion/meta/>
 134
 135 =head1 COPYRIGHT
 136
 137 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 138
 139 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 140
 141 =head1 SEE ALSO
 142
 143 L<Search::Xapian>, L<DBD::SQLite>