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	Persistent diagnostics, traces, and recovery data.
/var/lib/bongo/cache	Regenerable caches.
/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:

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

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 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.

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. Remove those two 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.