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 GIT_DIR
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-index creates and updates the search and NNTP
  12 article number database used by the read-only public-inbox HTTP
  13 and NNTP interfaces.  Currently, this requires L<Search::Xapian>
  14 and L<DBD::SQlite> and L<DBI> Perl modules.
  15
  16 Once the initial indices are created by public-inbox-index,
  17 L<public-inbox-mda(1)> and L<public-inbox-watch(1)> will
  18 automatically maintain them.
  19
  20 Running this manually to update indices is only required if
  21 relying on L<git-fetch(1)> to mirror an existing public-inbox.
  22
  23 Having a search and article number database is essential to
  24 running the NNTP interface, and strongly recommended for the
  25 HTTP interface as it provides thread grouping in addition
  26 to normal search functionality.
  27
  28 =head1 FILES
  29
  30 All public-inbox-specific files are contained within the
  31 C<$GIT_DIR/public-inbox/> directory.  All files are expected to
  32 grow in size as more messages are archived, so using compaction
  33 commands (e.g. L<xapian-compact(1)>) is not recommended unless
  34 the list is no longer active.
  35
  36 =item $GIT_DIR/public-inbox/msgmap.sqlite3
  37
  38 The stable NNTP article number to Message-ID mapping is
  39 stored in an SQLite3 database.
  40
  41 This is required for users of L<public-inbox-nntpd(1)>, but
  42 users of the L<PublicInbox::WWW> interface will find it
  43 useful for attempting recovery from copy-paste truncations of
  44 URLs containing long Message-IDs.
  45
  46 Avoid removing this file and regenerating it; it may cause
  47 existing NNTP readers to lose sync and miss (or duplicate)
  48 messages.
  49
  50 This file is relatively small, and typically less than 5%
  51 of the space of the mail stored in a packed git repository.
  52
  53 =item $GIT_DIR/public-inbox/xapian*
  54
  55 The database used by L<Search::Xapian>.  This directory name is
  56 followed by a number indicating the index schema version this
  57 installation of public-inbox uses.
  58
  59 These directories may be safely deleted or removed in full
  60 while the NNTP and HTTP interfaces are no longer accessing
  61 them.
  62
  63 In addition to providing a search interface for the HTTP
  64 interface, the Xapian database is used to group and combine
  65 related messages into threads.  For NNTP servers, it also
  66 provides a cache of metadata and header information often
  67 requested by NNTP clients.
  68
  69 This directory is large, often two to three times the size of
  70 the objects stored in a packed git repository.
  71
  72 =head1 ENVIRONMENT
  73
  74 =over 8
  75
  76 =item PI_CONFIG
  77
  78 Used to override the default "~/.public-inbox/config" value.
  79
  80 =back
  81
  82 =head1 CONTACT
  83
  84 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
  85
  86 The mail archives are hosted at L<https://public-inbox.org/meta/>
  87 and L<http://hjrcffqmbrq6wope.onion/meta/>
  88
  89 =head1 COPYRIGHT
  90
  91 Copyright 2016 all contributors L<mailto:meta@public-inbox.org>
  92
  93 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
  94
  95 =head1 SEE ALSO
  96
  97 L<Search::Xapian>, L<DBD::SQLite>