Config reload

Bongo reloads its configuration file on SIGHUP. Some settings take effect immediately; the rest take effect at the next restart. Mail, IMAP and web sessions stay connected during a reload.

Sending the signal

Edit the configuration file, then send SIGHUP to the bongo process:

docker compose kill -s HUP bongo     # Docker: the entrypoint runs bongo directly
systemctl reload bongo               # systemd: the unit's ExecReload sends SIGHUP
kill -HUP <pid>                      # any other process manager

SIGHUP never stops the server. A foreground bongo serve whose terminal closes, and a process started under nohup, reload rather than exit. SIGINT and SIGTERM stop the server.

A server started without a configuration file (for example bongo serve --dev with no --config) logs config reload: no config file in use, nothing to reload.

Settings that reload

Key Effect
telemetry.log.level Applies to the next log line.
telemetry.log.components Per-component levels; apply to the next log line. Removing an entry returns that component to telemetry.log.level.
antispam.builtin.threshold, antispam.builtin.high_threshold Applied together, from the next message scored.
smtp.trusted_networks Applies from the next message, including on connections already open.
antivirus.clamav.on_failure Applies from the next message scanned.

A widened smtp.trusted_networks is logged at WARN with the old and new lists. A narrowed one is logged at INFO.

Settings that need a restart

Every other setting needs a restart. Each changed one is logged at WARN as config reload: key needs restart, with the key name and whether it is a secret. Values are never logged. The warning repeats on every reload until the server restarts.

A few keys are not read by the server. A change to one of them is listed under no_effect in the summary line.

Flags and environment

Command-line flags and BONGO_* environment variables take precedence over the file. The overridable settings are BONGO_ROLE, BONGO_BIND, BONGO_JOIN and BONGO_WEB_SESSION_SECRET (and BONGO_CONFIG, which picks the file), plus the matching flags and --log-level. A key set by a flag or the environment keeps that value; the file value is ignored and logged as config reload: key shadowed by flag or env, file value ignored.

The environment is read once, at start. A changed /etc/bongo/bongo.env (systemd) or Compose .env / environment: needs a restart. With Compose, docker compose up -d recreates the container with the new environment; docker compose restart keeps the old one.

Validation

The file is parsed and validated in full before anything is applied, with the same checks as at startup. If parsing or validation fails, the reload logs config reload failed and every running value stays as it was. Parse errors are logged as a position and a summary only, so a value from the file never reaches the log.

Log output

Every reload ends with one INFO line, config reload complete, with these attributes:

Attribute Contents
file The file that was read
applied Keys applied
needs_restart Changed keys that need a restart
no_effect Changed keys the server does not read
shadowed Keys set by a flag or the environment
file_mtime, file_size Modification time (UTC) and size of the file as read

To check a reload:

docker compose logs --tail 30 bongo | grep 'config reload'

Docker single-file bind mounts

The shipped Compose file mounts the configuration as a single file. An editor that saves by writing a new file and renaming it creates a new inode, and the container keeps seeing the old file until it restarts. Edit the file in place, or check what the container sees before sending the signal:

docker compose exec bongo cat /etc/bongo/bongo.hcl

file_mtime and file_size in the summary line show which version was read.

Clusters

Configuration is per node. SIGHUP reloads only the node that receives it. In a cluster, edit the file and send the signal on every node. Cluster settings (cluster.*), ports, TLS files and server.name all need a restart, so a reload cannot change how nodes connect to each other.

Design

The classification of every key and the reasoning behind the reload flow are in docs/design/config-reload.md.

View this page's source on GitHub