App
Beacon
OVERVIEW
Beacon is a modern, secure, full-featured, open-source mail server for low-maintenance self-hosted email — a single Go binary serving SMTP/IMAP/HTTPS with automatic ACME TLS, webmail, and admin/account web interfaces. The Qompass repo carries the server (module `github.com/qompassai/beacon`, derived from the mox mail server codebase) under the tagline “Self-hosted mail made simple” / “Quality e-mail solution.”
HOW IT WORKS
- 1Generate a working setup with `beacon quickstart [-existing-webserver] [-hostname host] user@domain [user | uid]` — it writes configuration files, prints the initial admin and account passwords and the DNS records to create, and on Linux writes a systemd service file with the commands to enable/start it.
- 2Start the server with `beacon serve`: incoming mail is accepted over SMTP, mail is retrieved over IMAP, and HTTP listeners serve the admin/account web interfaces plus automated TLS configuration (missing essential certs are requested immediately, others on demand via ACME/Let's Encrypt). Unix only.
- 3Administer domains, accounts, and addresses either through the admin web interface or the config CLI (`beacon config domain add/rm`, `beacon config account add/rm`, `beacon config address add/rm`); validate with `beacon config test` and `beacon config dnscheck` / `beacon config dnsrecords`.
- 4Users read and send mail via IMAP/SMTP clients or the webmail interface; client settings are discoverable via `beacon clientconfig domain` / autoconfig.
- 5Operate the queue and data from the CLI against the running instance (via the ctl file in the data directory): `beacon queue list/kick/drop/dump`, `beacon import/export maildir|mbox`, `beacon backup`, `beacon verifydata`, and password resets with `beacon setaccountpassword` / `beacon setadminpassword`.
CONCEPTS
CONFIGURATION
| Option | Default | What it does |
|---|---|---|
`-config` flag / `BEACONCONF` env | `config/beacon.conf` (fallback `beacon.conf`) | Static config file; other config files (e.g. `domains.conf`) are looked up in the same directory |
`DataDir` (beacon.conf) | — (set by quickstart; `data` in test fixtures) | Directory for queue, accounts, messages, and ACME TLS certs/keys; relative paths resolve against the `beacon.conf` directory |
`Hostname` (beacon.conf) | — (set by quickstart) | Full hostname of the system, e.g. `mail.<domain>` |
`Listeners` (beacon.conf) | — | Named groups of IPs + enabled services (SMTP/IMAP, admin, metrics); a listener named `public` gets extra ACME/DNSBL checks |
`ACME` port | `443` by default | TLS port for ACME validation; override only if port 443 cannot be listened on directly |
`Postmaster` (beacon.conf) | — | Postmaster account + mailbox (e.g. `Postmaster` or `Inbox`) for postmaster mail |
`LogLevel` (beacon.conf) | `trace` in test fixtures | Startup log level; runtime-adjustable via `beacon loglevels [level [pkg]]` |
Domains / accounts (domains.conf) | — | `Domains:` map and `Accounts:` map with `Domain`, `Destinations`, optional `QuotaMessageSize` and `JunkFilter` (e.g. `Threshold: 0.95`) |
`-pedantic` flag | false | Protocol violations become errors instead of being accepted/worked around |
Quickstart run-as user | beacon | Optional `[user \ |
CONTROLS
| Action | Control |
|---|---|
| Set up a new instance | `beacon quickstart [-existing-webserver] [-hostname host] user@domain [user \ |
| Start the server | `beacon serve` (SMTP/IMAP/HTTPS) |
| Stop the server | beacon stop |
| Run locally for development | beacon localserve |
| Manage domains/accounts/addresses | beacon config domain add/rm`, `beacon config account add/rm`, `beacon config address add/rm |
| Check config / DNS | beacon config test`; `beacon config dnscheck domain`; `beacon config dnsrecords domain |
| Print generated config | beacon config describe-static >beacon.conf`; `beacon config describe-domains >domains.conf`; `beacon config printservice >beacon.service |
| Reset passwords | beacon setaccountpassword account`; `beacon setadminpassword |
| Manage the queue | beacon queue list`; `beacon queue kick/drop [-id id] [-todomain domain] [-recipient address]`; `beacon queue dump id |
| Import / export mail | `beacon import maildir\ |
| Backup / verify data | beacon backup dest-dir`; `beacon verifydata data-dir |
| DKIM / DMARC / SPF / DNS diagnostics | `beacon dkim gened25519\ |
| Show version / help | beacon version`; `beacon help [command …] |
NOT COVERED
- The GitHub README is Qompass boilerplate beyond the “Self-hosted mail made simple” header (its embedded quick-start even clones `qompassai/dotfiles`); every functional row above traces to the primo clone at `~/.GH/Qompass/Go/beacon` (`doc.go`, `main.go`, `config/config.go`, `quickstart.go`). There is no top-level `~/.GH/Qompass/beacon` clone — the primo copy lives under `Go/beacon`. - Provenance: the codebase is the mox mail server rebranded (test fixtures still named `mox.conf`, deps on `github.com/mjl-/…`); sources read do not state Qompass-specific deltas from upstream mox, so no Beacon-only features are claimed. - Config defaults are sconf-schema defaults documented in `config/config.go`; a full generated `beacon.conf`/`domains.conf` pair was not produced (quickstart was read, not run), and webmail/webadmin UI controls were inventoried as packages (`webmail/`, `webadmin/`, `webaccount/`) without a UI walkthrough.
REFERENCES
- RFC 5321 — Simple Mail Transfer ProtocolThe SMTP protocol Beacon accepts and delivers mail with.
- RFC 9051 — Internet Message Access Protocol (IMAP) - Version 4rev2The current IMAP revision — the protocol Beacon serves for mailbox access.
- RFC 8555 — Automatic Certificate Management Environment (ACME)The protocol behind Beacon's automatic TLS: missing essential certificates are requested at startup, others on demand.
- mox — modern, secure, all-in-one mail server (upstream)Provenance: Beacon's codebase derives from the mox mail server; the upstream repository is the reference implementation this codebase rebrands.