]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-init.pod
viewvcs: prepopulate search bar with dfpost + dfn
[public-inbox.git] / Documentation / public-inbox-init.pod
1 =head1 NAME
2
3 public-inbox-init - create or reinitialize a public-inbox
4
5 =head1 SYNOPSIS
6
7 B<public-inbox-init> [OPTIONS] NAME INBOX_DIR HTTP_URL ADDRESS [ADDRESS..]
8
9 =head1 DESCRIPTION
10
11 Creates an empty public-inbox or reinitializes an existing one.
12 It updates C<~/.public-inbox/config> by creating a
13 C<[publicinbox "NAME"]> section where
14 C<publicinbox.NAME.inboxdir> is C<INBOX_DIR>,
15 C<publicinbox.NAME.url> is C<HTTP_URL>, and
16 C<publicinbox.NAME.address> is C<ADDRESS>.  Multiple addresses
17 may be specified for inboxes with multiple addresses.
18
19 =head1 OPTIONS
20
21 =over
22
23 =item -V FORMAT_VERSION
24
25 =item --version FORMAT_VERSION
26
27 Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
28 if you have L<DBD::SQLite> installed.
29
30 The default is C<1> for the old L<public-inbox-v1-format(5)>,
31 but C<2> is strongly recommended for scalability if you have
32 L<DBD::SQLite>.
33
34 Default: C<1>
35
36 =item -L <basic|medium|full>
37
38 =item --indexlevel <basic|medium|full>
39
40 Controls the indexing level for L<public-inbox-index(1)>
41
42 See L<public-inbox-config(5)> for more information.
43
44 Default: C<full>
45
46 =item --ng NEWSGROUP
47
48 =item --newsgroup NEWSGROUP
49
50 The NNTP group name for use with L<public-inbox-nntpd(8)>.  This
51 may be any newsgroup name with hierarchies delimited by C<.>.
52 For example, the newsgroup for L<mailto:meta@public-inbox.org>
53 is: C<inbox.comp.mail.public-inbox.meta>
54
55 This may be set after-the-fact via C<publicinbox.$NAME.newsgroup>
56 in the configuration file.  See L<public-inbox-config(5)> for more
57 info.
58
59 Available in public-inbox 1.6.0+.
60
61 Default: none.
62
63 =item -c KEY=VALUE
64
65 Allow setting arbitrary configs as C<publicinbox.$NAME.$KEY>.
66 This is idempotent for the same C<VALUE>, but allows setting
67 multiple values for keys such as C<publicinbox.$NAME.url> and
68 C<publicinbox.$NAME.watch>.
69
70 =item --skip-artnum
71
72 This option allows archivists to publish incomplete archives
73 with only new mail while allowing NNTP article numbers
74 to be reserved for yet-to-be-archived old mail.
75
76 This is mainly intended for users of C<--skip-epoch> (documented below)
77 but may be of use to L<public-inbox-v1-format(5)> users.
78
79 There is no automatic way to use reserved NNTP article numbers
80 when old mail is found, yet.
81
82 Available in public-inbox 1.6.0+.
83
84 Default: unset, no NNTP article numbers are skipped
85
86 =item -S
87
88 =item --skip-epoch
89
90 For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
91 allows archivists to publish incomplete archives with newer
92 mail while allowing "0.git" (or "1.git" and so on) epochs to be
93 added-after-the-fact (without affecting "git clone" followers).
94
95 Available since public-inbox 1.2.0.
96
97 Default: unset, no epochs are skipped
98
99 =item -j JOBS
100
101 =item --jobs=JOBS
102
103 Control the number of Xapian index shards in a
104 C<-V2> (L<public-inbox-v2-format(5)>) inbox.
105
106 It can be useful to use a single shard (C<-j1>) for inboxes on
107 high-latency storage (e.g. rotational HDD) unless the system has
108 enough RAM to cache 5-10x the size of the git repository.
109
110 Another approach for HDDs is to use the
111 L<public-inbox-index(1)/publicInbox.indexSequentialShard> option
112 and many shards, so each shard may fit into the kernel page
113 cache.  Unfortunately, excessive shards slows down read-only
114 query performance.
115
116 For fast storage, it is generally not useful to specify higher
117 values than the default due to the top-level producer process
118 being a bottleneck.
119
120 Default: the number of online CPUs, up to 4 (3 shard workers, 1 producer)
121
122 =item --skip-docdata
123
124 Do not store document data in Xapian, reducing Xapian storage
125 overhead by around 1.5%.
126
127 Warning: this option prevents rollbacks to public-inbox 1.5.0
128 and earlier.
129
130 Available in public-inbox 1.6.0+.
131
132 =back
133
134 =head1 ENVIRONMENT
135
136 =over 8
137
138 =item PI_CONFIG
139
140 Used to override the default C<~/.public-inbox/config> value.
141
142 =back
143
144 =head1 LIMITATIONS
145
146 Some of the options documented in L<public-inbox-config(5)>
147 require editing the config file.  Old versions lack the
148 C<--ng>/C<--newsgroup> parameter
149
150 See L<public-inbox-config(5)> for all the options which may be applied
151 to a given inbox.
152
153 =head1 CONTACT
154
155 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
156
157 The mail archives are hosted at L<https://public-inbox.org/meta/> and
158 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
159
160 =head1 COPYRIGHT
161
162 Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org>
163
164 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
165
166 =head1 SEE ALSO
167
168 L<git-init(1)>, L<git-config(1)>, L<public-inbox-v1-format(5)>,
169 L<public-inbox-v2-format(5)>