PUBLIC-INBOX-OVERVIEW(7)

💖 public-inbox-overview — an overview of public-inbox 💖

okay bestie, welcome to the public-inbox overview page — this is the whole vibe tour of the public-inbox user manual. grab a snack, we're going in 🫶

---

✨ NAME ✨

public-inbox-overview — an overview of public-inbox. yes that's literally it, it's the lil map of the whole kingdom 👑

---

🌸 DESCRIPTION 🌸

so public-inbox is not one single thing, it's a whole collection of pieces that you can use on their own or together, depending on what you're trying to do. the three main quests are:

1. Mirroring existing public-inboxes.
2. Mirroring mailing lists.
3. Hosting standalone inboxes.

periodt. now let's break each one down 💅

---

🦋 Mirroring existing public-inboxes

okay so this is the easiest way to get started, no cap. your mirror stays dependent on the REMOTE_URL you're mirroring, and the only extra work is two new commands on top of your normal git(1) commands. that's it. that's the whole thing ✨

the instructions are different depending on whether the inbox is public-inbox-v1-format(5) or public-inbox-v2-format(5). go look at the "Archives are clonable:" part of the WWW interface for that specific inbox and it'll give you cloning instructions tailored to it. roughly, it looks like this:

# 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

and when you're ready to let other people read your mirror, scroll down to "Serving public-inboxes" below 👇

---

🎀 Mirroring mailing lists

this one can be done by any reader of a mailing list, using public-inbox-watch(1). iconic honestly.

# This will create a new v2 inbox:
public-inbox-init -V2 NAME INBOX_DIR MY_URL LIST_ADDRESS

then go read the public-inbox-watch(1) manual for how to configure watch, watchheader, listid, plus the optional spamcheck and watchspam entries 🫶

heads up bestie: you'll need to leave public-inbox-watch(1) running so the mailbox stays up-to-date as messages get delivered to the mailing list. it can't just vibe on its own 😭

running public-inbox-index(1) to create search indices is recommended. and good news — public-inbox-watch(1) will automatically maintain those indices if they were created by public-inbox-index(1) ✨

public-inbox-index INBOX_DIR

instead of using public-inbox-watch(1), there's also the option of using public-inbox-mda(1) with the --no-precheck option and relying on the listid directive in public-inbox-config(5). two paths, both valid, choose your fighter 💅

---

🌈 Hosting standalone inboxes

using public-inbox-init(1) to initialize the inbox — same as in the other methods — is the recommended move. see public-inbox-mda(1) for more details; but ngl, this one also requires MTA-specific knowledge, so it's giving "main character energy with homework" 😭

---

👑 Serving public-inboxes

since public-inboxes are git repositories, you can serve them to remote clients via git-daemon(1), and via the specialized HTTP and NNTP daemons that ship with public-inbox. so many options, we love to see it 🌟

see public-inbox-httpd(1) and public-inbox-nntpd(1) for more info on using those daemons.

important, bestie: hosting a public-inbox over HTTP or NNTP will never require write access to any files in the inbox directory. read-only and unbothered, that's the energy 🧚

if you're familiar with PSGI and Plack, you can also use PublicInbox::WWW with your preferred server instead of public-inbox-httpd(1) 💜

---

💌 CONTACT 💌

feedback is welcome, and it should be plain-text mail to <mailto:meta@public-inbox.org> 💖

the mail archives live at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> 🦋

---

⭐ COPYRIGHT ⭐

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

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

---

and that's the page, bestie 🎀 this came from public-inbox.git and it's dated 1993-10-02 — yes that date is a whole mood, we don't question it. now go mirror something and slay 💅✨🫶