Overview
Stalwart is configured through a small startup file called config.json and a database that holds everything else. When the server starts, it reads config.json to learn where the database is, connects to it, and loads the rest of its configuration from there. Every setting (domains, accounts, TLS certificates, SMTP rules, rate limits, and so on) lives in that database as a structured object.
Bootstrap mode
The first time Stalwart is started without a config.json, it enters bootstrap mode. No mail services are started. The server listens on HTTP port 8080 (configurable with STALWARTRECOVERYMODE_PORT) and serves only the WebUI and the management API, with the JMAP API restricted to a single object type: Bootstrap.
Recovery mode
Recovery mode is intended for situations where a running deployment requires maintenance and the normal services must not be active. Typical reasons include a misconfigured external directory that is preventing any administrator from signing in, a faulty setting that is causing the MTA to loop, a pre-deployment provisioning step where a large batch of objects must be loaded before any mail traffic reaches the server, or a freshly bootstrapped installation where HTTPS on the configured hostname is not yet reachable and the WebUI must remain available over HTTP to finish the setup.
Environment variables
A small number of environment variables influence how Stalwart starts. None of them are required for a normal installation; they exist for recovery, diagnostics, public URL composition, and clustering.
Declarative deployments
Operators who manage infrastructure with tools such as NixOS, Ansible, Terraform or Pulumi typically describe the desired state in a text file and let the tool converge the system toward it. Stalwart supports this workflow, with one notable detail: the declarative surface is split between the config.json file and the CLI.
Expressions
4 items
Variables
Context or environment variables may be used in certain settings of the configuration file that accept expressions. The available context variables for evaluation vary depending on the setting and can include: