What this is about
CRMS reads its settings from environment variables. They all start with CODAMAI_CRMS_, the S3 connection with CODAMAI_S3_. Spring binds them to a setting by name: CODAMAI_CRMS_RENDER_THREADS becomes codamai.crms.render.threads.
Where a value comes from
-
Environment variableIs the variable set?↳ no on to the next source
-
Buildcrms-configuration.yamlDoes the CRMS module in the hub have a value?↳ no on to the next source
-
CRMSDefault of the CRMS moduleDoes the setting have a default?↳ no Start fails and names the variable
- The value is fixed
The file crms-configuration.yaml exists only when CRMS is embedded, or built as a separate service with a CRMS module from the hub. A client has none.
Which variables are read
This depends on the placement:
When: CRMS runs in the process of a CDMS application.
The application reads every variable on this page except those of the client. It already has a database and CIAS, see The database.
When: The CDMS application calls a CRMS service.
It reads only three variables: CODAMAI_CRMS_CLIENT_URL (required), CODAMAI_CRMS_CLIENT_CONNECT_TIMEOUT (default PT5S) and CODAMAI_CRMS_CLIENT_TIMEOUT (default PT2M, one whole call). Everything else belongs to the service.
When: CRMS runs as a standalone service.
The service reads every CRMS variable on this page, plus the variables for database and CIAS that a CDMS application reads too: CODAMAI_PERSISTENCE_*, CIAS_ISSUER, CIAS_CLIENT, CIAS_CLIENT_SECRET, CODAMAI_CIAS_PLATFORM_ADMINISTRATOR_ROLES, CODAMAI_CIAS_TENANCY_CLIENT_*. In addition SERVER_PORT (8080), MANAGEMENT_SERVER_PORT (8081) and TZ (UTC).
What is required
A required variable without a value makes the start fail. The error message names the variable. Whether a variable is required depends on two switches: whether documents are stored (CODAMAI_CRMS_DOCUMENT_REVISIONS) and whether PDFs are sealed (CODAMAI_CRMS_SEAL_MODE).
| Store documents? | Seal on? | Required for embedded CRMS |
|---|---|---|
| – | – | CODAMAI_CRMS_TSA_KEYSTORE, always |
| yes | – | plus CODAMAI_CRMS_DOCUMENT_KEY, CODAMAI_CRMS_DOCUMENT_RETENTION, CODAMAI_CRMS_DOCUMENT_BUCKET, CODAMAI_S3_ENDPOINT, CODAMAI_S3_ACCESS_KEY, CODAMAI_S3_SECRET_KEY |
| no | – | none of these: no storage, no document key |
| – | yes | plus CODAMAI_CRMS_SEAL_KEYSTORE |
| – | no | no seal key |
In addition: if the CRMS module admits system templates (scope SYSTEM, the default), an embedded CRMS needs CODAMAI_CIAS_PLATFORM_ADMINISTRATOR_ROLES. These realm roles write the system templates. Without them the application does not start.
For the separate service, bucket and S3 access are always required, even when no documents are stored. The standalone CRMS service always brings the S3 storage, and it checks its bucket at start. Document key and retention are required there, as above, only while documents are stored.
Evidence and keys
| Variable | Meaning | Default |
|---|---|---|
CODAMAI_CRMS_TSA_KEYSTORE | the timestamping key CRMS anchors its journals with. PKCS#12 as Base64. The certificate carries timeStamping as a critical extended key usage | required, secret |
CODAMAI_CRMS_TSA_KEYSTORE_PASSWORD | its password | empty |
CODAMAI_CRMS_TSA_TRUSTED_CERTIFICATES | former timestamping certificates or the authority that issues them, as PEM or as PEM in Base64. Old anchors stay verifiable after a key replacement | empty |
CODAMAI_CRMS_DOCUMENT_KEY | the key that encrypts the keys of the stored documents. 256 bits as Base64 | required with stored documents, secret |
CODAMAI_CRMS_SEAL_MODE | the PAdES seal of PDF documents: internal or none | internal |
CODAMAI_CRMS_SEAL_KEYSTORE | the seal key with its certificate chain, PKCS#12 as Base64 | required unless none, secret |
CODAMAI_CRMS_SEAL_KEYSTORE_PASSWORD | its password | empty |
Anchoring means: CRMS regularly gives the latest state of a journal a timestamp. How this works is described in Timestamps, the seal in Seal.
Documents and storage
| Variable | Meaning | Default |
|---|---|---|
CODAMAI_CRMS_DOCUMENT_REVISIONS | store final documents. Off: a FINAL render is refused | true |
CODAMAI_CRMS_DOCUMENT_RETENTION | how long a final document stays, ISO-8601, e.g. P10Y | none |
CODAMAI_CRMS_DOCUMENT_STORE_PAYLOAD | store the data of a final document with it, encrypted | true |
CODAMAI_CRMS_AUDIT_READS | also write every read to the journal | false |
CODAMAI_CRMS_DOCUMENT_BUCKET | the bucket of final documents. It must be created with Object Lock | none |
CODAMAI_S3_ENDPOINT | the S3 of the platform, e.g. http://minio:9000 | none |
CODAMAI_S3_ACCESS_KEY, CODAMAI_S3_SECRET_KEY | the S3 access | none, secret |
CODAMAI_S3_REGION | the S3 region | us-east-1 |
CODAMAI_S3_PATH_STYLE | bucket in the path instead of the host name, as MinIO expects | true |
CODAMAI_CRMS_STORAGE_ALLOW_UNLOCKED | accept a bucket without Object Lock. Documents can then be deleted | false |
Object Lock is an S3 feature that locks an object against deletion and overwriting until a date. All modules of the platform share the S3 connection CODAMAI_S3_*. The bucket is separate per purpose. More in Storage.
Templates and roles
| Variable | Meaning | Default |
|---|---|---|
CODAMAI_CRMS_TEMPLATE_SCOPES | the admitted scopes: SYSTEM, TENANT, USER, comma separated | all |
CODAMAI_CRMS_TEMPLATE_REASON_REQUIRED | a reason on submit, roll back and retire | true |
CODAMAI_CRMS_TEMPLATE_ROLES_USER | client role for a user’s own templates | crms-template-personal |
CODAMAI_CRMS_TEMPLATE_ROLES_TENANT | client role for a tenant’s templates | crms-template-author |
CODAMAI_CRMS_REST_DOCUMENT_ROLES_READ | client role that reads final documents | crms-document-reader |
CODAMAI_CRMS_REST_DOCUMENT_ROLES_HOLD | client role that places and releases a hold against erasure | crms-document-custodian |
CODAMAI_CRMS_REST_DOCUMENT_ROLES_ERASE | client role that erases a document | crms-document-eraser |
CODAMAI_CRMS_REST_TEMPLATE_MAX_BYTES | largest template upload in bytes | 16777216 |
The approval stages have no variable. They come from the build only.
Rendering
| Variable | Meaning | Default |
|---|---|---|
CODAMAI_CRMS_FORMATS | the formats offered, comma separated: HTML, PDF, DOCX, XLSX, CSV, ODS. A format without an installed module makes the start fail | every installed format |
CODAMAI_CRMS_PDF_PROFILE | PDF_A_3A, PDF_UA, PDF_A_3A_UA or NONE | PDF_A_3A |
CODAMAI_CRMS_TRANSIENT_DOCUMENTS | allow the mode TRANSIENT for system templates. Off, it is refused | false |
CODAMAI_CRMS_RENDER_THREADS | how many documents are produced at once | number of processors |
CODAMAI_CRMS_RENDER_QUEUE | how many wait beyond those. More are refused | 50 |
CODAMAI_CRMS_RENDER_TIMEOUT | how long a caller waits for its document | PT30S |
CODAMAI_CRMS_RENDER_MAX_OUTPUT | largest document in bytes | 52428800 |
CODAMAI_CRMS_PAYLOAD_MAX_BYTES | largest data (payload) in bytes | 5242880 |
CODAMAI_CRMS_ATTACHMENTS_MAX_COUNT | highest number of pictures (PNG, JPEG) per request | 200 |
CODAMAI_CRMS_ATTACHMENTS_MAX_BYTES | highest sum of the pictures per request in bytes | 52428800 |
What the limits do is described in Execution, the mode TRANSIENT in Modes. The separate service also reads CODAMAI_I18N_DEFAULT_LOCALE (de) and CODAMAI_I18N_SUPPORTED_LOCALES (de,en), see Language and time zone.
Schedules
| Variable | Meaning | Default |
|---|---|---|
CODAMAI_CRMS_SCHEDULING_ENABLED | whether this instance runs anchoring and retention | true |
CODAMAI_CRMS_ANCHOR_INTERVAL | delay between two anchorings | PT1H |
CODAMAI_CRMS_RETENTION_INTERVAL | delay between two passes that remove expired documents | PT24H |
The first pass starts one minute after the start. A delay that is not positive makes the start fail.