]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-overview.pod
v2writable: use msgmap as multi_mid queue
[public-inbox.git] / 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-2019 all contributors L<mailto:meta@public-inbox.org>
129
130 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>