Server Configuration

Minimal is configured through a single config.yml file on the server. This page explains every section and field.

---

Service

Controls the core runtime behaviour of the Minimal server.

service:
  name: minimal
  port: "3045"
  version: "0.0.1"
  environment: "development"
  server_key: "minimal_oJdz7w8M************************4ue12E7R"
  log_level: "debug"
  debug_mode: true
  cors_enabled: false
  middleware_enabled: false
  trace_to_stdout: false
  shutdown_timeout: 30
  otel_endpoint: "localhost:4317"
  timeout:
    enable: true
    timeout: 10
    initial_interval: 1
    max_interval: 30
    max_elapsed_time: 120

Field	Type	Description
name	string	Internal service name — used in logs and traces
port	string	Port the Minimal server listens on
version	string	Service version — informational only
environment	string	development or production — affects log verbosity
server_key	string	Server-to-server auth key — used only for System APIs (org/project creation). Never expose this to clients.
log_level	string	Logging verbosity — debug, info, warn, error
debug_mode	boolean	Enables detailed request/response logging — disable in production
cors_enabled	boolean	Enable built-in CORS headers. Set to false if your gateway or nginx handles CORS
middleware_enabled	boolean	Enable built-in middleware chain — set to false if handled upstream
trace_to_stdout	boolean	Print OpenTelemetry traces to stdout — useful for local debugging
shutdown_timeout	integer	Seconds to wait for in-flight requests to complete on graceful shutdown
otel_endpoint	string	OpenTelemetry collector endpoint for distributed tracing

Timeout

Controls retry and timeout behaviour for outbound operations:

Field	Type	Description
enable	boolean	Enable timeout enforcement
timeout	integer	Request timeout in seconds
initial_interval	integer	Initial retry interval in seconds
max_interval	integer	Maximum retry backoff interval in seconds
max_elapsed_time	integer	Total time in seconds before retries are abandoned

Production Checklist

• Set environment: production
• Set debug_mode: false
• Set log_level: info or warn
• Ensure server_key is loaded from a secrets manager, not hardcoded

---

Definition Store

The internal database where Minimal stores its own configuration — org records, project records, space metadata, and table definitions. This is not your application database.

definition_store:
  type: mysql
  port: 3306
  username: minimalist
  password_source: file
  password: 'you****'
  host: localhost
  schema: minimal
  connect_timeout_secs: 30
  idle_timeout_secs: 600
  max_open_connections: 60
  max_idle_connections: 25
  default_query_timeout_secs: 10
  mode: single
  encrypt_database: true
  encryption_key_source: file
  encryption_key: 'password'

Field	Type	Description
type	string	Database engine — mysql, postgres, mariadb, clickhouse
port	integer	Database port — 3306 for MySQL/MariaDB, 5432 for Postgres, 9000 for ClickHouse
username	string	Database username
password_source	string	Where to read the password from — file or env
password	string	Password value (when password_source: file)
host	string	Database host
schema	string	Database/schema name Minimal uses for its own tables
connect_timeout_secs	integer	Timeout in seconds to establish a new connection
idle_timeout_secs	integer	How long an idle connection is kept alive in the pool
max_open_connections	integer	Maximum concurrent open connections
max_idle_connections	integer	Maximum idle connections held in the pool
default_query_timeout_secs	integer	Maximum time a single query can run before being cancelled
mode	string	single for one node — cluster for multi-node setups
encrypt_database	boolean	Enable encryption at rest for definition data
encryption_key_source	string	Where to read the encryption key — file or env
encryption_key	string	Encryption key value (when encryption_key_source: file)

Supported Database Types

Value	Engine	Default Port
mysql	MySQL	3306
mariadb	MariaDB	3306
postgres	PostgreSQL	5432
clickhouse	ClickHouse	9000

danger

The definition store is Minimal's own internal database — do not point it at your application database. Use a dedicated schema (e.g. minimal) on a separate user with limited privileges.

---

Cache Settings

Controls how long Minimal caches table definitions and schema metadata in memory.

cache_settings:
  ttl_seconds: 1800

Field	Type	Description
ttl_seconds	integer	Time in seconds before cached definitions expire and are re-read from the definition store. Default is 1800 (30 minutes)

tip

If you frequently update table definitions or add new projects during development, lower this to 60 so changes are picked up faster. In production, 1800 or higher reduces load on the definition store.

---

Auto API

Controls the behaviour of the automatically generated REST endpoints.

auto_api:
  roles: [admin, power, wheel]
  avg_columns_per_table: 20
  indexing_page_size: 100
  max_rows_per_page: 100

Field	Type	Description
roles	list of strings	Roles permitted to access Auto API endpoints. Values must match what your gateway sends in X-User-Roles
avg_columns_per_table	integer	Used to pre-allocate memory for query building — set to the average number of columns across your tables
indexing_page_size	integer	Number of rows fetched per page when Minimal indexes table metadata
max_rows_per_page	integer	Hard limit on rows returned per request — the ps param cannot exceed this value

caution

max_rows_per_page is a server-side hard cap. If a client sends ps=500 and this is set to 100, the API returns at most 100 rows — no error is raised, the value is silently capped.