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 --reindex
  36
  37 Forces a search engine re-index of all messages in the
  38 repository.  This can be used for in-place upgrades while
  39 NNTP/HTTP server processes are utilizing the index.  Keep in
  40 mind this roughly doubles the size of the already-large
  41 Xapian database.
  42
  43 This does not touch the NNTP article number database.
  44
  45 =item --prune
  46
  47 Run L<git-gc(1)> to prune and expire reflogs if discontiguous history
  48 is detected.  This is intended to be used in mirrors after running
  49 L<public-inbox-edit(1)> or L<public-inbox-purge(1)> to ensure data
  50 is expunged from mirrors.
  51
  52 =back
  53
  54 =head1 FILES
  55
  56 For v1 (ssoma) repositories described in L<public-inbox-v1-format>.
  57 All public-inbox-specific files are contained within the
  58 C<$GIT_DIR/public-inbox/> directory.
  59
  60 v2 repositories are described in L<public-inbox-v2-format>.
  61
  62 =back
  63
  64 =head1 ENVIRONMENT
  65
  66 =over 8
  67
  68 =item PI_CONFIG
  69
  70 Used to override the default "~/.public-inbox/config" value.
  71
  72 =item XAPIAN_FLUSH_THRESHOLD
  73
  74 The number of documents to update before committing changes to
  75 disk.  This environment is handled directly by Xapian, refer to
  76 Xapian API documentation for more details.
  77
  78 Default: our indexing code flushes every megabyte of mail seen
  79 to keep memory usage low.  Setting this environment variable to
  80 any positive value will switch to a document count-based
  81 threshold in Xapian.
  82
  83 =back
  84
  85 =head1 UPGRADING
  86
  87 Occasionally, public-inbox will update it's schema version and
  88 require a full index by running this command.
  89
  90 =head1 CONTACT
  91
  92 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
  93
  94 The mail archives are hosted at L<https://public-inbox.org/meta/>
  95 and L<http://hjrcffqmbrq6wope.onion/meta/>
  96
  97 =head1 COPYRIGHT
  98
  99 Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
 100
 101 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 102
 103 =head1 SEE ALSO
 104
 105 L<Search::Xapian>, L<DBD::SQLite>