92 lines
2.7 KiB
Groff
92 lines
2.7 KiB
Groff
|
.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
|