> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment variables
> Deploy-time environment variables for Lerian SISBAJUD: KMS backend, S3 object storage, envelope-encryption keys, workers, and Midaz ledger.
Lerian SISBAJUD is the Lerian-owned rail that fulfils judicial asset-blocking orders and protects the personal data they carry. You set these variables at deploy time. They take effect only after a service restart. [BYOC configuration essentials](/en/reference/byoc-configuration) documents the universal backbone that every Lerian Go service shares: server, datastores, multi-tenancy, telemetry, plugin authentication, and licensing. This page covers only the variables distinctive to Lerian SISBAJUD.
In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required** or **Required if enabled**) marks the variables you must set. `—` means no default. Any variable flagged **Sensitive** carries credential or key material. Inject it from your secret manager at deploy time. Never commit a value.
## Service and runtime
| Variable | Default / Required | Description |
| --------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_ADDRESS` | — | Main HTTP listen address; no code default, so set it explicitly (the reference deployment uses `:4029`). The liveness, readiness, metrics, and version probes bind this same port. |
| `ENVIRONMENT_NAME` | — | Runtime environment: `local`, `development`, `staging`, `e2e`, `test`, or `production`. `ENV_NAME` is accepted as an alternative name. Unset stays empty and is treated as production-like, so the strictest security gates arm fail-closed. |
| `SYSTEMPLANE_ENABLED` | `false` | Enable the [Systemplane](/en/reference/platform/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode). |
| `DEFAULT_TENANT_ID` | **Required in single-tenant mode** | Tenant UUID used in single-tenant mode. There is no effective string default: explicitly set a valid UUID for usable single-tenant operation. The tenant is the database-isolation boundary and can contain several institutions; each institution routes by its own identifier inside the tenant. With auth disabled, the rail also falls back to this UUID as its single configured institution. |
Lerian SISBAJUD exposes `/health` (liveness), `/readyz` (readiness), `/version`, and `/metrics` on the main port. When you enable multi-tenancy, it also exposes `GET /readyz/tenant/{id}`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.
## Security backend
The service validates the KMS provider at boot. It selects the backend that protects court-ordered seizure data with envelope encryption. In production, an unset or unsupported value fails the boot closed. Outside production, it defaults to `vault`.
| Variable | Default / Required | Description |
| -------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KMS_PROVIDER` | `vault` (non-production) · **Required in production** | Envelope-encryption key manager: `vault` (HashiCorp Vault Transit) or `aws` (AWS KMS). Read once at boot; not hot-reloadable. There is no in-memory provider. |
`KMS_PROVIDER=vault` requires the Vault variables below. `KMS_PROVIDER=aws` requires the shared `AWS_REGION`. Per-institution connector credentials are sealed inside institution-configuration metadata under a credentials-class KEK. No environment selector chooses their storage. `KMS_PROVIDER` defaults to `vault` when unset outside production. In production, you must set it explicitly or the boot fails closed.
### Vault (when `KMS_PROVIDER=vault`)
| Variable | Default / Required | Description |
| -------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `VAULT_ADDR` | **Required for the Vault provider** | Address of the client's Vault. |
| `VAULT_AUTH_METHOD` | `token` | Authentication method: `token` (static `VAULT_TOKEN`) or `approle` (AppRole role and secret ids). |
| `VAULT_TOKEN` | **Required if `token`, in production** | Service token for Vault. Sensitive. Non-production falls back to a development token. |
| `VAULT_APPROLE_ROLE_ID` | **Required if `approle`** | AppRole role id. Sensitive. |
| `VAULT_APPROLE_SECRET_ID` | **Required if `approle`** | AppRole secret id. Sensitive. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Mount path of the Transit engine used for envelope encryption. |
\| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Run a background renewer that refreshes the Vault token before its lease lapses. |
\| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Floor, in seconds, between renewal attempts. |
\| `VAULT_TIMEOUT_SEC` | `15` | Per-request timeout, in seconds, for each Vault round-trip. |
### AWS (when `KMS_PROVIDER=aws`)
| Variable | Default / Required | Description |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_REGION` | **Required with `KMS_PROVIDER=aws`** | Region for the AWS KMS adapter. Boot fails closed when `KMS_PROVIDER=aws` and it is blank. Credentials resolve through the default AWS SDK chain. |
| `AWS_ENDPOINT_URL` | — | AWS-compatible endpoint override. Leave unset in real AWS environments so the SDK uses its default endpoints. |
## Crypto lifecycle
Envelope encryption uses a per-record data key sealed under the institution's master key, plus a blind index for exact-match lookup on fiscal identifiers.
| Variable | Default / Required | Description |
| ---------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `SISBAJUD_DEK_CACHE_TTL` | `5m` | Lifetime of an unwrapped data-encryption key in the in-memory cache before the KMS is asked to unwrap again. Go-duration string. |
| `SISBAJUD_DEK_CACHE_MAX_ENTRIES` | `50000` | Ceiling on cached data-key primitives; bounds heap during a large batch decrypt. |
| `SISBAJUD_HMAC_COEXISTENCE_WINDOW` | `720h` | Window during which blind-index hashes from the previous HMAC key version stay queryable across a key rotation. Go-duration string. |
| `KEK_REWRAP_BACKFILL_ENABLED` | `false` | Enable the background sweep that advances behind data-key rows to the active master-key version after a rotation. |
| `REHASH_BACKFILL_ENABLED` | `false` | Enable the background sweep that re-hashes trailing blind-index rows to the new primary HMAC key version. |
## Domain workers
Judicial-order processing runs as a set of per-institution background crons. All are off by default except the processing-lock reaper, which runs by default. The workers use the `*_SCAN_INTERVAL` (seconds) and `*_BATCH_SIZE` cadence knobs where applicable.
| Variable | Default / Required | Description |
| -------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `EXECUTION_ENABLED` | `false` | Master switch for the order-execution engine. When off, the FIFO orchestrator and downstream dispatch stay dormant. |
| `ORCHESTRATOR_LOCK_TTL` | `30` | Per-subject execution lock lease, in seconds. |
| `ORCHESTRATOR_RENEW_INTERVAL` | `10` | Cadence, in seconds, at which the owning worker renews the lock. Must stay strictly below `ORCHESTRATOR_LOCK_TTL` or boot fails closed. |
| `PROCESSING_LOCK_REAPER_ENABLED` | `true` | Enable the background reaper that deletes expired processing-lock rows for each tenant. |
| `PROCESSING_LOCK_REAPER_INTERVAL_SEC` | `300` | Reaper sweep cadence in seconds. When this variable is unset or non-positive, the service uses 300 seconds. |
| `UNBLOCK_EXECUTION_SCAN_INTERVAL` | `60` | Pending-unblock sweep cadence in seconds. Shares the `EXECUTION_ENABLED` gate. |
| `UNBLOCK_EXECUTION_BATCH_SIZE` | `500` | Pending unblock orders processed per tenant pass. |
| `PERMANENT_BLOCK_EXPIRY_ENABLED` | `false` | Enable the daily scan that expires permanent blocks past their deadline. |
| `RECONCILIATION_ENABLED` | `false` | Enable the scan that reconciles monitoring orders against the ledger and persists detected gaps. |
| `RETURN_FILE_GENERATION_ENABLED` | `false` | Enable generation of SISBAJUD return files for unreturned terminal orders. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Enable generation of AJUD309 information-response files. |
| `SLA_ALERT_ENABLED` | `false` | Enable the evaluator that classifies active orders by SLA-risk band and emits the bands as metrics. |
| `RETURN_FILE_ENVIRONMENT` | `HOMOLOGATION` | Regulatory environment stamped into generated return files. |
## Object storage
Lerian SISBAJUD writes court-ordered seizure artifacts to an S3-compatible object store, already encrypted. The blob layer never sees plaintext.
| Variable | Default / Required | Description |
| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint of the S3-compatible object store. Storage wiring failures are non-fatal: the service boots and the readiness probe reports the store as unavailable. |
| `SEAWEEDFS_BUCKET` | `sisbajud` | Bucket for remittance and return artifacts (already encrypted). |
| `SEAWEEDFS_REGION` | `us-east-1` | S3 region label required by the AWS SDK. |
| `SEAWEEDFS_ACCESS_KEY` | — | Object-store access key. Sensitive. Leave blank when the store needs no auth. |
| `SEAWEEDFS_SECRET_KEY` | — | Object-store secret key. Sensitive. Leave blank when the store needs no auth. |
| `STA_INBOUND_BUCKET` | `sta-files` | Bucket holding the raw remittance objects a reception notification points at. |
| `STA_FILE_LOCK_TTL` | `5` | Per-file processing-lock TTL, in minutes. |
## Midaz ledger connector
Lerian SISBAJUD reads balances and blocks through the Midaz ledger. `MIDAZ_BASE_URL` is an optional service-wide fallback. Per-institution connector metadata takes precedence.
| Variable | Default / Required | Description |
| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MIDAZ_BASE_URL` | — (optional fallback) | Base URL of the Midaz ledger. Used only when per-institution metadata provides no URL. Connector resolution fails closed only if neither provides a URL. |
| `MIDAZ_AUTH_ENABLED` | `false` | Enable machine-to-machine authentication to Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Required if enabled** | Auth service address for minting Midaz tokens. |
| `MIDAZ_CLIENT_ID` | **Required if enabled** | OAuth client id for Midaz. Ignored in multi-tenant mode (resolved per tenant). |
| `MIDAZ_CLIENT_SECRET` | **Required if enabled** | OAuth client secret for Midaz. Sensitive. Ignored in multi-tenant mode (resolved per tenant). |