Choose how you manage settings

Web UI on a config file (the default)

Good for: a Raspberry Pi or a home server you look after in the browser.

1. The install's config file holds the basics: where to listen and which upstreams to ask. Leave it as it is.
2. Add and change everything else on its page in the web UI: upstreams, lists, groups and schedules, devices, local names, quick rules, and alerts.
3. Each change shows what it will do first. Changes are stored in state.db next to users and the audit log, and they're included in backups.

Each editor's Manage table says where every entry comes from:

Config file only

Good for: Ansible, Puppet, or a dotfiles repository, where every change is a reviewed diff.

1. Edit telltale.toml. Split it if you like: later files override earlier ones (telltale run -c base.toml -c site.toml).
2. Check it: telltale config check base.toml site.toml reports every problem at once with its key path. --print shows the effective configuration.
3. Apply it without a restart: systemctl reload telltale, or docker kill -s HUP telltale. A file that doesn't validate is refused and the previous configuration keeps serving.

telltale config check /etc/telltale/telltale.toml   # "config OK", or every error with its path
sudo systemctl reload telltale                       # applied with no dropped queries

To keep the file the only source, give everyone else the viewer role: viewers see everything but change nothing.

Git, per node (Helm, Argo CD, Flux)

Good for: Kubernetes, where Argo CD or Flux applies the Helm values from your repository.

1. Put your settings under config: in the Helm values. The chart writes them after its own (listeners, data directory, ports).
2. Tell TelltaleDNS the file comes from Git, so the UI can help you keep the repository in step:

config: |
  [cluster]
  config_source = "gitops"

  [[upstream]]
  name = "quad9"
  url = "tls://9.9.9.9"
  tls_server_name = "dns.quad9.net"

Changes in the UI still work, at once. After Apply, the UI shows the TOML to add to your repository (under config:) with a Copy button. Once Git has it, Revert to the file removes the UI's copy, so the next rebuild from Git doesn't lose anything. The API returns the same text as keepInGit.

The Kubernetes guide covers the rest of the chart.

Git, for the whole cluster

Good for: "nothing changes unless it's in Git", across every node.

Option 1: the cluster reads one file from a repository. The primary fetches the shared settings, checks them, and hands them to every node, so every node serves the same commit:

# On every node that may become primary:
[cluster.git]
repo = "https://github.com/me/homelab"
ref = "main"
path = "telltale/shared.toml"
# require_signed = true                 # only SSH-signed commits...
# allowed_signers_file = "/etc/telltale/allowed_signers"
# webhook_secret_file = "/etc/telltale/git-hook"   # push webhook: applied in seconds

• A commit is used only if it validates and descends from the one in use; anything else is refused, and the cluster stays on the last good commit.
• If the repository is unreachable, every node keeps serving the last commit. DNS never waits for Git.

Option 2: only Git-managed nodes may publish. On the primary: telltale cluster set-authority gitops (or telltale cluster init --config-authority gitops), then restart. Only nodes with [cluster] config_source = "gitops" may publish the cluster's configuration. Any other node can only take over as an emergency primary, which keeps the last version until a Git-managed node is back.