> ## 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, STA file exchange, and Midaz ledger.

Lerian SISBAJUD encrypts the personal data it keeps in its own database and bucket. 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` | `:8080` | Main HTTP listen address. The example configuration uses `:4029`. The liveness, readiness, 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. An unset or unknown value runs the production configuration checks. |
| `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` | `11111111-1111-1111-1111-111111111111` | Tenant UUID used in single-tenant mode. 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. |

<Note>
  Lerian SISBAJUD exposes `/health` (liveness), `/readyz` (readiness), and `/version` on the main port. It exposes `/metrics` only when `ENVIRONMENT_NAME` is `local` or `development`. 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.
</Note>

## Security backend

An unsupported `KMS_PROVIDER` value fails the boot in every environment.

| Variable | Default / Required | Description |
| - | - | - |
| `KMS_PROVIDER` | `vault` · **Required when `ENVIRONMENT_NAME` is `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. |

<Note>
  `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.
</Note>

### 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` and `ENVIRONMENT_NAME` is `production`** | Service token for Vault. Sensitive. With any other environment value, an unset token 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_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.

| 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. |
| `INFORMATION_REQUEST_ENABLED` | `false` | Enable the worker that processes pending information-request orders. |
| `MONITORING_EXPIRY_ENABLED` | `false` | Enable the daily scan that closes non-permanent monitoring orders at the end of their monitoring window. |
| `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. |
| `RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Return-file generation cadence in seconds. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Enable generation of AJUD309 information-response files. |
| `INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Information-response generation cadence in seconds. |
| `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` | `PRODUCTION` or `HOMOLOGATION`. A generated return file takes the environment of the remittance file behind its orders. This value applies only when no remittance file backs them. An invalid value turns off return-file generation. |
| `SISBAJUD_REMITTANCE_LAYOUTS` | `v111,v2026` | Comma-separated remittance layouts the service accepts: `v111` (CNJ v1.11) and `v2026`. The service rejects a file in any other layout at reception. An invalid value fails the boot. |
| `SISBAJUD_RESPONSE_LAYOUT` | `auto` | Layout of the block response. `auto` answers each remittance in the layout it arrived in. `v111` or `v2026` forces one layout. An invalid value fails the boot. |

## Object storage

| Variable | Default / Required | Description |
| - | - | - |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint of the S3-compatible object store. With `STA_TRANSFERS_ENABLED` off, storage wiring failures are non-fatal: the service boots and the readiness probe reports the store check as `n/a`. |
| `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` | **Required** | Bucket holding the raw remittance objects that a reception notification or a Lerian STA event points at. The boot fails when it is empty. |
| `STA_FILE_LOCK_TTL` | `5` | Per-file processing-lock TTL, in minutes. |

## Event streaming

Lerian SISBAJUD publishes its business events and receives Midaz balance events over Kafka.

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publish the service's business events. Requires `OUTBOX_ENABLED`. With it off, a set `STREAMING_BROKERS` fails the boot. |
| `STREAMING_BROKERS` | — | Kafka broker list. It starts the balance-change trigger for permanent-block reattempts. Without it, only the 5-second scan re-attempts. `STA_CONSUMER_ENABLED` also requires it. |
| `OUTBOX_ENABLED` | `true` | Durable delivery path for emitted events. `STREAMING_ENABLED` and `STA_TRANSFERS_ENABLED` require it. |

## STA file exchange

Lerian SISBAJUD exchanges judicial files with BACEN through [Lerian STA](/en/rails/sta/what-is-lerian-sta).

| Variable | Default / Required | Description |
| - | - | - |
| `STA_CONSUMER_ENABLED` | `false` | Receive inbound files from the events that Lerian STA publishes. Requires `STREAMING_BROKERS`. |
| `STA_TRANSFERS_ENABLED` | `false` | Submit generated return files to Lerian STA for transmission to BACEN. Requires `PLUGIN_AUTH_HOST`. |
| `STA_SOURCE_PRODUCT` | **Required if either switch is on** | Source-product name that Lerian STA records for this rail. Use the value from your Lerian STA configuration. |
| `STA_OBJECT_STORAGE_ENDPOINT` | **Required if either switch is on** | Object-store endpoint that Lerian STA uses. It must resolve to the same store as `SEAWEEDFS_S3_ENDPOINT`. |
| `STA_BACEN_SYSTEM_CODE` | **Required if the consumer is on** | BACEN system code of the files to accept: `JUD` for SISBAJUD. |
| `STA_EXPECTED_TENANT_ST` | **Required if the consumer is on** | Tenant that Lerian STA stamps on its events in single-tenant mode. Set the `DEFAULT_TENANT_ID` of your Lerian STA deployment. The variable must exist, but an empty value is valid. |
| `STA_MAX_INBOUND_SIZE_BYTES` | **Required if the consumer is on** | Largest inbound file, in bytes, that the consumer downloads. It must be greater than 0. The example configuration uses `52428800`. |
| `STA_TRANSFERS_BASE_URL` | **Required if transfers are on** | Base URL of the Lerian STA API. |
| `STA_DOCUMENT_TYPE_AJUD302` | **Required if transfers are on** | Lerian STA document type for the block response. The example configuration uses `AJUD302`. |
| `STA_DOCUMENT_TYPE_AJUD309` | **Required if transfers are on** | Lerian STA document type for the information response. The example configuration uses `AJUD309`. |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Required if transfers are on** | Bucket shared with Lerian STA for outbound return files. It must name the same bucket as `STA_INBOUND_BUCKET`. |
| `STA_CLIENT_ID` | **Required if transfers are on** | OAuth client id that gets the token for Lerian STA. |
| `STA_CLIENT_SECRET` | **Required if transfers are on** | OAuth client secret for Lerian STA. Sensitive. |

## Midaz ledger connector

Lerian SISBAJUD reads balances and blocks through the Midaz ledger. Each institution's configuration sets the Midaz address, the authorization address, and the credentials. No environment variable sets them.

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | CRM surface that the connector queries to find a defendant's accounts: `legacy` or `embedded` (the CRM inside the Midaz ledger). An institution's own `crmMode` overrides it. Any other value fails the boot. |
| `MIDAZ_BALANCE_DEFAULT_ACCOUNT_TYPE` | `deposit` | Account type the service uses for a balance event when the blocked account has no recorded type. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.