]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-overview.pod
wwwtext: support $INBOX_URL/_/text/config/raw
[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 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-2019 all contributors L<mailto:meta@public-inbox.org>
107
108 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>