Skip to main content

Post‑Installation: Data Directory Layout

After installation and first start, MAPS Messaging initializes a data directory (default ${MAPS_DATA}) that holds runtime state, logs, and optional embedded security data.

Directory Structure (example)​

${MAPS_DATA}/
├── .security/                 # embedded security assets (only if enabled)
├── destinations/              # durable message/persistence stores per namespace
├── licenses/                  # active license files
├── log/                       # messaging.log / audit.log (rotated)
├── sessions/                  # persistent client/session state
├── InstanceConfig.yaml        # generated instance settings
├── mapsMessaging.lock         # single-writer lock (for HA)
└── mapsMessaging.lock.heartbeat

.security/ exists only when embedded security is enabled (external IdPs like LDAP/OIDC won't populate it).

.security/ — Embedded Security Assets (if enabled)​

Contains credentials and materials used by the built‑in auth layer:

  • .auth.db — embedded auth database (binary).
  • .htgroups — group definitions (text).
  • .htpassword-enc — hashed user credentials.
  • authKeystore.jks — keystore for auth operations.
  • admin_password — one‑time file containing admin and user credentials in plain text.
Critical: remove admin_password

admin_password is created once on the first start to reveal initial credentials.
While this file exists, anyone with read access to ${MAPS_DATA}/.security/ can obtain the clear‑text passwords.

  • Log in immediately and rotate credentials.
  • Delete the file as soon as you have the passwords stored safely. 
    rm -f "${MAPS_DATA}/.security/admin_password"

Keep .auth.db, .htgroups, .htpassword-enc, and authKeystore.jks private. Limit access to the service account only.

destinations/ — Durable Message Stores​

Holds persistent storage for namespaces/queues/topics:

  • Includes message payloads, indices, and internal state necessary for recovery.
  • Back up this directory if you rely on persistence and retention.
  • Size grows with retained messages; tune retention/cleanup according to your workload.

sessions/ — Client/Session State​

Maintains persistent session information (e.g., subscriptions, inflight state) used for clean restarts and reconnects:

  • Preserve during upgrades for seamless client continuity.
  • If you delete it, clients may reconnect as fresh sessions.

licenses/ — License Files​

Place your license files here:

  • The server loads active licenses from this directory at startup.
  • Replace/renew licenses by updating files here and restarting the service (or follow your license reload procedure, if supported).

log/ — Operational & Audit Logs​

  • messaging.log — operational events (INFO by default).
  • audit.log — audit‑only entries (security‑relevant operations).
  • Rotated daily, compressed (*.log-YYYY-MM-DD.log.gz), 7‑day history by default.

See Logging for the default logback.xml and how to change levels/retention/paths.

mapsMessaging.lock* — HA Single‑Writer Guard​

These files prevent concurrent writers when multiple servers point to the same ${MAPS_DATA}:

  • Only one instance becomes the active writer; others remain passive/standby.
  • Useful for HA/failover designs where a standby should not write until promoted.

InstanceConfig.yaml — Generated Instance Settings​

A generated file with instance‑specific settings captured at first run or during configuration:

  • Treat as part of the node’s runtime state.
  • Back up alongside destinations/ and sessions/ if you need to fully restore a node.

Verify Post‑Install​

curl -s http://localhost:8080/api/v1/ping   # {"status":"Success"}
curl -s http://localhost:8080/health       # OK | Warning | Error

For metrics and dashboards, continue to Monitoring Overview and Prometheus (JMX Exporter).