# 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` | Local bootstrap, Web, and administrator-managed configuration. |
| `/etc/bongo/bongo.conf` | Authentication and LDAP bootstrap policy. |
| `/etc/bongo/bongo-web.json` | Web listener, proxy, session, and Web database policy. |
| `/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 and locally managed cryptographic material. |
| `/var/lib/bongo/web` | Web session, task, and identity databases. |
| `/var/lib/bongo/work` | Runtime work area. |
| `/var/lib/bongo/cache` | Regenerable caches. |
| `/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
```

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` tree. systemd-tmpfiles or the
service script creates volatile directories at boot. Persistent empty
directories below `/var/lib/bongo` are created during setup or package
installation with the appropriate owner.

The default TLS certificate and key are
`/var/lib/bongo/dbf/osslcert.pem` and
`/var/lib/bongo/dbf/osslpriv.pem`. ACME deployments may use paths managed by
their deploy hook instead. DKIM and SRS secrets are configuration-dependent
and must be included in backup and permission reviews.