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 --skip-artnum
  64
  65 This option allows archivists to publish incomplete archives
  66 with only new mail while allowing NNTP article numbers
  67 to be reserved for yet-to-be-archived old mail.
  68
  69 This is mainly intended for users of C<--skip-epoch> (documented below)
  70 but may be of use to L<public-inbox-v1-format(5)> users.
  71
  72 There is no automatic way to use reserved NNTP article numbers
  73 when old mail is found, yet.
  74
  75 Available in public-inbox 1.6.0+.
  76
  77 Default: unset, no NNTP article numbers are skipped
  78
  79 =item -S
  80
  81 =item --skip-epoch
  82
  83 For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
  84 allows archivists to publish incomplete archives with newer
  85 mail while allowing "0.git" (or "1.git" and so on) epochs to be
  86 added-after-the-fact (without affecting "git clone" followers).
  87
  88 Available since public-inbox 1.2.0.
  89
  90 Default: unset, no epochs are skipped
  91
  92 =item -j JOBS
  93
  94 =item --jobs=JOBS
  95
  96 Control the number of Xapian index shards in a
  97 C<-V2> (L<public-inbox-v2-format(5)>) inbox.
  98
  99 It can be useful to use a single shard (C<-j1>) for inboxes on
 100 high-latency storage (e.g. rotational HDD) unless the system has
 101 enough RAM to cache 5-10x the size of the git repository.
 102
 103 Another approach for HDDs is to use the
 104 L<public-inbox-index(1)/publicInbox.indexSequentialShard> option
 105 and many shards, so each shard may fit into the kernel page
 106 cache.  Unfortunately, excessive shards slows down read-only
 107 query performance.
 108
 109 For fast storage, it is generally not useful to specify higher
 110 values than the default due to the top-level producer process
 111 being a bottleneck.
 112
 113 Default: the number of online CPUs, up to 4 (3 shard workers, 1 producer)
 114
 115 =item --skip-docdata
 116
 117 Do not store document data in Xapian, reducing Xapian storage
 118 overhead by around 1.5%.
 119
 120 Warning: this option prevents rollbacks to public-inbox 1.5.0
 121 and earlier.
 122
 123 Available in public-inbox 1.6.0+.
 124
 125 =back
 126
 127 =head1 ENVIRONMENT
 128
 129 =over 8
 130
 131 =item PI_CONFIG
 132
 133 Used to override the default C<~/.public-inbox/config> value.
 134
 135 =back
 136
 137 =head1 LIMITATIONS
 138
 139 Some of the options documented in L<public-inbox-config(5)>
 140 require editing the config file.  Old versions lack the
 141 C<--ng>/C<--newsgroup> parameter
 142
 143 See L<public-inbox-config(5)> for all the options which may be applied
 144 to a given inbox.
 145
 146 =head1 CONTACT
 147
 148 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 149
 150 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 151 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 152
 153 =head1 COPYRIGHT
 154
 155 Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org>
 156
 157 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 158
 159 =head1 SEE ALSO
 160
 161 L<git-init(1)>, L<git-config(1)>, L<public-inbox-v1-format(5)>,
 162 L<public-inbox-v2-format(5)>