Configuration

How Environment Files Load

Soli reads environment variables from the process, then loads .env, then loads .env.{APP_ENV} when APP_ENV is set. Environment-specific files override .env, except variables listed in SOLI_PROTECT_ENV.

APP_ENV=development
SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=myapp_development

Keys must match [A-Za-z_][A-Za-z0-9_]*. Values cannot contain \0, \r, or \n — entries with control characters are skipped at load time with a warning on stderr. This avoids HTTP-header-split / log-injection vectors when an env value flows downstream into responses or structured logs.

The files are read from the app folder passed to soli serve. When serving a bundle (soli serve app.soli), they are read from the directory containing the .soli file — dotfiles are never included in a bundle, so ship the .env alongside it.

Application Environment

Server And Development

Health checks and graceful shutdown

Two endpoints let an orchestrator or load balancer see the server's lifecycle. Both are plain text, need no authentication, and are always available — there is nothing to enable.

The distinction matters. A shutting-down process is perfectly healthy — it just does not want new work. If /_health failed during shutdown, an orchestrator would restart a container that was already exiting cleanly. Point liveness probes at /_health and readiness probes at /_ready.

What happens on SIGTERM

On SIGTERM or SIGINT the server drains rather than cutting requests off:

1. /_ready starts answering 503 draining, so the load balancer stops routing here.
2. New requests get 503 Server shutting down with Connection: close. Probes still answer.
3. Requests already in flight run to completion and return their real response.
4. Once the last one finishes — or SOLI_SHUTDOWN_GRACE_SECS elapses — the process exits 0.

A second signal skips the wait and exits immediately. The default 25s sits just under Kubernetes' default 30s terminationGracePeriodSeconds, so the process exits on its own rather than being SIGKILLed. If you raise one, raise both.

# Kubernetes
livenessProbe:
  httpGet: { path: /_health, port: 3000 }
readinessProbe:
  httpGet: { path: /_ready, port: 3000 }
terminationGracePeriodSeconds: 30    # must exceed SOLI_SHUTDOWN_GRACE_SECS

Parsing And Security Limits

Bundle protection

Used when serving an encrypted / protected .soli bundle (see Encrypted & Protected Bundles). Read at both soli build --encrypt/--protect and soli serve app.soli, and may live in the .env next to the bundle. Distinct from SOLI_ENCRYPTION_KEY, which encrypts model fields.

Production logging (SOLI_LOG)

The AQL query log, the outgoing HTTP log, and the middleware/view/phase timing breakdown normally only feed the dev bar under --dev. SOLI_LOG turns those same channels on in production and prints them to stdout as an indented block under each request's access line — so you can debug a slow or failing route on a live server without redeploying in dev mode (which would also disable the VM, enable hot-reload, and inject the bar).

Set SOLI_LOG_FORMAT=json for one NDJSON object per request (and per production error on stderr) so a log shipper can ingest them. Detail channels become nested arrays on the same object; trace_id / span_id appear when OpenTelemetry is on. Full operator guide: Observability.

# Just the access line (same as SOLI_REQUEST_LOG=1)
SOLI_LOG=access soli serve

# Queries + outgoing HTTP for the whole app
SOLI_LOG=query,http soli serve

# Everything
SOLI_LOG=all soli serve

A request with SOLI_LOG=query,http,timing prints:

[LOG] GET /posts - 200 (12.480ms)
  db: 2 queries (8.210ms)
    (5.110ms) FOR p IN posts FILTER p.published == @v0 RETURN p binds={"v0":true}
    (3.100ms) FOR c IN comments FILTER c.post_id == @v0 RETURN c binds={"v0":"abc"}
  http: 1 call (2.000ms)
    (2.000ms) GET https://api.example.com/feed -> 200
  timing:
    middleware auth (0.420ms)
    view posts/index (3.050ms)
      view posts/_card (1.200ms)

The whole block is written with a single println! so concurrent worker threads never interleave their output. Bind variables and HTTP URLs are scrubbed of secret-bearing values before they reach the log.

Slow-request logging (SOLI_SLOW_REQUEST_MS)

SOLI_LOG=all prints a block for every request — too noisy to leave on in production. SOLI_SLOW_REQUEST_MS instead emits the full detail block only for requests whose total time (queue wait + handler) crosses the threshold, and nothing at all for fast ones:

# Log a full breakdown only for requests slower than 100ms
SOLI_SLOW_REQUEST_MS=100 soli serve

[SLOW] GET /gather/map - 200 (412.480ms + 0.320ms queue)
  db: 3 queries (398.210ms)
    (395.110ms) FOR p IN pins FILTER p.board == @v0 RETURN p binds={"v0":"x"}
    ...
  timing:
    view gather/map (10.050ms)

The access line shows handler time plus the time the request waited in the worker queue before being picked up, so a request stuck behind a busy worker is distinguishable from a genuinely slow handler. It composes with SOLI_LOG: explicitly requested channels still print for every request; the threshold adds the [SLOW] block on top.

OpenTelemetry tracing

Production can join a distributed trace without a heavyweight SDK: W3C traceparent, OTLP/HTTP JSON export of the same span tree the dev-bar flamegraph builds. Enable with SOLI_OTEL=1 or any OTEL_EXPORTER_OTLP_* endpoint. Operator guide (metrics, log fields, span kinds, limits): Observability.

SOLI_OTEL=1 soli serve
# or
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 OTEL_SERVICE_NAME=myapp soli serve

DB connection keep-warm

Pooled SoliDB connections idle out after SOLI_DB_POOL_IDLE_SECS. On a quiet server, a request arriving after a longer gap used to pay a fresh DNS + TCP (+ TLS for remote hosts) connect mid-request — visible as intermittent latency spikes. When a DB is configured, soli serve now runs a periodic read-only RETURN 1 ping that keeps a live connection pooled at all times (and pre-warms the model DB at boot). Disable it with SOLI_DB_KEEP_WARM=0.

The ping runs on its own thread, and with one connection pool per worker it can only refresh its own — so a worker's connection is instead kept inside the 25s idle window described above, short enough that the pool retires it before SoliDB's 30s idle close. A worker idle longer than that pays one reconnect on its next query, which is the fresh-connect cost the ping avoids elsewhere.

Keeping memory low

soli serve runs a pool of worker threads in one process, and each worker holds its own copy of the parsed app plus the full builtin surface (Rc-based values can’t be shared across threads). So baseline RSS scales with the worker count and — for apps with lots of code or large in-memory data such as i18n locale tables — with the size of that app.

Within a worker the builtin surface is built once and shared as the enclosing scope of the interpreter’s globals, the template engine’s environment and the view helpers’ closure; those three used to be separate full registries. Don’t expect that to show up in your RSS — a registry turns out to be a few hundred KB, so removing two of them per thread sits below the noise of an ordinary measurement. The levers below are what actually move the number.

Measuring it at all takes more care than it looks. ps -o rss= cannot separate a process’s own heap from the file-backed pages every soli process shares; Pss_Anon from /proc/<pid>/smaps_rollup can, but counts only resident pages, so on a swapping machine a process reads as smaller the more pressure the box is under — add SwapPss. Transparent huge pages move anonymous RSS by tens of MiB between identical runs, so take a median of several. And compare two binaries by alternating them in one session, never by lining up two sweeps taken minutes apart: machine drift lands entirely on whichever ran later. scripts/mem-probe.sh in the repository does all of this, --ab included.

The levers, cheapest first:

Slim binary (Cargo features)

cargo install / CI use the default feature set so published binaries match a full product build. Optional subsystems can be dropped at compile time when you build from source:

SoliDB (HTTP) always stays linked. SoliDB-only install without PASETO or SQL clients:

cargo install --path . --locked --no-default-features \
  --features embedding,llm,codegraph

Postgres only (no MySQL or SQLite client, no PASETO):

cargo install --path . --locked --no-default-features \
  --features embedding,llm,codegraph,postgres

SQLite only — the client is compiled in, so the host needs no libsqlite3:

cargo install --path . --locked --no-default-features \
  --features embedding,llm,codegraph,sqlite

If the binary was built without an adapter and you set SOLI_DB_ADAPTER=postgres (or a database.toml entry for it), boot fails with a rebuild hint rather than a missing symbol. The Paseto class is simply not registered when the paseto feature is off.

The boot process also builds one extra interpreter to register the shared route/model/controller/template registries before workers start; it is now reclaimed immediately after boot rather than parked for the process lifetime.

Hardening

Knobs that control how the request edge handles untrusted input. See the Server Hardening page for the full story.

Database

Sessions

Jobs

Cache And KV

S3

Deploy And Internals

Runtime Overrides

The hardening knobs above also have function equivalents that override the env-driven default at runtime — useful when a single action needs a different limit, or when test setup needs to flip the gate without re-reading the environment.

Soli loads config/application.sl once at boot, before config/routes.sl, which makes it the natural place for app-wide startup config:

# Trust X-Forwarded-* only behind a trusted proxy.
enable_trust_proxy()

# Always emit Secure session cookies — appropriate when the deployment
# is always on TLS but the proxy doesn't forward X-Forwarded-Proto.
enable_force_secure_cookies()

# Raise the default 8 MiB body cap when an app needs larger uploads.
set_max_body_size(32 * 1024 * 1024)