3 public-inbox-overview - an overview of public-inbox
7 public-inbox consists of many pieces which may be used
8 independently or in conjunction of each other for:
14 Mirroring existing public-inboxes.
18 Mirroring mailing lists.
22 Hosting standalone inboxes.
26 =head2 Mirroring existing public-inboxes
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.
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:
40 git clone --mirror URL INBOX_DIR
42 # for v2 inboxes (each epoch needs to be cloned):
43 git clone --mirror URL/EPOCH INBOX_DIR/git/EPOCH.git
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
49 # Optional but strongly recommended for hosting HTTP
50 # (and required for NNTP)
51 # enable overview (requires DBD::SQLite) and, if Search::Xapian is
53 public-inbox-index INBOX_DIR
55 # Periodically fetch the repo using git-fetch(1)
57 git --git-dir=INBOX_DIR fetch
59 # for v2 (in most cases, only the newest epoch needs to be fetched):
60 git --git-dir=INBOX_DIR/git/EPOCH.git fetch
62 # index new messages after fetching:
63 public-inbox-index INBOX_DIR
65 See L</"Serving public-inboxes"> below for info on how to expose
66 your mirror to other readers.
68 =head2 Mirroring mailing lists
70 Mirroring mailing lists may be done by any reader
71 of a mailing list using L<public-inbox-watch(1)>.
73 # This will create a new git repository:
74 public-inbox-init -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS
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.
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
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)>
89 public-inbox-index INBOX_DIR
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)>
96 =head2 Hosting standalone inboxes
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.
102 =head2 Serving public-inboxes
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.
108 See L<public-inbox-httpd(1)> and L<public-inbox-nntpd(1)>
109 for more information on using these daemons.
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.
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)>
121 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
123 The mail archives are hosted at L<https://public-inbox.org/meta/>
124 and L<http://hjrcffqmbrq6wope.onion/meta/>
128 Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>
130 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>