Configuration Settings

All configurable settings for DMART. Bound to the strongly-typed DmartSettings record and loaded from a config.env dotenv file and/or environment variables. Values are read once at boot and validated before the server starts — there is no hot reload and no file watcher.

Loading Order

Sources are layered with a strict precedence (later wins): appsettings.json < config.env < environment variables (Dmart__Xxx).

The config.env file is located with a first-match-wins lookup:

1. The path in the BACKEND_ENV (or DMART_ENV) environment variable — used for dev/CI, e.g. a repo-local file

2. ~/.dmart/config.env — per-user install

3. /etc/dmart/config.env — system-wide RPM/DEB install

A cwd-relative ./config.env is not looked up implicitly. Because the file may carry JWT_SECRET and DATABASE_PASSWORD, DMART refuses to read it when it is world-writable, and warns at every start when it is world-readable.

Where the first file comes from. dmart init writes ~/.dmart/config.env from the config.env.sample shipped beside the binary, with a fresh random JWT_SECRET, and leaves an existing file alone. The sample's values are not all the defaults in the tables below: it sets JWT_ACCESS_EXPIRES=3600, DATABASE_DRIVER="postgresql" with DATABASE_PASSWORD="somepassword", and ADMIN_EMAIL="admin@example.com", among others. The RPM, DEB and APK packages instead seed /etc/dmart/config.env from config.env.packaged: SQLite at /var/lib/dmart/dmart.db, SPACES_FOLDER="/var/lib/dmart/spaces", JSON logs, and the placeholder JWT_SECRET, which must be replaced before the server starts.

Strict validation. Configuration is bound and validated at startup (ValidateOnStart). Any unknown key in config.env is rejected and aborts startup — there is no silent fallthrough for typos. (Environment variables are not checked this way.) Keys of settings that no longer exist — REDIS_HOST/PORT/PASSWORD/CONNECTION, ACTIVE_DATA_DB, WEBSITE_URL and WEBSITE_DIR — are unknown keys and stop the boot. ALLOW_PASSWORD_RESET_RESEND_AFTER is ignored with a warning. MANAGEMENT_SPACE is retired: the management space is always management. MANAGEMENT_SPACE="management" still starts, with a warning to remove the line; any other value refuses to start.

Frontends read the server's values. The config.json DMART serves cxb and catalog carries OTP_LENGTH, ALLOW_OTP_RESEND_AFTER, OTP_TOKEN_TTL, MAX_UPLOAD_SIZE_MB, DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, UI_LIST_LIMIT, and whether the password and username rules are custom (password_rule_custom, username_rule_custom), with their hints (password_hint, username_hint). A frontend DMART does not serve can read the same from GET /public/client-config. The backend_timeout in that config.json is at least REQUEST_TIMEOUT + 5 seconds, so the server's own timeout answer arrives before the frontend gives up.

The frontends' own config.json. DMART serves cxb and catalog the first it finds of: the file named by --cxb-config (or DMART_CXB_CONFIG), ./config.json, ~/.dmart/config.json, and the copy built into each app. Its keys are title, footer, short_name, display_name, description, default_language, languages and backend, plus catalog's switches enable_websocket, enable_messaging, enable_surveys, enable_poll, enable_reaction_and_comment, enable_public_view and enable_notifications. A blank backend means the page's own origin. Any other value must be on the page's own site, because both apps authenticate by a SameSite=Lax cookie (see Base URL & Authentication). cxb draws schema and workflow diagrams by sending their text to https://www.plantuml.com/plantuml, unless plantuml_server names another server.

General Configuration

Outbound calls have timeouts of their own, each 1–3600 seconds: SMTP_TIMEOUT, SMS_TIMEOUT, OAUTH_TIMEOUT and EMBEDDING_TIMEOUT, listed with their services below. Startup warns when one of them, times the calls a request makes in a row (up to three for a social sign-in), is not shorter than REQUEST_TIMEOUT: the request's own deadline would cut it off first, and the client would get a bare timeout instead of the call's error.

Server & Network

With ASPNETCORE_URLS set in the environment, that names the listen address instead of LISTENING_HOST and LISTENING_PORT. dmart selfcheck, and dmart cli given no URL, reach the server at LISTENING_HOST:LISTENING_PORT from the same config.env, reading a wildcard host such as 0.0.0.0 as 127.0.0.1. Signing in without a password, with a token minted from this config.env, they send that token only to that address or a loopback one (localhost, 127.0.0.0/8, ::1), and refuse any other URL before a token is minted (see CLI).

Database & Storage

DMART keeps all runtime data in one SQL database: PostgreSQL (via Npgsql) or SQLite. PostgreSQL is the full tier. SQLite is a reduced tier for a single node, the edge, development and CI, and the default for the RPM, DEB and APK packages and the container. There is no Redis and no filesystem runtime store; all caches are in-process.

What SQLite costs. Payload filters (@payload.body.x:v) scan every row, with no index, so their cost grows with the corpus. One writer runs at a time. ILIKE folds case for ASCII letters only. A number stored as a JSON string sorts as text. sum and avg are floating point. Semantic search and four aggregation reducers (Query & Search) are PostgreSQL only. The database runs in WAL mode, which keeps -wal and -shm files beside it, so a file backup copies all three together (or use dmart export). It serves one node: the locks that let several DMART processes share a database are PostgreSQL's. Use PostgreSQL when a payload-filtered query over the whole corpus must stay under about 50 ms, or when write latency under concurrent writers must stay bounded.

Storage that does not survive a reboot. On Linux, startup warns with NON_DURABLE_STORAGE when SPACES_FOLDER or the SQLite file sits on a tmpfs or ramfs. The usual cause is a volume that failed to mount, leaving the empty directory beneath it in use.

On PostgreSQL, provide a full connection string with POSTGRES_CONNECTION, or leave it unset and let DMART assemble one from the individual DATABASE_* components below.

PostgreSQL Connection

Time zone. DMART stores timestamps as the app host's local wall-clock time, with no time zone (see Data Model). It pins each PostgreSQL session's time zone to the app host's, so the database's own clock agrees, unless the connection string sets Timezone= itself.

Session name. DMART names its PostgreSQL sessions dmart@<host>, after the app host's name. It shows as application_name in pg_stat_activity and as %a in the database's log, so two DMART nodes, or DMART and another service signing in as the same role, can be told apart. A POSTGRES_CONNECTION that sets Application Name keeps its own.

Spaces Folder (import/export only)

The on-disk spaces/ + .dm/meta.*.json layout is a transfer/backup format used only by import, export and seed — never as a live store. SPACES_FOLDER defaults empty. When set, it is where dmart seed copies the bundled sample spaces, and the root of an optional append-only audit trail: each space's events go to <SPACES_FOLDER>/<space>/.dm/events.jsonl (rolled over at EVENTS_LOG_MAX_BYTES), which events queries read. Empty, no audit trail is written.

Security & Authentication

Authentication is JWT Bearer (HS256, symmetric key from JWT_SECRET) with Argon2id password hashing. With ENABLE_MCP=true DMART also runs an OAuth 2.1 authorization server for MCP clients, and with OIDC_ISSUER set, an OpenID Connect provider that signs its tokens with its own RSA key. DMART's own tokens are always HS256; that is not configurable.

JWT & Sessions

Brute-force & Rate Limiting

These limits are server-wide. They apply the same way to web, mobile and admin accounts; bot accounts are never locked by MAX_FAILED_LOGIN_ATTEMPTS, though their failures are still counted.

One sign-in attempt

flowchart TD
    start(["Sign-in attempt"]) --> atmax{"Locked?"}
    atmax -- yes --> quiet{"Cool-down<br/>over?"}
    quiet -- no --> touch["Restart the cool-down"]
    touch --> locked(["USER_ACCOUNT_LOCKED"])
    quiet -- yes --> clear["Unlock:<br/>attempt_count = 0"]
    clear --> cred
    atmax -- no --> cred{"Password<br/>or code right?"}
    cred -- yes --> ok(["Signed in,<br/>attempt_count = 0"])
    cred -- no --> inc["attempt_count + 1"]
    inc --> reached{"Limit<br/>reached?"}
    reached -- yes --> locked
    reached -- no --> wrong(["Wrong password<br/>or code"])

Locked means attempt_count has reached MAX_FAILED_LOGIN_ATTEMPTS. Cool-down over means no attempt for more than LOCKOUT_COOLDOWN_SECONDS. A wrong code, or the right one sent after it expired, also uses up one of that code's own MAX_OTP_VERIFY_ATTEMPTS. Wrong passwords at the login, OIDC and MCP sign-in forms, wrong or expired codes at login and password reset, a wrong current password on a profile change or at /user/validate_password, a wrong current password when an account changes its own email or phone, and failed LDAP binds all add to the same counter.

The account over time

stateDiagram-v2
    state "No failures" as Clean
    state "Some failures" as Counting
    state "Locked" as Locked
    [*] --> Clean
    Clean --> Counting : wrong
    Counting --> Counting : wrong
    Counting --> Clean : right
    Counting --> Locked : wrong, limit reached
    Locked --> Locked : any attempt restarts the cool-down
    Locked --> Clean : cool-down passes, or admin unlocks

The cool-down counts from the last attempt, not from when the lock started, so every attempt while locked starts it again, even one with the correct password. With the defaults:

A lock does not sign the user out: access tokens already issued keep working until they expire, but refreshing them at /oauth/token is refused. An admin unlocks an account early with a user update carrying unlock: true, which is what the "clear on save" box in CXB and the catalog sends. An attempt_count sent in an update is ignored, so a client that posts a user record back can neither clear a lock nor lower the counter. Nobody unlocks their own account this way, and unlocking an admin account takes a global admin or the admin that owns it.

Registration, OTP & Profiles

The rules file. The JSON file at REGEX_CONFIG_PATH may hold email, msisdn, password, password_hint, username and username_hint:

{
  "email": "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\z",
  "password": "^.{12,64}\\z",
  "password_hint": "Use at least 12 characters.",
  "username": "^[a-z][a-z0-9_]{2,31}\\z",
  "username_hint": "3-32 lowercase letters, digits and _, starting with a letter."
}

• A missing file, key or empty value keeps the built-in rule. A rule that does not compile is logged, and the built-in one applies.
• password applies to every new password (registration, profile, reset, an admin's create), never to stored ones.
• username applies to a username a person chooses for a new user: a registrant's shortname at /user/create, an admin's create, and dmart import-ldif. It can only narrow DMART's own shortname rule (letters, digits and _, up to 64 characters), since a name must match both. A name the server makes is not held to it. Where DMART's usernames become Matrix IDs, use a Matrix-safe rule such as the one above.
• The hints are what a refused password or username is told, and sign-up forms show them, so set each one whenever you change its rule.

Admin Accounts

Accounts of type admin sign in with their password and a one-time code, both checked: once the password checks out, the server sends the code. An admin resets its password by code only while force_password_change is set on the account, which only a global admin, or the active admin that created the account, may set.

Management's users, roles, permissions and groups are for accounts of type admin and the built-in dmart. Another account's grants on them count only through the two exemptions below (see The Management Space). At every start the log names, as MANAGEMENT_ADMIN_ONLY, each role whose grants there the rule limits, and dmart check management hard counts the accounts that hold each.

Password Hashing

These set how new hashes are made. A stored hash keeps its own parameters, so changing them never invalidates a password.

Admin Bootstrap

Email & Notifications

Email and SMS each have an on/off switch, IS_SMTP_ENABLED and IS_SMPP_ENABLED. Left unset, a channel is on exactly when it has a real gateway. A channel that is off sends nothing, mocked or not, and logs no code, while the request still succeeds, so a code sent over it reaches nobody. Startup names a gateway or a mock that an off channel ignores.

The message text. A code goes out as otp_message, by SMS and as an email's body, with {code} replaced by the code and {otp_ttl} by OTP_TOKEN_TTL in minutes. An email's subject is otp_email_subject, which never carries the code. Both come from the built-in language files (english, arabic and kurdish), in the account's language, falling back to English. To change them, put the keys in ~/.dmart/languages/<english|arabic|kurdish>.json: each key there overrides the built-in one, and the rest stay. The files are read at start.

SMTP

SMS Gateway

Logging

The access line. Each request logs one line carrying its X-Correlation-ID, the header the response returns. In JSON, props.duration is in milliseconds. Secrets are masked in bodies, headers and query strings: a body field is masked when its name is a known secret (code, reset_code and verification_code among them, though not the number in a response's error object, which is dmart's error code and stays readable), ends in password, secret, _hash, _token, _otp or _key, or is one a history diff masks (see history), such as passwordConfirm, pwd, pin, otpCode or apiKey, unless it ends like a name that only talks about a secret: password_hint, token_type and otp_length stay readable, as do others ending in _hint, _type, _length, _rules and the like. A header is masked when it is authorization, cookie, location or another listed one, or its name contains key, auth, token, secret, password, passwd, cookie, session, signature or credential anywhere (x-keyauth included). A string in a body that is a URL (https://…?token=…) keeps its address, and each of its query and fragment parameters is masked by the query string's rule, and also when it is sig, signature, key, auth or session, so a payment or signed link is logged without its token. A masked value reads ******. The response bodies of GET /user/profile and of the directory feed are never captured.

Personal data. /user/otp-request logs the full phone number or email whenever it answers success without sending a code: an unknown or unusable account, a request inside the resend wait, the daily cap. It needs no sign-in, so anyone can make it write contacts to the log. A LOG_FILE is created with the process's default permissions, often readable by every local user. Treat the log as personal data: restrict who reads it, and keep it for a short time.

Third-Party Integrations

OAuth / Social Login

Leaving a provider’s CLIENT_ID blank disables it cleanly — its endpoints return a "provider not configured" error instead of attempting an outbound call. Social sign-in never creates an account: it reaches an existing one — by its <provider>_<id> shortname, by a provider id linked at an earlier sign-in, or the first time by a verified email — and is refused when none matches.

Embeddings (semantic search, opt-in)

When the pgvector extension is installed and EMBEDDING_API_URL is set, DMART embeds every entry on create/update and exposes POST /managed/semantic-search plus the dmart_semantic_search MCP tool. The endpoint is OpenAI-compatible.

Directory: LDAP, Replicas and OpenID Connect

DMART can serve its users as a read-only LDAP directory, keep a replica of another instance's users, and act as an OpenID Connect provider. All three are off by default.

A user's mailbox, mail_aliases and services are described under Mailbox, Aliases and Services.

The LDAP face

• Read-only. Every write, and the Password Modify operation, is refused with unwillingToPerform; users change through DMART. Only LDAPv3 simple binds are accepted, not SASL.
• The tree. Users are uid=<shortname>,ou=people,<base>, matched whatever the case. Groups are cn=<group>,ou=groups,<base> (groupOfNames). Service accounts bind as cn=<name>,ou=services,<base>. A user entry carries cn, sn, givenName, displayName, mail, mailAlias, mobile, authorizedService, entryUUID and memberOf, among others.
• Who reads what. An anonymous bind reads only the root DSE and the schema. A user bound with their password reads their own entry. Only the LDAP_SERVICE_ACCOUNTS, which must be bots binding from LDAP_TRUSTED_PEERS, read the whole directory.
• TLS. Once a certificate is set, a password bind over a connection still in cleartext gets confidentialityRequired (13), except from the trusted peers.
• Connections. At most 32 are open from one address outside the trusted peers, and 512 in all. One that has not bound idles out after 30 seconds, and a bound one after 15 minutes. A connection bound with a password is checked again every 5 minutes, and drops to anonymous after a password change or reset, the end of the account's sessions, or its deactivation, so a long-lived client must be ready to bind again.
• Failed binds. An address outside the trusted peers gets AUTH_RATE_LIMIT_PER_MINUTE failed binds a minute. While binds still being checked hold all of those that remain, a new bind waits up to 10 seconds. Once the minute's failures are spent, every bind gets busy (51) until the minute ends. A failed bind counts toward the account's lockout, except one that repeats one of the account's last two wrong passwords within the hour, which is how a device with a stale saved password looks.
• Configuration. LDAP_HOST must be an IP address. List the deployment's own directory clients, such as Postfix, Dovecot, webmail, Gitea and Dex, in LDAP_TRUSTED_PEERS: they bind for every user from one address.

Directory replicas

• Before the first sync, a replica answers every LDAP lookup and bind with unavailable (52), so a mail server defers mail rather than bouncing it. /health/ready answers 503 until then, and reports directory_replica_synced_at once ready.
• Once its copy is older than DIRECTORY_REPLICA_MAX_STALENESS_HOURS, binds answer unavailable, and lookups keep working.
• Lockout counters stay local to the replica, and a bind there does not upgrade an imported {SSHA} hash. The primary upgrades it at the owner's next sign-in on the primary, and the replica picks that up.
• Users edited on the replica are overwritten from the primary. Keep the replica's own HTTP API on loopback.

OpenID Connect clients

OIDC_CLIENTS_FILE holds an object with a clients list:

{"clients": [
  {"client_id": "gitea", "client_secret": "<32 or more random characters>", "name": "Gitea",
   "redirect_uris": ["https://git.example.com/user/oauth2/dmart/callback"], "services": ["gitea"]},
  {"client_id": "cli", "name": "A native app",
   "redirect_uris": ["http://127.0.0.1:8765/callback"]}
]}

• Keys are client_id, client_secret, name, redirect_uris and services. Any other key fails the load.
• A secret has at least 16 characters. A client without one is public, and must use PKCE with S256.
• Redirect URIs match exactly, and must be https, or http on a loopback address, with no fragment.
• services gates who may sign in: a user must hold one of them. Empty admits any active user.
• A bad file. A reload that fails keeps the previous list and logs why; at startup, a bad file stops the server.

With OIDC_ISSUER set, startup also requires OIDC_SIGNING_KEY_FILE, whose directory must exist (the key is created on first start), and an OIDC_CLIENTS_FILE that exists.

Channel Authentication

The channels file is a JSON array:

[
  {"name": "mobile_app", "keys": ["<random key>"], "allowed_api_patterns": ["^/user/", "^/public/"]}
]

• Patterns are regular expressions, matched anywhere in the path and ignoring case. Each is tried on the path as sent and without its trailing slash; for a request with no key, also with doubled slashes collapsed. A match is cut off after 100 ms and counts as no match. A pattern that does not compile is logged and dropped.
• With ENABLE_CHANNEL_AUTH=true:
  • a request with no x-channel-key is refused with 403 when any channel's pattern matches its path, and passes otherwise;
  • a key that no channel lists is refused with 403;
  • a known key passes only on a path one of its channel's patterns matches.
• /health is never gated.
• A missing or invalid file means no channels: requests without a key pass, and every request with one is refused.

Miscellaneous