bongo/docs/directory-layout.md

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:

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.