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