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	Administrator-managed configuration and protected key directories.
/etc/bongo/config.d	Suffixless JSON mirrors for every operative Store configuration document.
/etc/bongo/aliases.d	Mergeable suffixless alias and virtual-domain JSON 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	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.

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.