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 Available since public-inbox 1.4.0.
  50
  51 =item --reindex
  52
  53 Forces a re-index of all messages in the inbox.
  54 This can be used for in-place upgrades and bugfixes while
  55 NNTP/HTTP server processes are utilizing the index.  Keep in
  56 mind this roughly doubles the size of the already-large
  57 Xapian database.  Using this with C<--compact> or running
  58 L<public-inbox-compact(1)> afterwards is recommended to
  59 release free space.
  60
  61 public-inbox protects writes to various indices with L<flock(2)>,
  62 so it is safe to reindex while L<public-inbox-watch(1)>,
  63 L<public-inbox-mda(1)> or L<public-inbox-learn(1)> run.
  64
  65 This does not touch the NNTP article number database or
  66 affect threading.
  67
  68 =item --prune
  69
  70 Run L<git-gc(1)> to prune and expire reflogs if discontiguous history
  71 is detected.  This is intended to be used in mirrors after running
  72 L<public-inbox-edit(1)> or L<public-inbox-purge(1)> to ensure data
  73 is expunged from mirrors.
  74
  75 Available since public-inbox 1.2.0.
  76
  77 =item --max-size SIZE
  78
  79 Sets or overrides L</publicinbox.indexMaxSize> on a
  80 per-invocation basis.  See L</publicinbox.indexMaxSize>
  81 below.
  82
  83 Available since public-inbox 1.5.0.
  84
  85 =item --batch-size SIZE
  86
  87 Sets or overrides L</publicinbox.indexBatchSize> on a
  88 per-invocation basis.  See L</publicinbox.indexBatchSize>
  89 below.
  90
  91 Available in public-inbox 1.6.0 (PENDING).
  92
  93 =back
  94
  95 =head1 FILES
  96
  97 For v1 (ssoma) repositories described in L<public-inbox-v1-format>.
  98 All public-inbox-specific files are contained within the
  99 C<$GIT_DIR/public-inbox/> directory.
 100
 101 v2 inboxes are described in L<public-inbox-v2-format>.
 102
 103 =head1 CONFIGURATION
 104
 105 =over 8
 106
 107 =item publicinbox.indexMaxSize
 108
 109 Prevents indexing of messages larger than the specified size
 110 value.  A single suffix modifier of C<k>, C<m> or C<g> is
 111 supported, thus the value of C<1m> to prevents indexing of
 112 messages larger than one megabyte.
 113
 114 This is useful for avoiding memory exhaustion in mirrors.
 115 This option is only available in public-inbox 1.5 or later.
 116
 117 Default: none
 118
 119 =item publicinbox.indexBatchSize
 120
 121 Flushes changes to the filesystem and releases locks after
 122 indexing the given number of bytes.  The default value of C<1m>
 123 (one megabyte) is low to minimize memory use and reduce
 124 contention with parallel invocations of L<public-inbox-mda(1)>,
 125 L<public-inbox-learn(1)>, and L<public-inbox-watch(1)>.
 126
 127 Increase this value on powerful systems to improve throughput at
 128 the expense of memory use.  The reduction of lock granularity
 129 may not be noticeable on fast systems.
 130
 131 This option is available in public-inbox 1.6 or later.
 132 public-inbox 1.5 and earlier used the current default, C<1m>.
 133
 134 For L<public-inbox-v2-format(5)> inboxes, this value is
 135 multiplied by the number of Xapian shards.  Thus a typical v2
 136 inbox with 3 shards will flush every 3 megabytes by default.
 137
 138 Default: 1m (one megabyte)
 139
 140 =back
 141
 142 =head1 ENVIRONMENT
 143
 144 =over 8
 145
 146 =item PI_CONFIG
 147
 148 Used to override the default "~/.public-inbox/config" value.
 149
 150 =item XAPIAN_FLUSH_THRESHOLD
 151
 152 The number of documents to update before committing changes to
 153 disk.  This environment is handled directly by Xapian, refer to
 154 Xapian API documentation for more details.
 155
 156 For public-inbox 1.6 and later, use C<publicinbox.indexBatchSize>
 157 instead.  Setting C<XAPIAN_FLUSH_THRESHOLD> for a large C<--reindex>
 158 may cause L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
 159 L<public-inbox-watch(1)> tasks to wait long periods of time
 160 during C<--reindex>.
 161
 162 Default: none, uses C<publicinbox.indexBatchSize>
 163
 164 =back
 165
 166 =head1 UPGRADING
 167
 168 Occasionally, public-inbox will update it's schema version and
 169 require a full index by running this command.
 170
 171 =head1 CONTACT
 172
 173 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 174
 175 The mail archives are hosted at L<https://public-inbox.org/meta/>
 176 and L<http://hjrcffqmbrq6wope.onion/meta/>
 177
 178 =head1 COPYRIGHT
 179
 180 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 181
 182 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 183
 184 =head1 SEE ALSO
 185
 186 L<Search::Xapian>, L<DBD::SQLite>