.TH NUNTIUS 1 2026-09-28 "nuntius 1.0.0" "nuntius manual"
.SH NAME
nuntius \- contact form backend
.SH SYNOPSIS
.B nuntius
.RB [ \-\-version ]
.RB [ \-\-check\-config ]
.SH DESCRIPTION
.B nuntius
serves multiple JSON form endpoints (contact, feedback, newsletter,
generic) from a single static binary, validates each submission, delivers
it by SMTP and keeps per-form rate limits, CORS allowlists and a honeypot
field. Newsletter forms use a double opt-in: the address is recorded only
after the subscriber redeems the confirmation link from the mail.
.PP
Configuration is read from a TOML file, /etc/nuntius/config.toml by
default. The first start writes a three-form starter template when the
file does not exist, and every ${VAR} reference inside it is expanded
from the environment before parsing, so secrets stay out of the file.
With no flags the server listens on the configured address and serves
until SIGINT or SIGTERM, then drains in-flight requests and exits.
.SH OPTIONS
.TP
.B \-\-version
Print the release the binary was built at, then exit. A build at a tag
reports the tag, a build from a commit reports a pseudo-version naming
that commit, and a build outside version control reports (devel); a dirty
tree appends +dirty.
.TP
.B \-\-check\-config
Load and validate the configuration file, then exit without listening.
Exits nonzero and names the problem on any error, so it can run as a
systemd ExecStartPre.
.SH EXIT STATUS
.TP
.B 0
The requested operation succeeded: the version was printed, the
configuration is valid, or the server shut down cleanly.
.TP
.B 1
The configuration is missing, invalid or fails validation, or the server
failed to serve.
.SH CONFIGURATION
The full schema, every key with its type, default and effect, is in
.I docs/CONFIGURATION.md
in the repository. Configuration is one TOML file holding a
.B [server]
table, a
.B data_dir
and one or more
.B [[forms]]
entries, each with its own SMTP settings, rate limit, CORS allowlist and
honeypot field.
.SH ENVIRONMENT
.TP
.B NUNTIUS_CONFIG
Path of the configuration file to read instead of
/etc/nuntius/config.toml.
.SH FILES
.TP
.I /etc/nuntius/config.toml
The default configuration file; written as a starter template on first
start when missing.
.TP
.I data_dir/newsletter-<name>.jsonl
The append-only newsletter subscriber log, where data_dir is the
configured data directory (./data by default).
.SH EXAMPLES
Print the release:
.PP
.RS
.nf
nuntius \-\-version
.fi
.RE
.PP
Validate a configuration without listening:
.PP
.RS
.nf
NUNTIUS_CONFIG=./config.toml nuntius \-\-check\-config
.fi
.RE
.SH AUTHOR
Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
.SH LICENCE
MIT License
.SH SEE ALSO
.IR docs/CONFIGURATION.md ,
.IR docs/API.md ,
.IR docs/DEPLOYMENT.md