public-inbox-init - Man Page

create or reinitialize a public-inbox

Synopsis

public-inbox-init [Options] NAME INBOX_DIR HTTP_URL ADDRESS [ADDRESS..]

Description

Creates an empty public-inbox or reinitializes an existing one. It updates ~/.public-inbox/config by creating a [publicinbox "NAME"] section where publicinbox.NAME.inboxdir is INBOX_DIR, publicinbox.NAME.url is HTTP_URL, and publicinbox.NAME.address is ADDRESS.  Multiple addresses may be specified for inboxes with multiple addresses.

Options

-V FORMAT_VERSION
--version FORMAT_VERSION

Specify 2 here to use the scalable public-inbox-v2-format(5) if you have DBD::SQLite installed.

The default is 1 for the old public-inbox-v1-format(5), but 2 is strongly recommended for scalability if you have DBD::SQLite.

Default: 1

-L <basic|medium|full>
--indexlevel <basic|medium|full>

Controls the indexing level for public-inbox-index(1)

See public-inbox-config(5) for more information.

Default: full

--ng NEWSGROUP
--newsgroup NEWSGROUP

The NNTP group name for use with public-inbox-nntpd(8).  This may be any newsgroup name with hierarchies delimited by .. For example, the newsgroup for <mailto:meta@public-inbox.org> is: inbox.comp.mail.public-inbox.meta

This may be set after-the-fact via publicinbox.$NAME.newsgroup in the configuration file.  See public-inbox-config(5) for more info.

Available in public-inbox 1.6.0+.

Default: none.

-c KEY=VALUE

Allow setting arbitrary configs as publicinbox.$NAME.$KEY. This is idempotent for the same VALUE, but allows setting multiple values for keys such as publicinbox.$NAME.url and publicinbox.$NAME.watch.

--skip-artnum

This option allows archivists to publish incomplete archives with only new mail while allowing NNTP article numbers to be reserved for yet-to-be-archived old mail.

This is mainly intended for users of --skip-epoch (documented below) but may be of use to public-inbox-v1-format(5) users.

There is no automatic way to use reserved NNTP article numbers when old mail is found, yet.

Available in public-inbox 1.6.0+.

Default: unset, no NNTP article numbers are skipped

-S
--skip-epoch

For -V2 (public-inbox-v2-format(5)) inboxes only, this option allows archivists to publish incomplete archives with newer mail while allowing “0.git” (or “1.git” and so on) epochs to be added-after-the-fact (without affecting “git clone” followers).

Available since public-inbox 1.2.0.

Default: unset, no epochs are skipped

-j JOBS
--jobs=JOBS

Control the number of Xapian index shards in a -V2 (public-inbox-v2-format(5)) inbox.

It can be useful to use a single shard (-j1) for inboxes on high-latency storage (e.g. rotational HDD) unless the system has enough RAM to cache 5-10x the size of the git repository.

Another approach for HDDs is to use the “publicInbox.indexSequentialShard” in public-inbox-index(1) option and many shards, so each shard may fit into the kernel page cache.  Unfortunately, excessive shards slows down read-only query performance.

For fast storage, it is generally not useful to specify higher values than the default due to the top-level producer process being a bottleneck.

Default: the number of online CPUs, up to 4 (3 shard workers, 1 producer)

--skip-docdata

Do not store document data in Xapian, reducing Xapian storage overhead by around 1.5%.

Warning: this option prevents rollbacks to public-inbox 1.5.0 and earlier.

Available in public-inbox 1.6.0+.

Environment

PI_CONFIG

Used to override the default ~/.public-inbox/config value.

Limitations

Some of the options documented in public-inbox-config(5) require editing the config file.  Old versions lack the --ng/--newsgroup parameter

See public-inbox-config(5) for all the options which may be applied to a given inbox.

Contact

Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>

The mail archives are hosted at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

See Also

git-init(1), git-config(1), public-inbox-v1-format(5), public-inbox-v2-format(5)

Referenced By

lei-add-external(1), public-inbox-clone(1), public-inbox-convert(1), public-inbox-index(1), public-inbox-overview(7).

1993-10-02 public-inbox.git public-inbox user manual