# Directory layout

Bongo follows FHS-style paths for distribution installs. Configure a package
build with `CMAKE_INSTALL_PREFIX=/usr`; CMake then deliberately keeps host
configuration under `/etc`, not `/usr/etc`.

## Distribution installation

| Path | Contents |
| --- | --- |
| `/etc/bongo` | Administrator-managed configuration and protected key directories. |
| `/etc/bongo/config.d` | Suffixless JSON mirrors for every operative Store configuration document. |
| `/etc/bongo/aliases.d` | Editable mirror of the Store-authoritative, mergeable suffixless alias and virtual-domain fragments. |
| `/etc/bongo/ssl.d` | TLS certificates and private keys managed by setup or an ACME deploy hook. |
| `/etc/bongo/dkim.d` | Per-domain DKIM keys and related material. |
| `/etc/bongo/dmarc.d` | DMARC setup state and report-processing policy. |
| `/etc/bongo/acme.d` | Root-owned ACME DNS-provider credentials and policy. |
| `/etc/bongo/migration-backup` | Files consumed by an explicit one-time legacy migration. |
| `/var/lib/bongo` | Persistent Bongo state. |
| `/var/lib/bongo/users` | Per-user stores and message documents. |
| `/var/lib/bongo/system` | System Store and Store configuration documents. |
| `/var/lib/bongo/spool` | Queue spool. |
| `/var/lib/bongo/dbf` | Account database, random seed, protocol parameters, and runtime credentials. |
| `/var/lib/bongo/web` | Web session, task, and identity databases. |
| `/var/lib/bongo/work` | Persistent diagnostics, traces, and recovery data. |
| `/var/lib/bongo/cache` | Regenerable caches. |
| `/var/spool/bongo/maildrop` | Protected setgid hand-off for unprivileged local mail submission. |
| `/run/bongo` | Volatile PID and agent recovery files. |
| `/usr/sbin` | Server agents and administration programs. |
| `/usr/libexec/bongo` | Private administration helpers. |
| `/usr/share/bongo` | Web assets, providers, zone snapshot, templates, and examples. |
| `/usr/share/man` | Manual pages. |
| `/usr/lib/systemd/system` | systemd service unit. |
| `/usr/lib/tmpfiles.d` | Runtime-directory declaration. |
| `/usr/lib/sysusers.d` | Distribution-neutral service account declaration. |
| `/etc/fail2ban` | Bongo filter and disabled jail template, when enabled at build time. |

Distribution packaging may override the systemd, tmpfiles, sysusers, and
Fail2ban destinations with the documented CMake cache variables.

## Other prefixes

A self-contained install with `CMAKE_INSTALL_PREFIX=/usr/local` uses
`/usr/local/etc/bongo`. Executables, data, and libraries follow the selected
prefix, while persistent state remains `/var/lib/bongo` unless
`BONGO_STATE_DIR` is explicitly changed.

Useful configure-time overrides include:

```sh
cmake -S . -B build \
    -DCMAKE_INSTALL_PREFIX=/opt/bongo \
    -DSYSCONF_INSTALL_DIR=/etc \
    -DBONGO_CONFIG_DIR=/etc/bongo \
    -DBONGO_STATE_DIR=/srv/bongo \
    -DBONGO_RUNTIME_DIR=/run/bongo \
    -DBONGO_MAILDROP_DIR=/var/spool/bongo/maildrop
```

Absolute paths are compiled into agents and generated service/configuration
files. Do not move an installed state tree without reconfiguring and rebuilding
or supplying matching package overrides.

## Runtime directories

Packages should not ship a populated `/var/run` or `/run` tree.
systemd-tmpfiles or the service script creates `/run/bongo` at boot.
Persistent empty directories below `/var/lib/bongo` and the protected local
submission path below `/var/spool/bongo` are created during setup or package
installation with the appropriate owner.

TLS, DKIM, DMARC and SRS material below `/etc/bongo` must be included in backup
and permission reviews. ACME deployments may point configuration at paths
managed by their deploy hook instead. Runtime credentials required to access
the Store remain protected state below `/var/lib/bongo`.

## Package removal and upgrades

Distribution upgrades and same-version reinstalls preserve all
administrator-created configuration and key material below `/etc/bongo` and
all persistent mail, Store, queue, account, Web, and worker state below
`/var/lib/bongo`. Accepted local submissions below `/var/spool/bongo` are
preserved as well.

On Debian, a normal package removal deletes Bongo programs and service units
but retains package-owned conffiles as well as both Bongo trees. A purge also
deletes the package-owned Fail2ban filter and disabled jail template. It still
does **not** delete `/etc/bongo` or `/var/lib/bongo`: destroying keys, server
configuration, queued messages, or user mail as a side effect of package
removal would be unsafe. The same rule applies to `/var/spool/bongo`. Remove
these trees explicitly only after making and verifying any required backup.

`/run/bongo` contains no persistent state. Its contents can remain until the
next boot after a package removal and must never be relied upon for recovery.