Documentation/public-inbox-overview.pod

   1 =head1 NAME
   2
   3 public-inbox-overview - an overview of public-inbox
   4
   5 =head1 DESCRIPTION
   6
   7 public-inbox consists of many pieces which may be used
   8 independently or in conjunction of each other for:
   9
  10 =over 4
  11
  12 =item 1
  13
  14 Mirroring existing public-inboxes.
  15
  16 =item 2
  17
  18 Mirroring mailing lists.
  19
  20 =item 3
  21
  22 Hosting standalone inboxes.
  23
  24 =back
  25
  26 =head2 Mirroring existing public-inboxes
  27
  28 Mirroring existing public-inboxes is the easiest way to get
  29 started.  Your mirror will remain dependent on the REMOTE_URL
  30 you are mirroring and you only need to use two new commands in
  31 addition to common L<git(1)> commands.
  32
  33 Instructions are different depending on whether the inbox
  34 is L<public-inbox-v1-format(5)> or L<public-inbox-v2-format(5)>.
  35 See the "Archives are clonable:" part of the WWW interface
  36 of a given inbox for cloning instructions specific to
  37 that inbox.  The instructions are roughly:
  38
  39   # for v1 inboxes:
  40   git clone --mirror URL INBOX_DIR
  41
  42   # for v2 inboxes (each epoch needs to be cloned):
  43   git clone --mirror URL/EPOCH INBOX_DIR/git/EPOCH.git
  44
  45   # The following should create the necessary entry in
  46   # ~/.public-inbox/config, use "-V2" only for v2 inboxes:
  47   public-inbox-init [-V2] NAME INBOX_DIR MY_URL LIST_ADDRESS
  48
  49   # Optional but strongly recommended for hosting HTTP
  50   # (and required for NNTP)
  51   # enable overview (requires DBD::SQLite) and, if Search::Xapian is
  52   # available, search:
  53   public-inbox-index INBOX_DIR
  54
  55   # Periodically fetch the repo using git-fetch(1)
  56   # for v1 inboxes:
  57   git --git-dir=INBOX_DIR fetch
  58
  59   # for v2 (in most cases, only the newest epoch needs to be fetched):
  60   git --git-dir=INBOX_DIR/git/EPOCH.git fetch
  61
  62   # index new messages after fetching:
  63   public-inbox-index INBOX_DIR
  64
  65 See L</"Serving public-inboxes"> below for info on how to expose
  66 your mirror to other readers.
  67
  68 =head2 Mirroring mailing lists
  69
  70 Mirroring mailing lists may be done by any reader
  71 of a mailing list using L<public-inbox-watch(1)>.
  72
  73         # This will create a new git repository:
  74         public-inbox-init -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS
  75
  76 Then, see the L<public-inbox-watch(1)> manual for configuring
  77 C<watch>, C<watchheader>, C<listid> and the optional C<spamcheck>
  78 and C<watchspam> entries.
  79
  80 You will need to leave L<public-inbox-watch(1)> running to
  81 keep the mailbox up-to-date as messages are delivered to
  82 the mailing list.
  83
  84 Running L<public-inbox-index(1)> to create search indices
  85 is recommended.  L<public-inbox-watch(1)> will automatically
  86 maintain the indices if they were created by
  87 L<public-inbox-index(1)>
  88
  89         public-inbox-index INBOX_DIR
  90
  91 Instead of using L<public-inbox-watch(1)>, using
  92 L<public-inbox-mda(1)> with the C<--no-precheck> option and
  93 relying on the C<listid> directive in L<public-inbox-config(5)>
  94 is also an option.
  95
  96 =head2 Hosting standalone inboxes
  97
  98 Using L<public-inbox-init(1)> to initialize the inbox as in the
  99 other methods is recommended.  See L<public-inbox-mda(1)> for
 100 more details; but this also requires MTA-specific knowledge.
 101
 102 =head2 Serving public-inboxes
 103
 104 Since public-inboxes are git repositories, they may be served to
 105 remote clients via L<git-daemon(1)> as well as specialized HTTP
 106 and NNTP daemons distributed with public-inbox.
 107
 108 See L<public-inbox-httpd(1)> and L<public-inbox-nntpd(1)>
 109 for more information on using these daemons.
 110
 111 Hosting a public-inbox over HTTP or NNTP will never require
 112 write access to any files in the git repository, including
 113 the search indices or article number map database.
 114
 115 Users familiar with PSGI and L<Plack> may also use
 116 L<PublicInbox::WWW> with the preferred server instead of
 117 L<public-inbox-httpd(1)>
 118
 119 =head1 CONTACT
 120
 121 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 122
 123 The mail archives are hosted at L<https://public-inbox.org/meta/>
 124 and L<http://hjrcffqmbrq6wope.onion/meta/>
 125
 126 =head1 COPYRIGHT
 127
 128 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 129
 130 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>