about summary refs log tree commit homepage
path: root/Documentation/public-inbox-overview.pod
blob: 91d4a88e2eab8a0f98da9cb65f13183a724aa918 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
=head1 NAME

public-inbox-overview - an overview of public-inbox

=head1 DESCRIPTION

public-inbox consists of many pieces which may be used
independently or in conjunction of each other for:

=over 4

=item 1

Mirroring existing public-inboxes.

=item 2

Mirroring mailing lists.

=item 3

Hosting standalone inboxes.

=back

=head2 Mirroring existing public-inboxes

Mirroring existing public-inboxes is the easiest way to get
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.

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:

  # for v1 inboxes:
  git clone --mirror URL INBOX_DIR

  # for v2 inboxes (each epoch needs to be cloned):
  git clone --mirror URL/EPOCH INBOX_DIR/git/EPOCH.git

  # 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

  # 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

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 -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS

Then, see the L<public-inbox-watch(1)> manual for configuring
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
the mailing list.

Running L<public-inbox-index(1)> to create search indices
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 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 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 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
and NNTP daemons distributed with public-inbox.

See L<public-inbox-httpd(1)> and L<public-inbox-nntpd(1)>
for more information on using these daemons.

Hosting a public-inbox over HTTP or NNTP will never require
write access to any files in the git repository, including
the search indices or article number map database.

Users familiar with PSGI and L<Plack> may also use
L<PublicInbox::WWW> with the preferred server instead of
L<public-inbox-httpd(1)>

=head1 CONTACT

Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>

The mail archives are hosted at L<https://public-inbox.org/meta/>
and L<http://hjrcffqmbrq6wope.onion/meta/>

=head1 COPYRIGHT

Copyright 2016-2019 all contributors L<mailto:meta@public-inbox.org>

License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>