diff options
-rw-r--r-- | Documentation/public-inbox-overview.pod | 68 |
1 files changed, 45 insertions, 23 deletions
diff --git a/Documentation/public-inbox-overview.pod b/Documentation/public-inbox-overview.pod index 46060d0c..91d4a88e 100644 --- a/Documentation/public-inbox-overview.pod +++ b/Documentation/public-inbox-overview.pod @@ -4,7 +4,7 @@ public-inbox-overview - an overview of public-inbox =head1 DESCRIPTION -public-inbox consists of many parts which may be used +public-inbox consists of many pieces which may be used independently or in conjunction of each other for: =over 4 @@ -15,11 +15,11 @@ Mirroring existing public-inboxes. =item 2 -Mirroring mailing lists directly. +Mirroring mailing lists. =item 3 -Hosting standalone. +Hosting standalone inboxes. =back @@ -30,35 +30,52 @@ started. Your mirror will remain dependent on the REMOTE_URL you are mirroring and you only need to use two new commands in addition to common L<git(1)> commands. - git clone --mirror REMOTE_URL /path/to/repo.git +Instructions are different depending on whether the inbox +is L<public-inbox-v1-format(5)> or L<public-inbox-v2-format(5)>. +See the "Archives are clonable:" part of the WWW interface +of a given inbox for cloning instructions specific to +that inbox. The instructions are roughly: - # The following should create the necessary entry in - # ~/.public-inbox/config - public-inbox-init NAME /path/to/repo.git MY_URL LIST_ADDRESS + # for v1 inboxes: + git clone --mirror URL INBOX_DIR - # Optional but strongly recommended for hosting HTTP - # (and required for NNTP) - # enable search (requires Search::Xapian and DBD::SQLite) - public-inbox-index /path/to/repo.git + # for v2 inboxes (each epoch needs to be cloned): + git clone --mirror URL/EPOCH INBOX_DIR/git/EPOCH.git - # Periodically update the repo with the following commands - # to update the git repo and index new messages: - cd /path/to/repo.git && git fetch && public-inbox-index + # The following should create the necessary entry in + # ~/.public-inbox/config, use "-V2" only for v2 inboxes: + public-inbox-init [-V2] NAME INBOX_DIR MY_URL LIST_ADDRESS -See L</"Hosting public-inboxes"> below for info on how to expose + # Optional but strongly recommended for hosting HTTP + # (and required for NNTP) + # enable overview (requires DBD::SQLite) and, if Search::Xapian is + # available, search: + public-inbox-index INBOX_DIR + + # Periodically fetch the repo using git-fetch(1) + # for v1 inboxes: + git --git-dir=INBOX_DIR fetch + + # for v2 (in most cases, only the newest epoch needs to be fetched): + git --git-dir=INBOX_DIR/git/EPOCH.git fetch + + # index new messages after fetching: + public-inbox-index INBOX_DIR + +See L</"Serving public-inboxes"> below for info on how to expose your mirror to other readers. -=head2 Mirroring mailing lists directly +=head2 Mirroring mailing lists -Mirroring existing mailing lists may be done by any reader +Mirroring mailing lists may be done by any reader of a mailing list using L<public-inbox-watch(1)>. # This will create a new git repository: - public-inbox-init NAME /path/to/repo.git MY_URL LIST_ADDRESS + public-inbox-init -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS Then, see the L<public-inbox-watch(1)> manual for configuring -C<watch>, C<watchheader>, and the optional C<spamcheck> and -C<watchspam> entries. +C<watch>, C<watchheader>, C<listid> and the optional C<spamcheck> +and C<watchspam> entries. You will need to leave L<public-inbox-watch(1)> running to keep the mailbox up-to-date as messages are delivered to @@ -69,15 +86,20 @@ is recommended. L<public-inbox-watch(1)> will automatically maintain the indices if they were created by L<public-inbox-index(1)> - public-inbox-index /path/to/repo.git + public-inbox-index INBOX_DIR + +Instead of using L<public-inbox-watch(1)>, using +L<public-inbox-mda(1)> with the C<--no-precheck> option and +relying on the C<listid> directive in L<public-inbox-config(5)> +is also an option. -=head2 Hosting standalone +=head2 Hosting standalone inboxes Using L<public-inbox-init(1)> to initialize the inbox as in the other methods is recommended. See L<public-inbox-mda(1)> for more details; but this also requires MTA-specific knowledge. -=head2 Hosting public-inboxes +=head2 Serving public-inboxes Since public-inboxes are git repositories, they may be served to remote clients via L<git-daemon(1)> as well as specialized HTTP |