Skip to main content

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.

​
Pre-upgrade checklist

1
Backup existing Helm releases:
helm get values -n midaz midaz > midaz-v4-backup.yaml
2
Decision required: Choose your deployment strategy (Ledger service or legacy Onboarding/Transaction).
3
If migrating to Ledger service, prepare new secrets with module-specific prefixes.
4
Schedule a maintenance window.

​
Breaking changes in v5.x

​
New Ledger service available

Starting from version 5.0, the Ledger service is available (ledger.enabled: false by default). When enabled, this service combines the functionality of both onboarding and transaction modules into a single deployment.
The separate onboarding and transaction services will become legacy in a future release. The unified Ledger service will become mandatory. We strongly recommend planning your migration to the Ledger service.
Default values:
Settingv4.x (before)v5.x (after)
ledger.enabledN/Afalse
onboarding.enabledtruetrue (auto-disabled when ledger is enabled)
transaction.enabledtruetrue (auto-disabled when ledger is enabled)
Impact when enabling Ledger:
  • The midaz-onboarding and midaz-transaction deployments will be removed.
  • A new midaz-ledger deployment will be created.
  • Ingresses will automatically redirect to the Ledger service (DNS compatibility maintained).
  • Environment variables and secrets structure changes (module-specific prefixes).

​
App version bump

Midaz has been bumped to v3.5.3.
Check the app changelog for the complete list of changes.

​
Migration options

​
Option 1: keep using Onboarding and Transaction (gradual migration)

Add the following to your values override to maintain the current behavior: 
ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true
This allows you to upgrade the chart version without changing your infrastructure.

​
Option 2: run all services simultaneously (testing/migration period)

Use the hidden migration.allowAllServices flag to run all three services during the migration: 
ledger:
  enabled: true

onboarding:
  enabled: true

transaction:
  enabled: true

migration:
  allowAllServices: true
This mode is intended for testing and migration only. Do not use in production long-term.
Accept the new architecture and migrate to the unified Ledger service:
1
Before upgrading: Ensure your databases are ready (same databases, new environment variable names).
2
Update secrets: Create new secrets with module-specific prefixes (see Configuration reference).
3
Upgrade: Run helm upgrade with the new chart version.
4
Verify: Check that the Ledger service is healthy and ingresses are working.
ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

​
New features in v5.x

​
Unified Ledger service

A new Ledger service that combines onboarding and transaction modules into a single deployment. Key characteristics:
  • Single HTTP endpoint (port 3000 by default)
  • Separate database configurations for each module
  • Shared Redis and RabbitMQ connections
  • New Balance Sync Worker for background processing
New environment variables: 
# Balance Sync Worker
BALANCE_SYNC_WORKER_ENABLED: "false"
BALANCE_SYNC_MAX_WORKERS: "5"
These environment variables have been renamed in later versions. The current variable names are: BALANCE_SYNC_BATCH_SIZE, BALANCE_SYNC_FLUSH_TIMEOUT_MS, and BALANCE_SYNC_POLL_INTERVAL_MS. See the Configuration Reference for current defaults.

​
Ingress redirection to Ledger

When Ledger is enabled, existing ingresses automatically redirect traffic to the Ledger service, maintaining DNS compatibility.
ledger.enabledmigration.allowAllServicesonboarding ingress targettransaction ingress target
falsefalse (default)midaz-onboardingmidaz-transaction
truefalse (default)midaz-ledgermidaz-ledger
truetruemidaz-onboardingmidaz-transaction

​
CRM service integration

The CRM service is now available as an integrated component, moving from midaz-plugins to midaz namespace.
For more details, refer to the CRM Documentation.
Migration from plugin-crm:
1
Deploy the new CRM in the midaz namespace:
crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"
    MONGO_NAME: "crm"
2
Migrate your data from the old MongoDB to the new one (if using separate databases).
3
Update your ingress/DNS to point to the new CRM service.
4
Remove the old plugin-crm release from midaz-plugins namespace.

​
Upgrade command

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz

​
Rollback procedure

# List release history
helm history midaz -n midaz

# Rollback to previous version
helm rollback midaz <REVISION> -n midaz

# Or explicitly disable ledger
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --set ledger.enabled=false \
  --set onboarding.enabled=true \
  --set transaction.enabled=true \
  -n midaz

​
Common issues

Ledger service fails to start
  • Verify that all module-specific environment variables and secrets are configured with the new prefixes (DB_ONBOARDING_*, DB_TRANSACTION_*, etc.).
Ingress not routing to Ledger
  • Ensure ledger.enabled: true and migration.allowAllServices is not set to true.
Missing secrets after enabling Ledger
  • Create new secrets with module prefixes:
    • DB_ONBOARDING_PASSWORD instead of DB_PASSWORD
    • DB_TRANSACTION_PASSWORD instead of DB_PASSWORD
    • MONGO_ONBOARDING_PASSWORD instead of MONGO_PASSWORD
    • MONGO_TRANSACTION_PASSWORD instead of MONGO_PASSWORD