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 parts 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 directly.
  19
  20 =item 3
  21
  22 Hosting standalone.
  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         git clone --mirror REMOTE_URL /path/to/repo.git
  34
  35         # The following should create the necessary entry in
  36         # ~/.public-inbox/config
  37         public-inbox-init NAME /path/to/repo.git MY_URL LIST_ADDRESS
  38
  39         # Optional but strongly recommended for hosting HTTP
  40         # (and required for NNTP)
  41         # enable search (requires Search::Xapian and DBD::SQLite)
  42         public-inbox-index /path/to/repo.git
  43
  44         # Periodically update the repo with the following commands
  45         # to update the git repo and index new messages:
  46         cd /path/to/repo.git && git fetch && public-inbox-index
  47
  48 See L</"Hosting public-inboxes"> below for info on how to expose
  49 your mirror to other readers.
  50
  51 =head2 Mirroring mailing lists directly
  52
  53 Mirroring existing mailing lists may be done by any reader
  54 of a mailing list using L<public-inbox-watch(1)>.
  55
  56         # This will create a new git repository:
  57         public-inbox-init NAME /path/to/repo.git MY_URL LIST_ADDRESS
  58
  59 Then, see the L<public-inbox-watch(1)> manual for configuring
  60 C<watch>, C<watchheader>, and the optional C<spamcheck> and
  61 C<watchspam> entries.
  62
  63 You will need to leave L<public-inbox-watch(1)> running to
  64 keep the mailbox up-to-date as messages are delivered to
  65 the mailing list.
  66
  67 Running L<public-inbox-index(1)> to create search indices
  68 is recommended.  L<public-inbox-watch(1)> will automatically
  69 maintain the indices if they were created by
  70 L<public-inbox-index(1)>
  71
  72         public-inbox-index /path/to/repo.git
  73
  74 =head2 Hosting standalone
  75
  76 Using L<public-inbox-init(1)> to initialize the inbox as in the
  77 other methods is recommended.  See L<public-inbox-mda(1)> for
  78 more details; but this also requires MTA-specific knowledge.
  79
  80 =head2 Hosting public-inboxes
  81
  82 Since public-inboxes are git repositories, they may be served to
  83 remote clients via L<git-daemon(1)> as well as specialized HTTP
  84 and NNTP daemons distributed with public-inbox.
  85
  86 See L<public-inbox-httpd(1)> and L<public-inbox-nntpd(1)>
  87 for more information on using these daemons.
  88
  89 Hosting a public-inbox over HTTP or NNTP will never require
  90 write access to any files in the git repository, including
  91 the search indices or article number map database.
  92
  93 Users familiar with PSGI and L<Plack> may also use
  94 L<PublicInbox::WWW> with the preferred server instead of
  95 L<public-inbox-httpd(1)>
  96
  97 =head1 CONTACT
  98
  99 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 100
 101 The mail archives are hosted at L<https://public-inbox.org/meta/>
 102 and L<http://hjrcffqmbrq6wope.onion/meta/>
 103
 104 =head1 COPYRIGHT
 105
 106 Copyright 2016-2018 all contributors L<mailto:meta@public-inbox.org>
 107
 108 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>