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. An unknown key is ignored with a warning that names it and the key it was probably meant to be — at startup and in askr config-check, so run that after editing the file.

[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.

Ten seconds of queue latency is unremarkable; thirty means nothing is listening, which is why stall_secs defaults to 30. Raise it for an app whose queues are deliberately batchy, lower it to be told sooner. One threshold drives the watchdog log line, the warnings array in GET /api/status and the askr_queue_unattended metric together, so a dashboard cannot disagree with the log about whether a lane is stalled — see Admin.

root is the application these workers belong to, and with [[site]] you have to say it. Shared memory is namespaced per application, the namespace is derived from the docroot, and askr_queue_pop matches the namespaced key. A queue sidecar is one process with one namespace for its whole life, so it consumes exactly one application's jobs — set root to the same path as the [[site]] root of the application that dispatches them. If that is the top-level application, set it equal to [server] root: that is a valid and expected answer, it just has to be an answer. Without [[site]] there is only one application and the default is right.

Since 1.7.0 Askr refuses to start when [[site]] is configured together with a queue or scheduler sidecar and neither [queue] root nor [scheduler] root is set — it cannot tell which application the sidecar serves, and the error names the key to set. Guessing is what the release fixes: an instance whose jobs were dispatched by a [[site]] application accepted every job for six days and read none of them, with nothing in any log from the application's side. See Hosting.

[scheduler]

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

The scheduler sidecar is namespaced the same way as the queue workers and for the same reason. When both run for the same application — the usual case — [queue] root already covers it and there is no second line to write. Set [scheduler] root when the scheduler belongs to a different application than the queue workers, or when an instance runs the scheduler without queue workers at all; it is honoured independently of [queue] root, not merely as a fallback.

[[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. The same setting is what gives PHP the client in REMOTE_ADDR — see Behind a reverse proxy.

[[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.