¶Configuration

Askr can be configured with CLI flags (see CLI) or a typed askr.toml file. The config file is the declarative source of truth — the thing tooling and the admin GUI edit — and is recommended for production.

askr config-check askr.toml     # validate + print resolved settings
askr serve --config askr.toml   # run (the file is authoritative)

When --config is given, the file provides everything; other serve flags are ignored.

A config file is the whole configuration. --config is not merged with the other flags — it replaces them. Askr refuses to start if you pass both, naming the flags that would have been ignored, because the alternative is a server that runs with settings you didn't choose and says nothing. Everything a flag can do has a key here.

¶askr.toml reference

A complete, commented example lives at examples/askr.toml. Unknown keys are rejected, so typos fail fast in config-check.

¶[server]

¶[worker]

Omit this whole section to run in per-request mode. Present it to enable worker mode (boot once, serve many — see Worker mode).

¶[tls]

Enabling TLS negotiates HTTP/2 or HTTP/1.1 via ALPN and sets HTTPS=on in $_SERVER (so Laravel emits secure cookies). Certs must be X.509 v3.

Auto-TLS (ACME / Let's Encrypt) has its own section — see [acme]. Do not set both: [tls] is a certificate you supply, [acme] is one Askr fetches.

¶[acme]

[server]
listen = "0.0.0.0:443"
root = "/var/www/example.com/public"
force_https = true
trusted_proxies = ["172.17.0.1"]   # file-only, which is why [acme] had to exist

[acme]
enabled = true
domains = ["example.com", "www.example.com"]
email = "admin@example.com"
dir = "/var/lib/askr/acme"

One long-lived listener on http answers challenges and 308s everything else, so a certificate can be issued and HTTP redirected without the two fighting over port 80.

Askr refuses to start rather than let a mistake here become a site quietly serving plain HTTP: domains without enabled, enabled without domains, [acme] alongside [tls], and a wildcard domain (HTTP-01 cannot validate one) are all errors.

Until 1.4.10 ACME was flags-only. Since --config is the whole configuration rather than a set of defaults, that made auto-TLS and a config file mutually exclusive — and combinations like "auto-TLS behind a proxy" unreachable, because trusted_proxies has never had a flag.

¶[admin]

¶[queue]

Run queue workers in the same binary, supervised alongside the web workers.

slots is required when workers is set, and Askr refuses to start without it. The ring is only mapped when slots are configured; without it every push returns 0, Laravel does not check that, and queued jobs are discarded silently — which is how a live site stopped sending mail with nothing in any log.

¶[scheduler]

Run the scheduler (built-in cron) in the same binary.

¶[[sidecar]]

Supervise arbitrary external commands (array of tables; respawned if they die). Run via sh -c in $ASKR_APP_BASE. Used for e.g. Inertia SSR — see Docker.

[[sidecar]]
command = "node bootstrap/ssr/ssr.mjs"

¶[[redirect]]

Declarative host redirects (array of tables), evaluated before any dispatch. from matches the Host header exactly or as a *.suffix glob; the request path + query are preserved; status defaults to 308 (permanent, method-preserving).

[[redirect]]
from = "www.domene.no"
to   = "https://domene.no"     # → https://domene.no/<path>?<query>

[[redirect]]
from   = "*.old.no"
to     = "https://ny.no"
status = 301

For plain-HTTP→HTTPS across all hosts, use [server] force_https = true instead.

¶[[site]]

Virtual hosts — serve several domains/apps from one Askr instance, routed by the Host header. Each site has its own document root + front controller; hosts match exactly or as a *.suffix glob. A request whose Host matches no site falls back to [server] root.

[server]
listen = "0.0.0.0:443"
root   = "/var/www/default/public"   # fallback

[[site]]
hosts = ["domene.no", "*.domene.no"]
root  = "/var/www/domene/public"

[[site]]
hosts = ["annet.no"]
root  = "/var/www/annet/public"
front = "index.php"

Static files are served from the matching site's root in any mode. Full dynamic dispatch (a different app per host) works in per-request mode — each request runs that site's front controller fresh. In worker mode the single booted app is fixed, so give each app its own instance (or route by host inside the worker script) until per-site worker pools land. Combine with [[redirect]] for per-host www→apex.

¶[cache]

Enable the shared-memory cache (askr_cache_*, and the Laravel driver). See Cache.

¶[[ratelimit]]

Rate limits enforced in the Rust layer before PHP is woken, with token buckets in shared memory (so a limit spans the whole worker fleet). First match wins. See Features.

[[ratelimit]]
path = "/login"
limit = 5
window = 300

Refused requests get 429 with Retry-After. Reserved /askr/* endpoints are exempt. Set [server] trusted_proxies when running behind a load balancer, or X-Forwarded-For is ignored and every client shares one bucket.

¶[[cache.rule]]

Per-path cache policy, applied without touching the app. First match wins — put specific rules above the catch-all. See Features.

[[cache.rule]]
path = "/admin/*"
action = "pass"

[[cache.rule]]
path = "/static/*"
ttl = 86400
force = true

Cache-key normalisation example — tracking parameters and analytics cookies stop fragmenting the cache:

[cache]
response_slots = 512
strip_query_params = ["utm_*", "gclid", "fbclid", "_ga"]
ignore_cookies = ["_ga", "_gid", "_fbp"]
vary_user_agent = false

¶[broadcast]

Enable askr_broadcast() and the SSE endpoint. See Broadcasting.

¶[pusher]

Pusher-compatible WebSocket + HTTP trigger (drop-in Reverb). Auto-enables the broadcast ring.

¶[record]

¶[reload]

¶Example

[server]
listen = "0.0.0.0:8000"
root = "/var/www/app/public"
workers = "auto"
max_requests = 1000
max_body_size = "16M"

[worker]
script = "/opt/askr/examples/laravel-worker.php"
app_base = "/var/www/app"
ini = "zend_extension=/opt/askr/vendor/php-build/install/lib/php/extensions/no-debug-non-zts-20240924/opcache.so\nopcache.enable=1\nopcache.validate_timestamps=0"

[tls]
cert = "/etc/askr/cert.pem"
key = "/etc/askr/key.pem"

[admin]
listen = "127.0.0.1:9000"

¶Environment variables

¶opcache

PHP 8.5 compiles OPcache into libphp and auto-registers it, so there is no zend_extension line — just enable it (and JIT) in the INI:

[worker]
ini = "opcache.enable=1\nopcache.enable_cli=1\nopcache.validate_timestamps=0\nopcache.jit=tracing\nopcache.jit_buffer_size=128M"

validate_timestamps=0 maximises throughput (no stat() per file); pair it with a SIGHUP reload on deploy so fresh workers recompile the new code. opcache.jit enables the JIT (on by default in this build). askr-run.sh sets sensible defaults automatically.