bongo/README

# Bongo

Bongo is an easy-to-use mail and calendar system, offering a simple yet
powerful user interface. The goal is to make sharing, organisation, and
communication simpler, quicker, and more useful.

It is intended for power home users, homelabs, small organisations, and mail
service operators who want an integrated server without assembling every
basic mail and calendar function from unrelated daemons.

This repository revives and modernises the original Bongo mail/calendar
server. The [upstream GitHub repository](https://github.com/bongo-project/bongo)
was archived in January 2025; active development now lives in the
[Disconnected by Peer Gitea repository](https://gitea.disconnected-by-peer.at/geos_one/bongo).
The historical project site remains available at
[bongo-project.org](https://bongo-project.org/).

## Project status

Bongo 0.7 is an active development line, not yet a final release. It ports the
server and Web interface to current C, CMake, and Python 3 while retaining the
small integrated-server design and the familiar Bongo Web appearance. Test a
staged installation before exposing it to Internet mail traffic and keep a
backup of all mail, account, key, and configuration data.

The 0.7 mail listeners are IPv4. IPv6 support is planned as one coherent
change for 0.9 so authentication, ACLs, SPF, logging, rate limits, and proxy
metadata all use the same address representation. JMAP is likewise outside
the 0.7 scope.

## Highlights of the 0.7 development tree

- SMTP receiving and delivery, authenticated submission, SMTPS, opportunistic
  outbound STARTTLS, LMTP routing, and a rate-limited trusted-device relay.
- IMAP4, IMAP4rev1, and IMAP4rev2 compatibility, IMAPS, POP3/POP3S, and
  ManageSieve with shared GNU SASL authentication.
- Webmail plus CalDAV and CardDAV for mail, calendars, and contacts; the Web
  service is normally placed behind Apache, nginx, or Nginx Proxy Manager.
- Native SPF, DKIM, and DMARC verification, outbound DKIM signing, and SRS
  forwarding/reversal without depending on a separate filtering service.
- Optional ClamAV and SpamAssassin integration. Distribution defaults keep
  both agents disabled until their services are detected or configured.
- Argon2id account passwords, optional TOTP, recovery codes, service-scoped
  app passwords, and LDAP/Active Directory authentication with a bounded local
  outage cache.
- External POP3/IMAP collection and matching authenticated SMTP identities,
  Sieve filters, user tasks, signatures, and provider presets.
- HAProxy PROXY protocol v1/v2 for trusted TCP4 mail frontends, configurable
  Web forwarded-address handling, Fail2ban filters, systemd, and OpenRC files.
- Native RFC 8555 ACME renewal with HTTP-01 or DNS-01, ARI/Retry-After
  scheduling, native ldns `nsupdate`/RFC 2136 with TSIG, and a scoped
  Cloudflare provider plugin.
- GCC and Clang builds, split CMake files, CTest coverage, and CPack source and
  binary packaging.

## Build requirements

Bongo requires a C11 compiler, CMake 3.16 or newer, POSIX threads, Gettext,
GLib, GMime, libgcrypt, GnuTLS, SQLite, libcurl, ldns, GNU Mailutils with Sieve,
GNU GSASL 2.2 or newer, OpenLDAP, libical, liboath, Argon2, libqrencode, libspf2,
OpenDKIM (including `opendkim-genkey`), OpenDMARC, libsrs2, libpsl, GnuTLS's
`certtool`, and Python 3 with development headers. The Python
environment must provide `dnspython`, `python-dateutil`, `nh3`, and `vobject`.
CMake reports missing Python modules during configuration; setup reports a
missing key-generation tool before changing the operative configuration.

Build outside the source tree:

```sh
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
ctest --test-dir build --output-on-failure
cmake --install build
```

For a debug installation use `-DCMAKE_BUILD_TYPE=Debug`. Do not work around
warnings by disabling them: GCC and Clang should both compile the tree cleanly.

Create packages with the generated CPack configurations:

```sh
cpack --config build/CPackConfig.cmake
cpack --config build/CPackSourceConfig.cmake
```

Source archives are named `bongo-<version>` without a `-linux` suffix.
Distribution packages should configure `CMAKE_INSTALL_PREFIX=/usr`; CMake then
uses `/etc/bongo` rather than incorrectly installing configuration below
`/usr/etc`.

## Initial setup

After installing the files, run the scenario-based curses wizard as root:

```sh
bongo-setup
```

`bongo-config wizard` opens the same interface. The wizard asks about the mail
identity and domains, reverse proxies, enabled protocols, trusted port 26
relay, LDAP, legacy-client TLS, DKIM, public mail DNS, ClamAV, and
SpamAssassin, and optional ACME HTTP-01 or DNS-01 renewal. It validates or
creates the TLS and per-domain DKIM material,
shows exact SPF/DKIM/DMARC records, and records unfinished DNS work in the
admin task list. Individual settings retain safe defaults. Passwords and the
initial configuration bundle are passed through anonymous file descriptors
and do not appear in process arguments.

The wizard probes local `clamd` and `spamd` services. For an installed but
unreachable scanner it offers an explicit local configuration editor: paths
and service actions are previewed, unrelated options are preserved, listeners
are restricted to loopback, and adjacent `.bongo-setup.bak` files plus a
transactional rollback protect the previous setup. Service enable/restart is a
separate choice and must pass a protocol probe before the Bongo setup commits.
Remote scanners are never edited. Loopback-only scanner fragments and Apache,
nginx, Nginx Proxy Manager, and HAProxy examples are installed below
`share/bongo/examples`.

Start Bongo with the service manager used by the host, for example:

```sh
systemctl enable --now bongo.service
```

Use the common editor and validator for later changes:

```sh
bongo-admin config
bongo-admin config check
```

Store configuration document names such as `smtp`, `imap`, `antispam`, and
`antivirus` deliberately have no `.json` suffix even though their contents are
JSON. Source and installed template names use the same convention.

## Security and compatibility

TLS 1.3 and TLS 1.2 are the defaults. Older TLS can be enabled only through an
explicit compatibility option and should be limited to trusted legacy
networks. Internet SMTP delivery remains opportunistic because not every peer
offers STARTTLS; certificate verification is enabled when TLS is used, while a
separate policy can require TLS for controlled destinations.

The internal relay is not an open relay. It binds to its own address/port,
accepts only configured networks, normalises legacy local senders, and applies
connection, message, recipient, and byte limits. PROXY, XCLIENT, XFORWARD, and
mail-header client metadata are accepted or emitted only for explicitly
trusted peers.

Before a public deployment, review at least the TLS, authentication, mail-auth,
proxy, scanner, and SMTP documentation linked below.

## Documentation

- [Documentation index](docs/README.md)
- [Architecture and data flow](docs/architecture.md)
- [Administration quick reference](docs/administration.md)
- [Installation and state directories](docs/directory-layout.md)
- [Network ports](docs/ports.md)
- [Protocols and client compatibility](docs/protocols.md)
- [Storage and backup](docs/storage.md)
- [Development and testing](docs/development.md)
- [Roadmap to 1.0](docs/roadmap.md)
- [Guided setup and configuration](docs/setup-wizard.md)
- [TLS policy and legacy-client compatibility](docs/tls.md)
- [Authentication, TOTP, app passwords, LDAP, and Fail2ban](docs/authentication.md)
- [SMTP, submission, LMTP, internal relay, and proxy metadata](docs/smtp.md)
- [IMAP compatibility and internationalised mailboxes](docs/imap.md)
- [Mail storage quotas](docs/quotas.md)
- [SPF, DKIM, DMARC, and SRS](docs/mail-authentication.md)
- [SpamAssassin and ClamAV](docs/antispam.md)
- [HAProxy PROXY protocol](docs/proxy-protocol.md)
- [External account collection and sender identities](docs/external-accounts.md)

The archived
[Bongo project documentation](https://github.com/bongo-project/bongo-project/tree/gh-pages/Documentation)
preserves the original administration guide, protocol descriptions,
architecture notes, and release notes. It is useful for historical context,
but its installation paths, dependencies, SSL advice, and feature status do
not describe this 0.7 tree and must not be copied into a current deployment.

Related historical source repositories are also preserved on GitHub:

- [Dragonfly](https://github.com/bongo-project/dragonfly) contains the original
  Python/JavaScript Webmail and Hawkeye administration interface. The 0.7 Web
  service keeps its familiar artwork and CSS where applicable, with maintained
  Python 3 server code in this repository.

The maintained roadmap incorporates the still useful historical 1.0 goals.
Experimental Ruby rewrites are deliberately not part of the current plan:
the server and Web interface remain C and Python 3 respectively.

The manual pages `bongo-setup(1)`, `bongo-config(1)`, `bongo-admin(1)`,
`bongo-manager(1)`, and `bongoagents(8)` document the installed tools.

## History and licence

Bongo began as a community continuation of Novell Hula and retains the
original copyright notices throughout the source tree. Historical context is
preserved in `AUTHORS`, `ChangeLog`, `NEWS`, and the archived upstream
repository.

Bongo is free software under the GNU General Public License version 2. See
`COPYING` for the complete licence.