Skip to content
df12 Productions Marrakesh Express Daemon
Docs · Configuration

Configuration

mxd uses OrthoConfig to merge settings from four sources in ascending priority: compiled defaults, .mxd.toml, environment variables prefixed MXD_, and CLI flags. Database backend selection is a compile-time choice via Cargo features.

Route map
Configuration
ConfigurationDatabase backends
Configuration

Configuration reference

Configuration fields

Each field can be set through any of the four configuration sources. The precedence order is fixed: CLI flags override environment variables, environment variables override the TOML file, the TOML file overrides compiled defaults.

Field CLI flag Env var Default Description
bind --bind MXD_BIND 0.0.0.0:5500 Socket address to listen on
database --database MXD_DATABASE mxd.db SQLite path or PostgreSQL connection string
argon2_m_cost --argon2-m-cost MXD_ARGON2_M_COST Argon2 default Memory cost for password hashing
argon2_t_cost --argon2-t-cost MXD_ARGON2_T_COST Argon2 default Time cost for password hashing
argon2_p_cost --argon2-p-cost MXD_ARGON2_P_COST Argon2 default Parallelism cost for password hashing

TOML configuration file

The TOML file is named .mxd.toml and searched in the current working directory. Keys match the field names above:

.mxd.toml 
bind = "0.0.0.0:6600"
database = "postgres://user:<password>@localhost/mxd"

File location: The TOML file must be in the current working directory. When mxd is launched from a different directory, place the file there or use environment variables or CLI flags instead.

Precedence order

CLI flags override environment variables. Environment variables override the TOML file. The TOML file overrides compiled defaults. That sequence defines the precedence order.

1

Compiled defaults

Lowest priority. Embedded in the binary.

2

.mxd.toml

File-based configuration in current directory.

3

Environment

Variables prefixed with MXD_

4

CLI flags

Highest priority. Always wins.

Usage examples

Using environment variables

bash 
export MXD_BIND="127.0.0.1:5501"
export MXD_DATABASE="postgres://mxd:${MXD_DB_PASSWORD}@db.example.com/mxd_prod"
mxd

Using CLI flags

bash 
mxd --bind 0.0.0.0:6600 --database mxd_production.db

Mixing sources

TOML file sets database path, environment variable overrides bind address, CLI flag overrides both for Argon2 memory cost:

.mxd.toml 
database = "mxd_local.db"
bash 
export MXD_BIND="0.0.0.0:7700"
mxd --argon2-m-cost 65536

Result: mxd binds to 0.0.0.0:7700 (from environment), uses mxd_local.db (from TOML), and sets Argon2 memory cost to 65536 (from CLI flag).

Database backends

Database backends

mxd compiles for exactly one backend at a time. The choice is made via Cargo features.

Compile-time selection

mxd compiles for exactly one backend at a time. The choice is made via Cargo features: sqlite (default) or postgres. Enabling both is a compile error. Enabling neither is also a compile error.

SQLite

The simplest deployment. The database is a single file. Migrations are embedded in the binary and run automatically at startup. WAL mode is enabled by default. Foreign key enforcement is enabled by default.

Recursive CTEs and json_each are used for news path resolution. The design calls for mxd to verify at startup that the bundled SQLite supports both features and exit with a diagnostic message rather than produce wrong results silently.

Startup verification

The design specifies that mxd queries the SQLite compile-time options to confirm recursive CTE and JSON support. If either is missing, the daemon refuses to start and logs which feature is absent, preventing runtime failures in news path traversal.

terminal 
cargo build --release
./target/release/mxd --database mxd.db

PostgreSQL

For concurrent access, connection pooling, and the ability to share the database between multiple processes. Build with --no-default-features --features postgres. Migrations are embedded and run automatically, same as SQLite.

terminal 
cargo build --release --no-default-features --features postgres
./target/release/mxd --database postgres://user:pass@localhost/mxd

Development helper

The pg-embed-setup-unpriv helper stages a PostgreSQL distribution with unprivileged ownership for development and testing. It requires no root access. 

cargo install --locked pg-embed-setup-unpriv
pg_embedded_setup_unpriv
make test

Install it once, run the setup, then make test will exercise both SQLite and PostgreSQL suites.

When to choose which

SQLite

  • ◆ Single-process deployment
  • ◆ Embedded systems
  • ◆ Development and testing
  • ◆ Small to medium deployments
  • ◆ Zero configuration required

PostgreSQL

  • ◆ Multi-process access
  • ◆ Connection pooling
  • ◆ Horizontal scaling
  • ◆ Large deployments
  • ◆ Shared database infrastructure