Skip to content

Admin Documentation [EN]

Jump to bottom
Nikita Hasert edited this page Oct 10, 2026 · 1 revision

Administrator Documentation

System Overview & Security Notice

Midas is an internal financial management application designed for tracking shareholder master data, bookings, interest calculations, and annual account statements.

Caution

Important Security Architecture Notice

Midas is intended to be run on an air gapped system, as there is no authentication or encryption of the data at rest implemented.

Any client capable of reaching the HTTP port has unrestricted read and write access to all stored financial and shareholder records. Deployments must enforce strict perimeter security, air-gapping, or network isolation (e.g., localhost binding, VPN, firewall restrictions, or reverse proxy authentication).

Technical Stack & Architecture

  • Runtime Environment: Java (OpenJDK recommended)
  • Application Framework: Spring Boot
  • UI Engine: Vaadin Flow (rendered server-side with standard web standards)
  • Embedded Database: SQLite
  • ORM & Persistence: Spring Data JPA / Hibernate Community SQLite Dialect
  • Schema Migration: Liquibase (automatically applies versioned changesets on application startup)
  • Packaging Formats:
    • midas-vaadin.jar: Standard executable desktop/server package with web UI.
    • midas-headless.jar: Headless edition for API-focused workflows without the Vaadin UI frontend.

Installation & Deployment

Prerequisites

  • Java Runtime: JRE or JDK version 21 or newer.
  • Operating System: Linux, macOS, or Windows.
  • File System Permissions: Read and write access to the working directory where the SQLite database (midas.db) and log files (logs/) reside.

Running the Application

Download the release JAR and execute it using standard Java commands:

java -jar midas-vaadin.jar

By default:

  • The application binds to port 8082.
  • The web interface is accessible at: http://localhost:8082
  • If running on a desktop environment with browser launching enabled, the default browser opens automatically upon startup.
  • If port 8082 is already in use by an active instance, Midas detects the existing instance and opens http://localhost:8082 in your browser rather than failing to bind the port.

Configuration Reference

Configuration properties can be set via:

  1. An external application.properties file in the current working directory.
  2. Java system properties (-Dkey=value).
  3. Environment variables (e.g., SERVER_PORT=8082).

Core Server & Database Settings

Property Default Value Description
server.port 8082 HTTP port on which the web application listens.
spring.datasource.url jdbc:sqlite:midas.db JDBC connection string pointing to the SQLite database file.
spring.datasource.driver-class-name org.sqlite.JDBC Database driver class.
spring.liquibase.change-log classpath:db/changelog/db.changelog-master.xml Master changelog path for automated schema migration.
midas.db.sqlite.optimize.enabled true Executes SQLite PRAGMA optimize on startup and graceful shutdown.
logging.file.name logs/midas-vaadin.log Destination path for the application log file.

Midas Application Settings (midas.*)

Title & Theme Configuration

  • midas.title.name (Default: Midas): Global application title displayed in the header navigation bar.
  • midas.theme.default-theme (Default: ""): Default visual theme ("dark" or empty string for light theme).

UI & Locale Configuration (midas.ui.* & midas.i18n.*)

  • midas.ui.currency-symbol (Default: €): Currency symbol displayed in tables, summaries, and dialogs.
  • midas.ui.hide-theme-toggle (Default: false): When true, hides the theme toggle option from the Settings page.
  • midas.ui.hide-language-selector (Default: false): When true, hides the language dropdown from the Settings page.
  • midas.ui.default-add-another-checkbox-state (Default: false): Default state for the "Add another" checkbox in the booking dialog.
  • midas.i18n.default-locale (Default: en): System fallback language code (en or de).
  • midas.i18n.force-default-language (Default: false): When true, prevents users from overriding the default language in the UI.

Business Logic & Shareholder Configuration (midas.shareholder.*)

  • midas.shareholder.delete-mode (Default: CASCADE):
    • CASCADE: Deleting a shareholder removes all associated bookings, opening balances, locks, and account statement overrides.
    • RESTRICT: Disables the Delete button in the Shareholders UI if any associated records exist, requiring manual cleanup first.

Desktop Lifecycle & Auto-Shutdown (midas.desktop.*)

  • midas.desktop.launch-browser (Default: true): When true, automatically launches the default system browser to the application URL upon startup.
  • midas.desktop.auto-shutdown-enabled (Default: true): Enables desktop auto-shutdown. When all active browser sessions/tabs are closed, the application initiates a graceful shutdown. Set to false for persistent server deployments.
  • midas.desktop.grace-period (Default: PT60S / 60 seconds): Time window before the process exits once active UI connections drop to zero.

Data Cleanup (midas.cleanup.*)

  • midas.cleanup.enabled (Default: true): Enables background scheduled cleanup tasks.
  • midas.cleanup.cutoff (Default: P10Y / 10 years): Retention period for historical audit data.
  • midas.cleanup.delay-between-cleanups (Default: PT1H / 1 hour): Interval between execution of background cleanup tasks.
  • midas.cleanup.limit (Default: 1000): Batch limit per cleanup cycle.

Database Management & Migrations

Midas persists data into a single SQLite file (midas.db by default) located in the execution directory.

Schema Migrations (Liquibase)

  • Database schema versioning is managed by Liquibase changelogs located in midas-persistence-sqlite.
  • Changesets are executed sequentially and transactionally upon application startup.
  • System tables created and maintained by Liquibase:
    • DATABASECHANGELOG
    • DATABASECHANGELOGLOCK
  • Core domain tables include:
    • midas_shareholders: Shareholder master records (id, display_id, first_name, last_name).
    • midas_bookings: Individual transactions (date, amount, comment, type, source, shareholder_id).
    • midas_opening_balances: Annual opening balance entries per shareholder (year, amount, source).
    • midas_interest_rates: Configured annual interest rates per shareholder and year.
    • midas_locked_years: Records of finalized/locked years per shareholder.
    • midas_account_statement_overrides: Custom manual entries and visibility exclusions for account statements.
    • midas_account_statement_orders: Custom display order sequences for statement rows.
    • midas_comment_templates: Predefined comment suggestions and assigned booking types.
    • midas_user_config: User settings such as active theme and language preferences.
    • midas_backup_status: Timestamp and record of the last successful backup.

Warning

Do not modify existing Liquibase migration scripts or alter the schema directly via external SQLite tools, as this may corrupt the Liquibase checksum log and prevent the application from starting.

Backup, Restore & Disaster Recovery

In-App Backup

  • The application provides a built-in backup function via the web interface at <base-url>/backup or the core backup service.
  • Creating a backup takes a snapshot of the SQLite database and packages it into a downloadable .zip archive.
  • The backup event is tracked in midas_backup_status.

Manual File-Level Backup

Because SQLite stores all data in a single file (midas.db), external backup strategies can also be implemented via standard filesystem snapshots or scheduled scripts:

# Cold backup when the application is stopped:
cp midas.db backups/midas_$(date +%Y%m%d_%H%M%S).db

# Live backup using sqlite3 CLI:
sqlite3 midas.db ".backup 'backups/midas_$(date +%Y%m%d_%H%M%S).db'"

Recovery

To restore a backup:

  1. Stop the Midas process.
  2. Replace the active midas.db file with your verified backup copy.
  3. Start the application. Liquibase will verify the schema and resume normal operation.

Logging & Troubleshooting

Log Locations

  • Standard output and file logging are configured out of the box.
  • The default log file path is logs/midas-vaadin.log.
  • Archived log rotations are compressed automatically (e.g. midas-vaadin.log.YYYY-MM-DD.0.gz).

Common Issues & Solutions

  • Port Conflict (java.net.BindException: Address already in use):
    • Another service or instance of Midas is already running on port 8082.
    • Specify an alternate port using --server.port=9090 or stop the existing process.
  • Premature Shutdown After Closing Browser:
    • This is expected behavior when midas.desktop.auto-shutdown-enabled=true is configured.
    • For perpetual installations, set midas.desktop.auto-shutdown-enabled=false.
  • Database File Lock (org.sqlite.SQLiteException: [SQLITE_BUSY] database is locked):
    • Ensure multiple processes are not accessing the same midas.db concurrently.

Clone this wiki locally