Installing Bongo from the binary release
This guide installs and runs a Bongo mail + calendar server from a release zip — no Docker, no build toolchain. Everything (web assets, templates, translations) is embedded in a single self-contained binary.
If you would rather run under Docker + Traefik, see
../deploy/README.md instead.
1. What’s in the zip
Download the zip for your architecture from the
GitHub releases page, or
build the same zips from a source checkout with make dist (they land in
dist/).
bongo_<version>_linux_<arch>/
bongo # the server binary
bongo-import # mail import tool (mbox/maildir/eml/IMAP/Thunderbird)
bongo.example.hcl # fully annotated example configuration
bongo.service # systemd unit template
INSTALL.md # this guide
README.md # what this release is and what is not finished yet
LICENSE # licence text
THIRD_PARTY_NOTICES.md # licences of bundled third-party components
<arch> is amd64 (Intel/AMD x86-64) or arm64 (ARM 64-bit, e.g. Raspberry
Pi 4/5, AWS Graviton). Pick the zip matching your machine — check with
uname -m (x86_64 -> amd64, aarch64 -> arm64).
The binaries are statically linked and have no runtime dependencies — no libc, no database server, nothing to install alongside them.
2. Prerequisites
To try it locally you need nothing but the binary.
To run a real, internet-facing mail server you also need, outside this software:
- A host that allows outbound TCP port 25 (many cloud/VPS providers block it — if yours does, use an SMTP relay; see step 7).
- A static IP with a matching PTR (reverse DNS) record pointing at your
mail hostname (e.g.
mail.example.com). - Control of your domain’s DNS to publish A / MX / SPF / DKIM / DMARC records (the admin UI generates the exact records for you).
- A TLS certificate for the mail hostname (e.g. from Let’s Encrypt). Without one, IMAP and POP3 fall back to a self-signed certificate (fine for testing; real clients will not trust it), and SMTP offers no STARTTLS at all, so authenticated submission on port 587 is unavailable because AUTH is only offered over TLS.
- Ports open:
25,587(SMTP),465(SMTP over implicit TLS; needssmtp.tls, otherwise it is not started),143,993(IMAP), optionally110,995(POP3), and443(web UI). Binding ports below 1024 needs root or a capability grant (see step 6).
Sizing
Measured on a 2 vCPU (shared), 4 GB virtual server with no swap, antivirus
off. The numbers are preliminary; docs/design/load-test-results.md has the
conditions.
- CPU is the first limit. Search indexing of new mail and password checks for logins use most of it. That machine sustained about 3 messages/s of inbound mail with about 820 connected clients, and about 16 new logins per second. CalDAV and CardDAV clients check the password on every request, so each one costs more CPU than an IMAP client.
- Memory. Plan for about 1 GB with several hundred clients, plus about
100 KB per open IMAP connection. The server has no memory ceiling of its own;
without swap, running out stops it. The container in
deploy/docker-compose.ymlis limited to 2 GB (mem_limit); raise it on a larger machine. - Disk. The search index takes several times the space of the mail it
indexes: about 85 KB per message, or about 340 KB for an account holding
five small messages. Keep the data directory on local SSD or NVMe; Bongo
refuses new mail with a temporary error while free space is below
storage.min_free_mb(default 1,024 MB), and accepts it again once space returns (free space is checked every 10 s). - Restarts. A clean stop and start takes seconds. After an unclean stop
(power loss,
kill -9, out of memory) every search and folder index is rebuilt before the server accepts connections: 68 minutes for 10,000 small accounts on that machine. Letsystemctl stopfinish rather than killing the process;deploy/bongo.servicekeeps systemd’s default stop timeout (90 s).
3. Install the files
unzip bongo_<version>_linux_<arch>.zip
cd bongo_<version>_linux_<arch>
# Binaries onto PATH
sudo install -m 0755 bongo bongo-import /usr/local/bin/
# Config directory
sudo mkdir -p /etc/bongo
sudo cp bongo.example.hcl /etc/bongo/bongo.hcl
# Data + log directories
sudo mkdir -p /var/lib/bongo /var/log/bongo
The server discovers its config file in this order:
--config flag > BONGO_CONFIG env var > ./bongo.hcl > /etc/bongo/bongo.hcl.
Putting it at /etc/bongo/bongo.hcl means you can just run bongo serve.
4. Quickest possible test (no config, no DNS)
To confirm the binary runs on your machine before doing any real setup:
bongo serve --dev
Dev mode uses ephemeral storage, runs the mail protocols on high ports, and
auto-creates a login of admin@localhost / admin. The mail protocols’ TLS
ports use a self-signed certificate. The web UI is always served over
plain http in dev mode (no TLS, so no certificate warning) at
http://localhost:8080 — do not use dev mode anywhere untrusted, since the
password crosses the network in clear. Stop it with Ctrl-C — nothing is
persisted.
5. Configure a real server
Edit /etc/bongo/bongo.hcl. Every option is documented inline in the example.
The minimum you must change for a real single-domain server:
- Hostname — set
smtp.hostnameto your mail host, e.g.hostname = "mail.example.com". - TLS certificates — point the cert/key at your certificate. IMAP (993) and
POP3 (995) read theirs from the
cluster.tlsblock; SMTP readssmtp.tls; the web UI readsweb.tls. Use the same fullchain/key for all three:cluster { tls { cert_file = "/etc/bongo/certs/fullchain.pem" key_file = "/etc/bongo/certs/privkey.pem" } } smtp { tls { cert_file = "/etc/bongo/certs/fullchain.pem" key_file = "/etc/bongo/certs/privkey.pem" } } web { tls { cert_file = "/etc/bongo/certs/fullchain.pem" key_file = "/etc/bongo/certs/privkey.pem" } }(Behind a TLS-terminating reverse proxy instead? Set
web.plain_http = trueandweb.behind_tls_proxy = true, changeweb.portto8080, and list the proxy’s address inserver.trusted_proxies; without itX-Forwarded-ForandX-Forwarded-Protoare ignored, so rate limits and lockout see the proxy’s IP and HSTS is not sent.) - Session secret — generate one and keep it out of the file:
openssl rand -base64 32Export it as
BONGO_WEB_SESSION_SECRET(the systemd unit reads it from an environment file — see step 6). The same secret is needed to create the first admin (step 8). - DNS — publish A,
MX -> mail.example.com, SPF (v=spf1 mx ~all) and DMARC (p=noneto start) records, plus the PTR for the mail host. The admin UI’s per-domain page generates the exact record set (and a BIND zone).
DKIM (recommended)
Generate a signing key and enable the smtp.dkim block:
sudo mkdir -p /etc/bongo/secrets
sudo openssl genrsa -out /etc/bongo/secrets/dkim.key 2048
sudo openssl rsa -in /etc/bongo/secrets/dkim.key -pubout -outform DER 2>/dev/null \
| openssl base64 -A # this is the p= value for the DNS TXT record
smtp {
dkim {
selector = "mail"
domain = "example.com"
private_key_file = "/etc/bongo/secrets/dkim.key"
}
}
Publish the public key as a TXT record at mail._domainkey.example.com
(v=DKIM1; k=rsa; p=<base64 from above>).
Alternatively, once the server is running, generate a key per domain in the web
UI under Admin → Domains → Manage. The page shows the DNS TXT record to
publish, and no key file or smtp.dkim block is needed for that domain.
6. Run as a service (systemd)
The included bongo.service runs the server as a dedicated user, restarts on
failure, and grants the capability to bind low ports without running as root.
# Dedicated system user
sudo useradd --system --home /var/lib/bongo --shell /usr/sbin/nologin bongo || true
sudo chown -R bongo:bongo /var/lib/bongo /var/log/bongo /etc/bongo
# Secret in an environment file (root-only)
echo "BONGO_WEB_SESSION_SECRET=$(openssl rand -base64 32)" | sudo tee /etc/bongo/bongo.env >/dev/null
sudo chmod 600 /etc/bongo/bongo.env
# Install and start the unit
sudo cp bongo.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bongo
# Watch it come up
journalctl -u bongo -f
7. External SMTP relay (smarthost)
If your host blocks outbound port 25, or you must send through a provider
(SendGrid, Mailgun, your ISP’s smarthost), enable the relay block in
bongo.hcl. All outbound mail then goes through that server instead of
direct-to-MX:
smtp {
relay {
enabled = true
host = "smtp.provider.com:587" # host:port of the smarthost
username = "you@example.com" # SMTP AUTH username (omit for none)
password = "your-app-password" # SMTP AUTH password
# allow_insecure_auth = false # only for a trusted link with no STARTTLS
}
}
How it works: Bongo connects to the smarthost, performs opportunistic STARTTLS,
and sends AUTH PLAIN only after TLS succeeds. If the link cannot be
encrypted it refuses to send the credentials unless you explicitly set
allow_insecure_auth = true (use only on a trusted private network). Permanent
(5xx) recipient rejections are reported back; transient failures are retried
from the outbound queue.
When enabled = false, Bongo delivers directly to each recipient’s MX. The
mta_sts_enabled / dane_enabled options (also in the relay block) harden that
direct-to-MX path and are ignored when a smarthost is in use.
8. Create the first admin user
Production does not auto-create a login. With the server running, create one by calling its internal endpoint (authenticated with the session secret):
bongo user create \
--email you@example.com \
--password 'a-strong-password' \
--admin \
--http-addr http://127.0.0.1:8081 \
--session-secret "$BONGO_WEB_SESSION_SECRET"
--http-addr must point at the running node’s control listener
(server.control_addr, default http://127.0.0.1:8081, always plain HTTP and
loopback only). The /internal/* routes are not served on the public web
port. If you change server.control_addr, pass the new address here, because
the CLI does not read the server config.
--session-secret must match the node’s
web.session_secret; it also falls back to the BONGO_WEB_SESSION_SECRET
environment variable. Then log in to the web UI.
You do not need to add your primary domain: on startup the server adds it as a
managed domain, taking smtp.dkim.domain or, if that is unset, the registered
domain of smtp.hostname (example.com for mail.example.com). Add any
further domains under Admin → Domains; they are managed at runtime, not in
the config file.
Listing users, domains and aliases
Three read-only commands list what the server holds, without the web UI. They
use the same control listener and session secret as user create:
bongo user list [--domain example.com] [--json]
bongo domain list [--json]
bongo alias list [--domain example.com] [--json]
user listprints email, display name, enabled or disabled, global admin and the domains the account administers.domain listprints each hosted domain with its status,alias_of(set for a domain alias), catch-all target, user and storage quota, usage and whether a DKIM key exists. The key itself is never shown.alias listprints address aliases (an alias address and the account it delivers to), not domain aliases. Domain aliases are in theALIAS OFcolumn ofdomain list.--domainkeeps only addresses ending in@example.com; subdomains do not match.--jsonprints a JSON array with the same fields as the table.--http-addrand--session-secretwork as foruser create;--http-addracceptshost:portorhttp://host:port. If the server cannot be reached the command prints one line naming the control address and exits non-zero.
The data comes from the node’s own Pebble store, never from passwords, TOTP
secrets, recovery codes, DKIM keys or session material. A follower may lag the
leader by a few log entries. Each list is sorted and capped at 100000 rows; if
it is cut, the command still prints what it has, warns on stderr and exits
non-zero (narrow it with --domain). An older node that lacks these routes
answers 404, which the command reports as such.
9. Importing existing mail
bongo-import ingests mail from mbox, maildir, .eml, IMAP and Thunderbird
profiles. See importing.md.
Cron jobs and web applications on the same host can send mail through
bongo sendmail, a sendmail-compatible submission client. See
sendmail.md.
10. Upgrading
Stop the service, replace the two binaries, start it again — data in
/var/lib/bongo and your config are untouched:
sudo systemctl stop bongo
sudo install -m 0755 bongo bongo-import /usr/local/bin/
sudo systemctl start bongo
bongo version # confirm the new version