Skip to content

FastAPI settings ​

Every setting of the FastAPI host, with its default, its bounds and what it does. The FastAPI page shows how to include the routers; the wire page describes the requests and answers they serve.

Where settings come from ​

DatumSettings reads the settings from three sources. The first source that names a setting wins.

  1. Keyword arguments to DatumSettings(...).
  2. Environment variables.
  3. A TOML file named by DATUM_CONFIG_FILE. The variable must name an existing file, or the start stops.

A name in the environment is DATUM_ plus the setting's path in capitals, with __ between levels: datum.runtime.validation.time_limit is DATUM_RUNTIME__VALIDATION__TIME_LIMIT. Names are matched without regard to case, and an empty value counts as unset. A list or a mapping is written as JSON text (DATUM_FORMS__LOCATIONS='["forms/*.json"]'), or a mapping one key at a time (DATUM_WEB__THROTTLE__LIMITS__SUBMIT=10). A key written in the environment comes out in lower case, so a binding id or a form key with capitals belongs in the TOML file. Values from the sources are merged level by level, so the environment can change one setting the TOML file also sets.

In the TOML file the tables are the setting paths without the leading datum:

toml
[web.api.endpoints]
submissions = true
validate = true

[runtime.validation]
time_limit = 3
memory = "64MiB"

[web.throttle]
limit = 30

[forms]
locations = ["forms/*.json"]

The same settings in the environment:

sh
export DATUM_WEB__API__ENDPOINTS__SUBMISSIONS=true
export DATUM_WEB__API__ENDPOINTS__VALIDATE=true
export DATUM_RUNTIME__VALIDATION__TIME_LIMIT=3
export DATUM_RUNTIME__VALIDATION__MEMORY=64MiB
export DATUM_WEB__THROTTLE__LIMIT=30
export DATUM_FORMS__LOCATIONS='["forms/*.json"]'

python -m datum_core.config.schema --out <path> writes the JSON Schema of every setting to a file, or into a directory as datum-settings.schema.json. The same schema ships inside datum-core.

A value that cannot work stops the start and names the setting: a number outside its bounds, a word that is not one of the allowed ones (the message lists them and offers the closest), a missing file, a password that is too short. A DATUM_ variable that matches no setting is warned about (datum.W007); with datum.strict_env it stops the start instead. The next section lists the value forms and the rules that tie settings together.

Value forms and rules across settings ​

FormWhat it accepts
SecondsA number (5, 0.05), a numeric string, or an ISO 8601 duration (PT5S). A boolean is refused.
SizeA whole number of bytes, or a size such as 32MiB (binary) or 32MB (decimal). A boolean is refused.
WordOne of a closed set, matched without regard to case.
SecretNever shown in a log, an error or a dump. A secret that sets a minimum length refuses a shorter value and reports the length only.
Credential addressA URI that may hold credentials. Its user-info is hidden in logs and in the JSON dump.

Rules that tie several settings together, each of which stops the start:

  • datum.runtime.qjs_sha256 needs datum.runtime.qjs_path.
  • A signing key (datum.pdf.signing and datum.tsa.signer) of type PKCS12 needs pkcs12_file and refuses key_password, key_file and cert_file. A key of type PEM needs key_file and cert_file and refuses pkcs12_file, pkcs12_password and friendly_name. An empty password counts as unset. The files are read once at start, at most 1 MiB each, so a renewed key takes a restart. The first certificate must be the certificate of the private key, the key must be RSA (2048 bits or more) or ECDSA P-256 or P-384, and a friendly_name must equal the friendly name of the key's certificate in the store; it checks, it does not choose.
  • datum.tsa.signer.self_signed refuses a named key file as well.
  • datum.tsa.enabled needs datum.tsa.policy, and every policy is checked as an OID.
  • datum.tsa.client_store = sql with access = clients needs a client store passed to Datum(tsa_client_store=...).
  • The timestamp client of a PDF signature needs an http or https address with a host. basic_user and basic_password are set together or not at all, and basic_user holds no colon. A bearer token, Basic credentials or user-info in the address are refused for an http address that is not loopback.
  • A throttle storage that is not memory needs datum.web.throttle.key_salt (datum.E005).
  • Each entry of datum.web.throttle.limits is at least 1.
  • Every binding named in datum.bindings must be in the catalogue, and every PDF theme a used binding suggests (other than datum-pdf) must be supplied under datum.bindings.pdf_themes.
  • datum.silenced_checks names only known check ids, and never an ERROR check.
  • A PDF or timestamp capability that is on needs its extra installed (datum-core[pdf], datum-core[timestamp]).

datum ​

The top of the tree.

SettingEnvironment variableDefaultMeaning
datum.enabledDATUM_ENABLEDtrueBoolean. When false, every Datum router adds no routes.
datum.strict_envDATUM_STRICT_ENVfalseBoolean. When true, a DATUM_ variable that names no setting stops the start instead of warning (datum.W007).
datum.silenced_checksDATUM_SILENCED_CHECKSnoneList of check ids to leave out of the log, such as ["datum.W003"]. Only INFO and WARNING checks can be silenced; an unknown id or an ERROR id is refused.
datum.workers_expectedDATUM_WORKERS_EXPECTEDunsetWhole number, at least 1. The number of worker processes the deployment runs. Unset, the host reads WEB_CONCURRENCY as a hint, else 1. The memory check (datum.W002) and the builder's shared-store rule (datum.E002) read it.

datum.runtime ​

The program runtime: the sandbox that runs the form program and the PDF program.

SettingEnvironment variableDefaultMeaning
datum.runtime.engineDATUM_RUNTIME__ENGINEwasmtimeText. The id of the engine provider. An unknown or unavailable id stops the start.
datum.runtime.fail_fastDATUM_RUNTIME__FAIL_FASTtrueBoolean. When true, a runtime that cannot be brought up stops the start.
datum.runtime.warm_up_runsDATUM_RUNTIME__WARM_UP_RUNS3Whole number, 0 or more. Runs made at start to warm the engine. The host always makes at least one, so 0 behaves as 1.
datum.runtime.shutdown_graceDATUM_RUNTIME__SHUTDOWN_GRACE10 sSeconds, 0 or more. How long shutdown waits for runs in flight. Keep it below the process manager's own timeout.
datum.runtime.startup_budgetDATUM_RUNTIME__STARTUP_BUDGET30 sSeconds, at least 0.001. The time allowed for the runtime to start. A start that runs past it fails with datum.E004.
datum.runtime.tickDATUM_RUNTIME__TICK0.05 sSeconds, at least 0.001. The resolution of the clock the runs share.
datum.runtime.work_dirDATUM_RUNTIME__WORK_DIRunsetText. A directory local to the container for the runtime's working files. Unset uses the system temporary directory.
datum.runtime.stop_graceDATUM_RUNTIME__STOP_GRACE5 sSeconds, 0 or more. How long the engine waits when it stops a run.
datum.runtime.max_straysDATUM_RUNTIME__MAX_STRAYS0Whole number, 0 or more. Stray runs tolerated. 0 means one per CPU, at least 2.
datum.runtime.worker_threadsDATUM_RUNTIME__WORKER_THREADS0Whole number, 0 or more. The worker threads the limiter allows for runs plus hooks in flight. 0 means 2 times the slots plus 2, where the slots are the validation and PDF slots together. To size it yourself use slots plus the slots times hook time on a thread over run time, rounded up, plus 2; blocking work on the worker thread (a synchronous store, the timestamp client) counts as hook time. A call that gets no thread within datum.runtime.validation.wait answers 503 server.busy.
datum.runtime.qjs_pathDATUM_RUNTIME__QJS_PATHunsetText. The path of your own copy of qjs-wasi.wasm. Unset uses the packaged, pinned module.
datum.runtime.qjs_sha256DATUM_RUNTIME__QJS_SHA256unsetText, 64 hexadecimal characters. The SHA-256 of your own copy. It needs qjs_path.
datum.runtime.verify_max_bytesDATUM_RUNTIME__VERIFY_MAX_BYTES20MiBSize. The largest PDF the verify route reads; a larger one answers 413. A value outside 1 MiB to 100 MiB is moved to the nearest bound with datum.W008.

datum.runtime.validation ​

The budgets of one validation run. Each value outside its bounds is moved to the nearest bound with datum.W008.

SettingEnvironment variableDefaultMeaning
datum.runtime.validation.time_limitDATUM_RUNTIME__VALIDATION__TIME_LIMIT5 sSeconds, more than 0. The time limit of a run. Bounds 0.001 s to 60 s.
datum.runtime.validation.memoryDATUM_RUNTIME__VALIDATION__MEMORY32MiBSize. The memory of a run. Bounds 4 MiB to 1 GiB. A value below what the runtime module needs to start is an error (datum.E003), never clamped up.
datum.runtime.validation.concurrencyDATUM_RUNTIME__VALIDATION__CONCURRENCY0Whole number, 0 or more. Concurrent runs. 0 means one per CPU. At most 64.
datum.runtime.validation.waitDATUM_RUNTIME__VALIDATION__WAIT2 sSeconds, 0 or more. How long a run waits for a slot before the answer is 503. At most 10 s.

datum.runtime.pdf ​

The budgets of one PDF run, on the same rules.

SettingEnvironment variableDefaultMeaning
datum.runtime.pdf.time_limitDATUM_RUNTIME__PDF__TIME_LIMIT60 sSeconds, more than 0. The time limit of a run. Bounds 0.001 s to 300 s.
datum.runtime.pdf.memoryDATUM_RUNTIME__PDF__MEMORY256MiBSize. The memory of a run. Bounds 32 MiB to 4 GiB. A value below what the runtime module needs to start is an error (datum.E003).
datum.runtime.pdf.concurrencyDATUM_RUNTIME__PDF__CONCURRENCY0Whole number, 0 or more. Concurrent runs. 0 means the smaller of 2 and the CPUs. At most 64.
datum.runtime.pdf.waitDATUM_RUNTIME__PDF__WAIT2 sSeconds, 0 or more. How long a run waits for a slot before the answer is 503. At most 10 s.

datum.runtime.programs ​

SettingEnvironment variableDefaultMeaning
datum.runtime.programs.sandboxDATUM_RUNTIME__PROGRAMS__SANDBOXunsetText. The path of the form program. Unset uses the packaged program, which is still checked against its digest. A path that cannot be read stops the start.
datum.runtime.programs.pdfDATUM_RUNTIME__PROGRAMS__PDFunsetText. The path of the PDF program, on the same terms.

datum.host ​

Options the form program reads on every run.

SettingEnvironment variableDefaultMeaning
datum.host.formula_errorsDATUM_HOST__FORMULA_ERRORSfailWord: fail or warn. What a formula that cannot be evaluated does.
datum.host.risky_patternsDATUM_HOST__RISKY_PATTERNSrefuseWord: refuse or allow. What a regular expression that repeats a repeat does.
datum.host.time_zoneDATUM_HOST__TIME_ZONEthe process zoneText, an IANA zone name such as America/Toronto or UTC. The zone for today() and clock rules. The default is the process zone, read once; when it cannot be read the host uses UTC and warns (datum.W010).
datum.host.unknown_fieldsDATUM_HOST__UNKNOWN_FIELDSstripWord: strip, keep or reject. What an answer with no component in the form does.
datum.host.log_levelDATUM_HOST__LOG_LEVELwarnWord: off, error, warn, info or debug. How much of a run's log is kept and relayed.

datum.submissions.idempotency ​

SettingEnvironment variableDefaultMeaning
datum.submissions.idempotency.memory_sizeDATUM_SUBMISSIONS__IDEMPOTENCY__MEMORY_SIZE10000Whole number, 16 to 10,000,000. Receipts the in-memory receipt store keeps.

datum.forms ​

SettingEnvironment variableDefaultMeaning
datum.forms.locationsDATUM_FORMS__LOCATIONS["datum/forms/*.json"]List of text. Paths and glob patterns of the form definition files, or package:<pkg>/<glob> for files inside an installed package. A location with no glob character names one file. Each file's id is its form key. A file that cannot be read, is not a JSON object, has no valid id, or repeats an id stops the start; a location that matches nothing is a warning in the datum.forms log. The files are read only when the definition route or the builder is on.

datum.forms.snapshots ​

SettingEnvironment variableDefaultMeaning
datum.forms.snapshots.max_entriesDATUM_FORMS__SNAPSHOTS__MAX_ENTRIES500Whole number, at least 1. Snapshots the in-memory store keeps.
datum.forms.snapshots.public_copy_cache_sizeDATUM_FORMS__SNAPSHOTS__PUBLIC_COPY_CACHE_SIZE256Whole number, at least 1. Public copies of a definition kept by hash.

datum.forms.translations ​

SettingEnvironment variableDefaultMeaning
datum.forms.translations.max_entriesDATUM_FORMS__TRANSLATIONS__MAX_ENTRIES1000Whole number, at least 1. The number of forms the in-memory translation store holds catalogues for.

datum.forms.data_sources ​

SettingEnvironment variableDefaultMeaning
datum.forms.data_sources.timeoutDATUM_FORMS__DATA_SOURCES__TIMEOUT15 sSeconds, at least 0.001. One deadline for all the data-source calls made while building a snapshot.
datum.forms.data_sources.max_threadsDATUM_FORMS__DATA_SOURCES__MAX_THREADS16Whole number, at least 1. Threads for data-source providers that are plain (synchronous) functions.

datum.forms.cache ​

SettingEnvironment variableDefaultMeaning
datum.forms.cache.definitionDATUM_FORMS__CACHE__DEFINITIONno-storeText. The Cache-Control header of a definition answer.

datum.web.api ​

SettingEnvironment variableDefaultMeaning
datum.web.api.max_body_sizeDATUM_WEB__API__MAX_BODY_SIZE1MiBSize, at least 1 byte. The largest request body. It is also the largest document the services read.
datum.web.api.problem_detailsDATUM_WEB__API__PROBLEM_DETAILSfalseBoolean. When true, errors are answered as RFC 9457 problem details.
datum.web.api.busy_retry_afterDATUM_WEB__API__BUSY_RETRY_AFTER5Whole seconds, 1 to 3600. The Retry-After of a busy answer.
datum.web.api.correlation_headerDATUM_WEB__API__CORRELATION_HEADERX-Request-IDText, an HTTP header name. The header that names a request in the logs.

datum.web.api.endpoints ​

One switch per endpoint. Every endpoint is off until its switch is set to true. A router adds a route only when its switch is on.

SettingEnvironment variableDefaultMeaning
datum.web.api.endpoints.submissionsDATUM_WEB__API__ENDPOINTS__SUBMISSIONSfalseBoolean. POST /api/submissions.
datum.web.api.endpoints.validateDATUM_WEB__API__ENDPOINTS__VALIDATEfalseBoolean. POST /api/submissions/validate.
datum.web.api.endpoints.testDATUM_WEB__API__ENDPOINTS__TESTfalseBoolean. POST /api/submissions/test.
datum.web.api.endpoints.inspectDATUM_WEB__API__ENDPOINTS__INSPECTfalseBoolean. Definition inspection, POST /api/inspect.
datum.web.api.endpoints.definitionDATUM_WEB__API__ENDPOINTS__DEFINITIONfalseBoolean. GET /api/forms/{key}/definition.
datum.web.api.endpoints.data_sourcesDATUM_WEB__API__ENDPOINTS__DATA_SOURCESfalseBoolean. GET /api/data-sources/{id}.
datum.web.api.endpoints.pdfDATUM_WEB__API__ENDPOINTS__PDFfalseBoolean. POST /api/pdf.
datum.web.api.endpoints.fillDATUM_WEB__API__ENDPOINTS__FILLfalseBoolean. POST /api/pdf/fill.
datum.web.api.endpoints.signDATUM_WEB__API__ENDPOINTS__SIGNfalseBoolean. POST /api/pdf/sign.
datum.web.api.endpoints.verifyDATUM_WEB__API__ENDPOINTS__VERIFYfalseBoolean. POST /api/pdf/verify.
datum.web.api.endpoints.certificateDATUM_WEB__API__ENDPOINTS__CERTIFICATEfalseBoolean. The signing certificate route, GET /api/server/certificate.

datum.web.throttle ​

Request throttling. Without datum.web.throttle.limits, one limit and one window apply to every kind of request.

SettingEnvironment variableDefaultMeaning
datum.web.throttle.enabledDATUM_WEB__THROTTLE__ENABLEDtrueBoolean. Throttle requests.
datum.web.throttle.limitDATUM_WEB__THROTTLE__LIMIT60Whole number, at least 1. Requests per window.
datum.web.throttle.windowDATUM_WEB__THROTTLE__WINDOW60 sSeconds, at least 1. The length of the window.
datum.web.throttle.byDATUM_WEB__THROTTLE__BY["ip", "form"]List of words: ip, form, principal; at least one. What a throttle key is made of.
datum.web.throttle.max_keysDATUM_WEB__THROTTLE__MAX_KEYS10000Whole number, at least 1. The most distinct keys the in-memory counters hold.
datum.web.throttle.limitsDATUM_WEB__THROTTLE__LIMITSnoneMapping from a kind (submit, validate, test, pdf, register) to requests per window, at least 1. A kind not listed uses limit.
datum.web.throttle.storageDATUM_WEB__THROTTLE__STORAGEasync+memory://Text. A storage address of the limits library; use async+redis://... in production. Any credentials in it are hidden in logs. A storage that cannot be built stops the start (datum.E006).
datum.web.throttle.key_saltDATUM_WEB__THROTTLE__KEY_SALTunsetSecret, at least 32 bytes. Salts the keys in the storage. Required when the storage is not memory, and every worker on one storage must share it (datum.E005). Memory storage uses a random salt per process.

datum.web.assets ​

SettingEnvironment variableDefaultMeaning
datum.web.assets.enabledDATUM_WEB__ASSETS__ENABLEDfalseBoolean. Serve the packaged browser files, host.json and datum-host.js.
datum.web.assets.cache_periodDATUM_WEB__ASSETS__CACHE_PERIOD31536000 sSeconds, 0 or more. The cache lifetime of an asset (one year).
datum.web.assets.omit_featuresDATUM_WEB__ASSETS__OMIT_FEATURESnoneList of text. Feature tokens whose files are left out of the served assets.

datum.web.csrf ​

The names the page glue reads from host.json. Datum adds no CSRF protection itself; these settings only name the header, cookie and meta tag your own protection uses.

SettingEnvironment variableDefaultMeaning
datum.web.csrf.header_nameDATUM_WEB__CSRF__HEADER_NAMEX-XSRF-TOKENText. The header that carries the token.
datum.web.csrf.cookie_nameDATUM_WEB__CSRF__COOKIE_NAMEXSRF-TOKENText. The cookie that carries the token.
datum.web.csrf.meta_nameDATUM_WEB__CSRF__META_NAME_csrfText. The meta tag that carries the token.

datum.web.openapi ​

SettingEnvironment variableDefaultMeaning
datum.web.openapi.enabledDATUM_WEB__OPENAPI__ENABLEDtrueBoolean. Describe Datum's routes in the application's OpenAPI document.
datum.web.openapi.tag_prefixDATUM_WEB__OPENAPI__TAG_PREFIXdatum-Text. The prefix of Datum's OpenAPI tags.
datum.web.openapi.group_documentsDATUM_WEB__OPENAPI__GROUP_DOCUMENTSfalseBoolean. Add one OpenAPI document per router, served at {prefix}/openapi/{factory}.json.

datum.web.management ​

SettingEnvironment variableDefaultMeaning
datum.web.management.recheckDATUM_WEB__MANAGEMENT__RECHECKfalseBoolean. Serve POST /recheck. It is guarded by the dependencies you pass to routers.management.

datum.builder ​

SettingEnvironment variableDefaultMeaning
datum.builder.enabledDATUM_BUILDER__ENABLEDfalseBoolean. Serve the builder routes.
datum.builder.max_definition_sizeDATUM_BUILDER__MAX_DEFINITION_SIZE1MiBSize, 1 byte to 64 MiB. The largest definition a save accepts.

datum.pdf ​

SettingEnvironment variableDefaultMeaning
datum.pdf.enabledDATUM_PDF__ENABLEDtrueBoolean. The PDF capability. With it on, the start needs datum-core[pdf].
datum.pdf.fontsDATUM_PDF__FONTSdefaultWord: default, standard or all. Which font faces a PDF embeds.

datum.pdf.seal ​

The seal preset applied to every PDF the application issues.

SettingEnvironment variableDefaultMeaning
datum.pdf.seal.enabledDATUM_PDF__SEAL__ENABLEDfalseBoolean. Seal issued PDFs. Without a server signing key the start warns (datum.W013).
datum.pdf.seal.layoutsDATUM_PDF__SEAL__LAYOUTSnoneList of text. The layout ids that are sealed. Empty means all.
datum.pdf.seal.certifyDATUM_PDF__SEAL__CERTIFYnoChangesWord: noChanges, formFill, annotate or none. The kind of signature. noChanges certifies and allows no change afterwards. formFill certifies and allows form filling. annotate certifies and allows form filling and annotations. none is an approval signature, not a certifying one. The program's own words formFilling and annotations, false and approval for none, and the numbers 0 to 3 are read as well, whatever the case.
datum.pdf.seal.timestampDATUM_PDF__SEAL__TIMESTAMPtrueBoolean. Ask a timestamp token for each seal made with the server's key, when a timestamp source is set up (datum.W011 otherwise). The test seal of posted answers is never timestamped.
datum.pdf.seal.reasonDATUM_PDF__SEAL__REASONunsetText. The signature reason.
datum.pdf.seal.locationDATUM_PDF__SEAL__LOCATIONunsetText. The signature location.
datum.pdf.seal.visibleDATUM_PDF__SEAL__VISIBLEunsetBoolean. Draw a visible signature. Unset leaves it to the layout.
datum.pdf.seal.posted_answersDATUM_PDF__SEAL__POSTED_ANSWERSfalseBoolean. Seal the PDFs of posted, unstored answers with the real certificate. Without a server key they keep the test seal.

datum.pdf.signing ​

The server's signing key, shared by the seal and POST /api/pdf/sign. The key rules are under the value forms above. Nothing here is needed when the application passes its own pdf_signer to Datum.

SettingEnvironment variableDefaultMeaning
datum.pdf.signing.typeDATUM_PDF__SIGNING__TYPEPKCS12Word: PKCS12 or PEM. The key file format.
datum.pdf.signing.pkcs12_fileDATUM_PDF__SIGNING__PKCS12_FILEunsetText. The path of the PKCS#12 key store. For type PKCS12.
datum.pdf.signing.pkcs12_passwordDATUM_PDF__SIGNING__PKCS12_PASSWORDunsetSecret. The store's password.
datum.pdf.signing.friendly_nameDATUM_PDF__SIGNING__FRIENDLY_NAMEunsetText. The friendly name of the key's certificate in the store. A check against the certificate; it never chooses one.
datum.pdf.signing.key_passwordDATUM_PDF__SIGNING__KEY_PASSWORDunsetSecret. The password of the PEM private key. For type PEM.
datum.pdf.signing.key_fileDATUM_PDF__SIGNING__KEY_FILEunsetText. The path of the PEM private key.
datum.pdf.signing.cert_fileDATUM_PDF__SIGNING__CERT_FILEunsetText. The path of the PEM certificate chain, the key's own certificate first.
datum.pdf.signing.retired_certificatesDATUM_PDF__SIGNING__RETIRED_CERTIFICATESnoneList of text. PEM locations (a path or package:<pkg>/<file>) of replaced certificates. The verify route reports a signature by one of them as site_retired.
datum.pdf.signing.trust_anchorsDATUM_PDF__SIGNING__TRUST_ANCHORSnoneList of text. PEM locations of the trust anchors the verify route builds a chain to. A location that cannot be read stops the start.

datum.pdf.signing.tsa ​

The timestamp client used to timestamp PDF signatures. It is not used when the application passes its own timestamper to Datum; setting it then raises datum.I002 or datum.W012.

SettingEnvironment variableDefaultMeaning
datum.pdf.signing.tsa.urlDATUM_PDF__SIGNING__TSA__URLunsetText. The address of the timestamp authority, http or https. User-info in it is hidden in logs.
datum.pdf.signing.tsa.policyDATUM_PDF__SIGNING__TSA__POLICYunsetText, an OID such as 1.2.3.4. The policy requested.
datum.pdf.signing.tsa.bearer_tokenDATUM_PDF__SIGNING__TSA__BEARER_TOKENunsetSecret. A bearer token for the authority.
datum.pdf.signing.tsa.basic_userDATUM_PDF__SIGNING__TSA__BASIC_USERunsetText. The Basic-auth user. Needs basic_password.
datum.pdf.signing.tsa.basic_passwordDATUM_PDF__SIGNING__TSA__BASIC_PASSWORDunsetSecret. The Basic-auth password. Needs basic_user.
datum.pdf.signing.tsa.timeoutDATUM_PDF__SIGNING__TSA__TIMEOUT10 sSeconds, at least 0.001. The bound on one request.

datum.bindings ​

Which design-system binding draws each form route, and the PDF theme its PDF prints under. A route is a form key without a version. Use the TOML file for keys with capitals.

toml
[bindings]
default = "datum"

[bindings.routes]
intake = "acme"

[bindings.catalog.acme]
label = "Acme"
pdf_theme = "acme-pdf"

[bindings.pdf_themes]
acme-pdf = "themes/acme-pdf.json"
SettingEnvironment variableDefaultMeaning
datum.bindings.defaultDATUM_BINDINGS__DEFAULTdatumText. The binding of a route with no override. It must be an id in the catalogue.
datum.bindings.routesDATUM_BINDINGS__ROUTESnoneMapping from a form key to the binding id that draws it. Every id must be in the catalogue.
datum.bindings.catalogDATUM_BINDINGS__CATALOGnoneMapping from a binding id to its entry (the two rows below). Adds bindings this host registers on its pages to the ones the bundles carry. An id holds letters, digits, ., _ and -.
datum.bindings.catalog.<id>.labelDATUM_BINDINGS__CATALOG__<ID>__LABELthe idText. Shown where bindings are listed.
datum.bindings.catalog.<id>.pdf_themeDATUM_BINDINGS__CATALOG__<ID>__PDF_THEMEnoneText, a PDF theme id. The theme a PDF of a route drawn by this binding prints under. Unset suggests none.
datum.bindings.pdf_themesDATUM_BINDINGS__PDF_THEMESnoneMapping from a PDF theme id to the path of its JSON file, for every suggested PDF theme except datum-pdf. The file is a JSON object whose id is the key and whose target is pdf.

datum.tsa ​

The RFC 3161 timestamp server. The routes are on only when datum.tsa.enabled is true.

SettingEnvironment variableDefaultMeaning
datum.tsa.enabledDATUM_TSA__ENABLEDfalseBoolean. Serve the timestamp route. Needs datum-core[timestamp] and datum.tsa.policy.
datum.tsa.accessDATUM_TSA__ACCESSclientsWord: clients or open. Who may call: only clients that present a known key, or anyone.
datum.tsa.policyDATUM_TSA__POLICYunsetText, an OID. The policy the server issues under.
datum.tsa.accepted_policiesDATUM_TSA__ACCEPTED_POLICIESnoneList of OIDs. The policies a request may ask for.
datum.tsa.accuracyDATUM_TSA__ACCURACY1 sSeconds, 0 to 60. The accuracy stated in each token.
datum.tsa.max_request_sizeDATUM_TSA__MAX_REQUEST_SIZE16KiBSize, 1 byte to 1 MiB. The largest request. A larger one answers 413.
datum.tsa.session_cookiesDATUM_TSA__SESSION_COOKIES["*"]List of text. A request that carries one of these cookies is refused with 403. The default "*" refuses any cookie. Name cookies instead to refuse only those. Names are matched without regard to case.
datum.tsa.allow_memory_storesDATUM_TSA__ALLOW_MEMORY_STORESfalseBoolean. Acknowledge that the serial allocator and issue log are kept in memory, which is safe for one instance only. Without it the start stops (datum.E001); with it the start warns (datum.W009).
datum.tsa.client_storeDATUM_TSA__CLIENT_STOREsettingsWord: settings or sql. Where timestamp clients are kept. sql needs a client store passed to Datum.
datum.tsa.clientsDATUM_TSA__CLIENTSnoneList of 64-character hexadecimal strings. The SHA-256 of each client key, for client store settings.
datum.tsa.retired_certificatesDATUM_TSA__RETIRED_CERTIFICATESnoneList of text. PEM locations of replaced timestamp certificates.

datum.tsa.flood ​

Flood control of the timestamp server.

SettingEnvironment variableDefaultMeaning
datum.tsa.flood.limitDATUM_TSA__FLOOD__LIMIT1000Whole number, 0 or more. Requests per window, counted per client (per address under open access). Over it the answer is 429. 0 turns it off.
datum.tsa.flood.windowDATUM_TSA__FLOOD__WINDOW3600 sSeconds, at least 1. The length of the window.
datum.tsa.flood.failed_keysDATUM_TSA__FLOOD__FAILED_KEYS10Whole number, 0 or more. Wrong keys tolerated per address per window; past it the answer is 429. 0 turns the lockout off.

datum.tsa.signer ​

The timestamp server's signing key. The key rules are under the value forms above.

SettingEnvironment variableDefaultMeaning
datum.tsa.signer.typeDATUM_TSA__SIGNER__TYPEPKCS12Word: PKCS12 or PEM. The key file format.
datum.tsa.signer.pkcs12_fileDATUM_TSA__SIGNER__PKCS12_FILEunsetText. The path of the PKCS#12 key store.
datum.tsa.signer.pkcs12_passwordDATUM_TSA__SIGNER__PKCS12_PASSWORDunsetSecret. The store's password.
datum.tsa.signer.friendly_nameDATUM_TSA__SIGNER__FRIENDLY_NAMEunsetText. The friendly name of the key's certificate in the store. Checked against the certificate, never used to choose it.
datum.tsa.signer.key_passwordDATUM_TSA__SIGNER__KEY_PASSWORDunsetSecret. The password of the PEM private key.
datum.tsa.signer.key_fileDATUM_TSA__SIGNER__KEY_FILEunsetText. The path of the PEM private key.
datum.tsa.signer.cert_fileDATUM_TSA__SIGNER__CERT_FILEunsetText. The path of the PEM certificate chain.
datum.tsa.signer.self_signedDATUM_TSA__SIGNER__SELF_SIGNEDfalseBoolean. Use a throwaway self-signed key, for development only. Refused when a key file is named as well.

Start-up checks ​

The host runs its checks when the lifespan starts and logs each one under datum.checks as (datum.W001) message, with a HINT: line when there is one. A WARNING or INFO check never stops the start. All ERROR checks found are raised together as one DatumConfigurationError and the start stops. List ids in datum.silenced_checks to leave out an INFO or WARNING check.

IdSeverityCauseWhat to do
datum.I001INFOThe log line that names the routes that are on: the endpoint switches that are true, and assets.Nothing. If it reads none, set datum.web.api.endpoints.* or datum.web.assets.enabled.
datum.I002INFOdatum.pdf.signing.tsa names an address or credentials, and the application also passed its own timestamper, which issues the tokens instead.Unset the client settings, or do not pass Datum(timestamper=...).
datum.W001WARNINGA router was included and every switch it reads is off (or datum.enabled is false), so it serves no route.Set one of the named switches, or do not include the router.
datum.W002WARNINGThe runtime's slots times their memory, for the validation and PDF pools and every worker, exceed the container's memory limit (cgroup, else the host's memory) less what the process uses at start.Lower datum.runtime.validation.concurrency, datum.runtime.pdf.concurrency or the memory budgets, raise the container memory, or state datum.workers_expected.
datum.W003WARNINGA submission route is on and the default logging handler is in use, which keeps nothing.Pass your own Datum(handler=...).
datum.W004WARNINGA store is kept in this process's memory: the throttle counters, the receipt store, the snapshot or translation store, or the builder's form repository. Each worker has its own, and a restart forgets them.Use a shared throttle storage (async+redis://...), give Datum SQL stores or your own, or run one worker.
datum.W005WARNINGDeclared for an engine over in-memory SQLite. Nothing raises it.None.
datum.W006WARNINGA data-source provider keeps the default exists, so it answers for every id and hides the providers after it.Implement exists on the provider.
datum.W007WARNINGA DATUM_ environment variable matches no setting. The hint offers the closest name.Fix the name, or remove the variable. Set datum.strict_env to stop the start on one. DATUM_CONFIG_FILE is the only name outside the settings that is allowed.
datum.W008WARNINGA datum.runtime budget was outside its bounds and was moved to the nearest bound. The message gives the value asked, the value used and the bounds.Set a value inside the bounds listed above.
datum.W009WARNINGThe timestamp server keeps its serial allocator or issue log in memory because datum.tsa.allow_memory_stores says so.Run one instance, or give Datum a SQL store or your own to share between instances and restarts.
datum.W010WARNINGThe process time zone could not be read, so datum.host.time_zone is UTC.Set datum.host.time_zone to an IANA zone name.
datum.W011WARNINGThe seal asks for timestamps, a server key is present, and no timestamp source is set up. Sealed PDFs carry the sealing.timestamp warning and no token.Pass Datum(timestamper=...), set datum.pdf.signing.tsa.url, enable datum.tsa.enabled, or set datum.pdf.seal.timestamp to false.
datum.W012WARNINGdatum.pdf.signing.tsa.policy is set, and the application's own timestamper issues the tokens, so the policy is unused.Unset the policy, or do not pass Datum(timestamper=...).
datum.W013WARNINGdatum.pdf.seal is on and the server has no signing key, so posted answers carry the test seal and render_submission answers 500.Name a key in datum.pdf.signing, or pass Datum(pdf_signer=...).
datum.E001ERRORThe timestamp server would keep its serial allocator or issue log in memory, and that is not acknowledged.Pass a SQL engine and create the table, provide your own store, or set datum.tsa.allow_memory_stores to true for one instance.
datum.E002ERRORThe builder is on with in-memory stores and more than one worker is expected, so a save on one worker is invisible on the others.Give Datum shared stores, or set datum.workers_expected to 1.
datum.E003ERRORA runtime memory budget is below what the runtime module needs to start (its initial pages times 64 KiB). The message gives the least value.Raise datum.runtime.validation.memory or datum.runtime.pdf.memory to at least that value.
datum.E004ERRORThe runtime did not start within datum.runtime.startup_budget. The message names the phases finished so far.Raise datum.runtime.startup_budget, or give the host more CPU: compiling the sandbox module takes seconds on a small virtual machine.
datum.E005ERRORThe throttle counts in a shared storage and datum.web.throttle.key_salt is not set.Set key_salt to a secret of at least 32 bytes, the same on every worker.
datum.E006ERRORThe throttle storage cannot be built: a missing client library or an unusable address. The message names the failure's class, never its text.Install the client library (for example the redis extra of limits), or fix datum.web.throttle.storage.

W003, W004, E005 and E006 are raised only while a submission route (submissions, validate, test or inspect) is on. W004 for the snapshot, translation and builder stores is raised while the definition route or the builder is on.

MIT licence. Your forms, your data, your keys.