Ship an example settings policy, and name the variables in .env.example
#231 added the policy but nothing to copy. The repo already answers this the same way four times over -- Caddyfile.example, deploy.example.sh, nginx.example.conf, .env.example -- and the new feature was the one thing configurable here with no example beside it. settings-policy.example.json carries all three sections with the reasoning in it, including the part worth being deliberate about: a `changes` entry overrides a decision a reader has already made, and if you want it to stay put regardless that is `enforced` instead. JSON has no comments, so the commentary is in `_`-prefixed keys, which is safe because the server reads three names and ignores everything else. A test asserts the shipped example stays valid against the rules the parser enforces -- unique versions, settings objects, no comment key colliding with a real section. An example that has drifted is worse than none: somebody copies it, the server refuses to start, and the first experience of the feature is a crash loop. .env.example gains the four variables, commented out, with the file form and the inline form and the note that the file wins over the variables. Confirmed against the real image on the deploy host rather than reasoned about: an immutable container -- --read-only, IMMUTABLE=1, SESSION_FILE= empty -- starts and serves the policy both with a read-only file mount and with the environment variables alone. The feature costs nothing in immutability, because the only thing it writes is the applied-changes stamp, and that goes in the reader's own settings file on Stalwart like every other setting.
This commit is contained in:
@@ -69,3 +69,27 @@ APP_NAME=ihasmail
|
||||
# you have patched it, point this at your own tree. Shown on the sign-in page
|
||||
# and in Settings > About.
|
||||
SOURCE_URL=https://github.com/Coffey-Labs/ihasmail
|
||||
|
||||
# ---- Settings this installation decides (all optional) ----
|
||||
#
|
||||
# Seed what a new account starts on, lock what nobody may change, and turn
|
||||
# something on once for accounts that already exist. Setting none of these --
|
||||
# the default -- behaves exactly as ihasmail always has.
|
||||
#
|
||||
# A file is easier once there are `changes` in it. See the shipped
|
||||
# settings-policy.example.json, and mount it read-only:
|
||||
#
|
||||
# -v /srv/ihasmail/policy.json:/etc/ihasmail/policy.json:ro
|
||||
#
|
||||
# SETTINGS_POLICY_FILE=/etc/ihasmail/policy.json
|
||||
#
|
||||
# Or inline, which is what an immutable deployment with no volume wants. These
|
||||
# are ignored entirely when SETTINGS_POLICY_FILE is set, so a file and a stray
|
||||
# variable cannot half-apply between them.
|
||||
#
|
||||
# SETTINGS_DEFAULTS={"externalSenderBanner":true}
|
||||
# SETTINGS_ENFORCED={"externalRecipientConfirm":true}
|
||||
# SETTINGS_CHANGES=[{"version":"20260902084513","settings":{"externalSenderBanner":true}}]
|
||||
#
|
||||
# Read once at startup: editing a policy means restarting the container.
|
||||
# Docs: https://docs.ihasmail.org/configure/#settings-your-installation-decides
|
||||
|
||||
Reference in New Issue
Block a user