Configuration, health, metrics, and deployment without shooting yourself in the foot.

When you expose a blockchain‑aware backend to the world, “it works on my laptop” is irrelevant.

You’re dealing with:

  • reorgs and mempool churn;
  • nodes that fall behind, stall, or get pruned;
  • RPC providers with rate limits and noisy latencies;
  • users who expect near‑real‑time data for Bitcoin, Cardano, Cosmos, Ethereum, and friends.

Spring Boot is a solid foundation, but production‑ready has a narrow meaning in this context: predictable configuration, honest health checks, actionable metrics, and deployments that keep working when nodes misbehave.

This is the mental model I use when I design these services.

1. What “production‑ready” means for blockchain services

For a blockchain microservice (indexer, wallet API, DEX backend, explorer API), “production‑ready” is not “no obvious bugs”. It’s:

- You can deploy the same artifact to dev/stage/prod
  without editing YAML over SSH.

- When a dependency (node, DB, RPC provider) fails,
  health checks and metrics tell you *before* users do.

- You can scale horizontally without corrupting state
  or double-processing blocks.

- You can roll out and roll back without downtime,
  even while chains are moving underneath you.

Spring Boot gives you the right primitives:

[ Spring Boot app ]
      |
      +-- Actuator (health/info/metrics)                         [Health]
      +-- externalized configuration (properties/YAML/env)       [Config]
      +-- Spring Cloud (Config Server, Vault, etc.)              [Secrets]
      +-- Micrometer (metrics facade, Prometheus, OTLP, etc.)    [Metrics]

Your job is to wire those primitives with blockchain‑specific constraints in mind. ([Home][1])

2. Architecture baseline: one service in the ecosystem

When I say “Spring Boot blockchain service”, I usually mean something like this:

                        +--------------------------+
                        |  spring-boot service     |
                        |--------------------------|
     HTTPS / gRPC <---- |  REST/gRPC API          |
                        |  business logic         |
                        |  block / tx processing  |
                        |  DB access              |
                        |  health / metrics       |
                        +-----------+-------------+
                                    |
             +----------------------+-------------------------+
             |                      |                         |
      [ Bitcoin node ]       [ Cardano node ]          [ Cosmos/EVM node ]
      RPC / ZMQ              Ouroboros mini-protocols  RPC / gRPC / WS

Around it:

[ Config Server / Vault ]    [ Prometheus / Grafana ]     [ Kubernetes / Nomad ]

The central box must remain boring to operate even when the nodes on the right are noisy or half‑broken.

3. Configuration management: stop hard‑coding your environment

Static YAML plus “just ssh and edit” is how blockchain backends silently become unmaintainable.

3.1 Externalise everything that changes per environment

At minimum, externalise:

  • database URLs and pool sizes;
  • timeouts, rate limits, retry policies.
  • per‑chain feature flags (enable/disable networks);
  • node endpoints and credentials (RPC URLs, gRPC targets, WebSocket URLs);

Spring Boot already supports a layered configuration model (properties, YAML, environment variables, command‑line args). ([baeldung.com][2])

Spring Boot supports a layered configuration model (properties, YAML, environment variables, command‑line args).

To keep things maintainable I prefer one configuration file with profiles over a forest of almost‑identical files. A common layout:

application.yml
  - shared defaults (logging, ports, base config)
  - "dev" profile: testnet nodes, local DB
  - "test" profile: staging infra, staging RPC providers
  - "prod" profile: mainnet nodes, tuned timeouts, real providers

Each profile section overrides only what it needs; everything else stays in the shared defaults. This reduces boilerplate, avoids copy‑paste drift between application-*.yml files, and plays well with environment overrides and Config Server. You still layer on top of this with environment variables or centralised config, but the shape of the configuration lives in a single place.

Everything secret (API keys, DB passwords, HSM credentials) moves out of Git and into a secure secrets store.

3.2 Centralised config and secrets (Config Server + Vault)

Once you have more than a couple of services, a central configuration and secrets system pays for itself.

  • Spring Cloud Config Server: central place for environment‑specific configuration served over HTTP; clients consume it as part of Spring’s Environment. ([Home][1])
  • Spring Cloud Vault: integration with HashiCorp Vault for secrets stored in dedicated backends instead of local files or env vars. ([Home][3])

Sketch:

               +-------------------------+
               |  Git / config repo      |
               +-----------+-------------+
                           |
                  Spring Cloud Config
                           |
             +-------------+-------------+
             |                           |
 [ wallet-api-service ]       [ indexer-service ]
  pulls env-specific props     pulls env-specific props
             |                           |
             v                           v
        Spring Cloud Vault           Spring Cloud Vault
             |                           |
        DB/RPC secrets              keys, RPC creds

This matters for blockchain because:

  • your RPC provider keys and DB credentials must rotate safely;
  • regulators care about how and where you store keys and secrets.
  • you typically run multiple networks (mainnet, testnet, preprod, private chains);

Vault + Spring Cloud let you reload some secrets without restarts, which is exactly what you want when rotating provider tokens or DB credentials at scale. ([HashiCorp Developer][4])

Here’s a revised From the trenches note you can paste in:

From the trenches. On multi‑chain indexers and wallet services, secrets management is not a “use Vault and move on” problem. You need disciplined key management: segregated credentials per chain, per environment, and often per service; no secret reused across unrelated systems; and a clear blast radius if one credential is compromised. On top of that you need procedures, not just tooling: who can issue keys, where they can be used, how they are rotated, and how quickly you can revoke them if something leaks. Vault (or similar) is the anchor, but the real safety comes from strict segregation, least‑privilege access, and automated rotation and revocation. In a multi‑chain setup, this isn’t bureaucracy – it’s the difference between a contained incident and an ecosystem‑wide outage.

4. Health checks that mean something

If /actuator/health always returns UP, it’s decoration, not observability.

Spring Boot Actuator provides a health abstraction with built‑in indicators (DB, disk, etc.) and lets you define custom ones. It also exposes liveness and readiness groups (/actuator/health/liveness, /actuator/health/readiness) designed for Kubernetes probes. ([Home][5])

4.1 Liveness vs readiness in a blockchain backend

I treat them as:

Liveness:
  "Is this JVM process fundamentally healthy?"
  - main event loop not wedged
  - thread pools not exhausted
  - no fatal internal error that requires a restart

Readiness:
  "Can this instance serve *correct* data right now?"
  - DB reachable and within latency SLO
  - required nodes or RPC providers reachable
  - index lag within acceptable bounds

Kubernetes uses:

  • liveness probes to decide when to restart a container; ([Kubernetes][6])
  • readiness probes to decide when to send it traffic. ([Kubernetes][7])

Spring Boot’s health groups map naturally to these probes when you deploy to Kubernetes. ([Home][5])

4.2 Making readiness blockchain‑aware

For an indexer or wallet API, readiness should drop when:

  • the primary DB is down or overloaded;
  • all upstream nodes/RPC providers for a chain are down or degraded;
  • your service’s notion of chain height lags the canonical tip by more than N blocks/seconds.

For example:

readiness = DOWN if db_status != UP
                 or rpc_backends_healthy == 0
                 or indexed_height < (chain_tip_height - MAX_ALLOWED_LAG)

That last condition is chain‑specific: on Bitcoin you might tolerate a few blocks of lag; on a fast EVM chain you might work in seconds.

From the trenches. On a BSC explorer backend we learned that “height lag” alone isn’t enough. Blockchains are quasi‑deterministic in block time: you know roughly how often new blocks should appear. We now track not only how far our indexed height is from the tip, but also the block indexing frequency itself – moving averages and standard deviation of “blocks indexed per minute” (or per slot/epoch), with alerts when the service diverges from the expected pattern. This gives us two independent signals: “are we caught up?” and “are we indexing at the expected pace?”. It matters because monitors fail too; relying on one metric is how you end up discovering, days later, that an account hasn’t updated and users open tickets. A simple statistically‑driven alert on indexing frequency would have told us within seconds that the indexer had silently stopped making progress.

5. Metrics and observability: see trouble before users do

Actuator + Micrometer give you a consistent way to expose metrics from Spring Boot apps. Add the Prometheus registry and Boot will auto‑configure a /actuator/prometheus endpoint ready for scraping. ([Home][8])

For blockchain services I always split metrics into three buckets:

1. Generic service metrics:
   - JVM memory, GC, threads
   - DB pool usage, slow queries
   - HTTP latency and error ratios

2. Node / provider metrics:
   - fallback counts (how often we fail over)
   - RPC latency and error rates per node/provider
   - reported chain height / sync status per backend

3. Domain-specific metrics:
   - observed reorg depth
   - current indexed height per chain
   - lag vs canonical tip (blocks or slots)
   - tx throughput (tx/s, tx per block) seen by the service

Prometheus + Grafana is still the standard combo: Prometheus scrapes /actuator/prometheus, Grafana visualises it. ([baeldung.com][9])

Very rough picture:

[ Spring Boot services ]
        |
        |  /actuator/prometheus (Micrometer metrics)
        v
   [ Prometheus ]  --->  [ Grafana dashboards ]
   time-series DB        chain lag, RPC health,
                         errors, latency, etc.

Two dashboards I rarely skip:

  • Chain lag view: indexed height vs a trusted node’s height, per chain.
  • RPC health: latency, error rate, and timeouts per upstream node/provider.

Those catch most slow‑bleed issues before users notice.

6. Deployment strategies that survive real nodes

Nodes and RPC providers are noisy; your deployment strategy has to assume that.

Spring Boot itself is deployment‑agnostic, but in practice the stack looks like:

Spring Boot fat JAR
   -> container image
      -> Kubernetes (or Nomad, ECS, etc.)
         -> autoscaling, probes, rolling updates

Kubernetes gives you liveness/readiness/startup probes; Boot’s Actuator is designed to feed them solid signals. ([Kubernetes][7])

Things I care about:

Rolling updates with protocol stability. Rolling updates mean old and new versions run side by side. For blockchain APIs, you must keep the external contract stable during that window: same JSON fields, same semantics, no sudden “height” definition changes. Internally you can evolve schemas and add metrics, but keep the external surface boring.

Graceful shutdown. Let the service:

  • stop accepting new traffic (readiness = DOWN),
  • finish in‑flight requests,
  • finish in‑flight block processing or checkpoint properly,

before the pod is killed. Combine Kubernetes terminationGracePeriodSeconds with Spring Boot’s lifecycle hooks and idempotent indexing logic so that replays are safe.

Horizontal scaling vs state. Stateless REST APIs are trivial to scale. Indexers are not. Decide up front how you parallelise:

  • by chain (one indexer per chain),
  • by partition (shard the keyspace),
  • by block height ranges with strict ownership.

Whatever you choose, ensure idempotence and a clear policy for “who owns which block”.

Environment parity. Dev/stage should mirror production topology (Kubernetes, Config Server, Vault, Prometheus) while pointing at testnets or private chains. If dev runs on docker-compose and prod runs on a hardened Kubernetes mesh, you will discover the interesting bugs in production.

7. A concrete example: cardano-tx-indexer

To make this less abstract, imagine a Spring Boot service:

cardano-tx-indexer:
  - HTTP API:
      GET /tx/{hash}
      GET /address/{addr}
  - Block/tx consumer: cardano-node (or Kafka with block events)
  - Storage: PostgreSQL
  - Health: Actuator
  - Metrics: Micrometer + Prometheus

I would build it roughly like this.

Configuration & secrets

  • All Cardano node endpoints, PostgreSQL URLs, and feature flags live in Spring Cloud Config (per environment). ([Home][1])
  • Vault stores DB passwords and any RPC provider tokens, exposed to the app via Spring Cloud Vault. ([Home][3])
  • Local application.yml just selects a profile (mainnet, preprod, testnet) and points to the config server.

Health

  • Liveness = JVM up, main processing loops healthy, no fatal internal error.
  • Readiness = PostgreSQL reachable; cardano-node reachable; indexed_slot within N slots of node_tip_slot (per chain/network). When lag exceeds N, readiness flips to DOWN and Kubernetes drains traffic.

Metrics

Expose generic metrics plus domain‑specific ones such as:

cardano_indexer_indexed_slot{network="mainnet"}
cardano_indexer_tip_slot{network="mainnet"}
cardano_indexer_reorg_events_total
cardano_rpc_latency_seconds{node="A", network="mainnet"}
cardano_rpc_errors_total{node="A", network="mainnet"}

These feed a dashboard that shows, for each network, whether you’re in lockstep with the chain and how healthy your nodes are.

Deployment

  • Containerised Spring Boot app, deployed to Kubernetes via Helm or Kustomize.
  • Probes wired to /actuator/health/liveness and /actuator/health/readiness. ([Home][5])
  • Rolling updates, max N% unavailable, with readiness gating traffic to new pods.
  • Termination hooks ensure that block processing can safely resume from the last confirmed height without double‑applying.

Testing

  • Integration tests with Testcontainers for PostgreSQL and a fake cardano-node (or a recorded block stream).
  • Tests that:
    • mark readiness DOWN when DB is down, and back to UP when it returns;
    • mark readiness DOWN when node is stuck or height lag is too high;
    • verify Prometheus metrics reflect index lag and RPC errors.

None of this is exotic. The “blockchain” part is how you define readiness and domain metrics; everything else is standard Spring Boot and Kubernetes.

8. Conclusion

Spring Boot is a good fit for blockchain backends, but what makes a service production‑ready isn’t the framework; it’s the contracts you establish around it:

Configuration:
  one source of truth, per environment, with secrets
  in Vault instead of YAML and shell history.

Health:
  liveness is "can this JVM be kept alive?",
  readiness is "can this instance serve correct chain data?".

Metrics:
  generic service metrics + domain metrics for lag,
  reorgs, and RPC health, exposed to Prometheus.

Deployment:
  rolling updates, graceful shutdown, and autoscaling
  that assume nodes and providers are noisy.

Once you treat configuration, health, metrics, and deployment as first‑class concerns, your Spring Boot services stop being “some Java glue in front of a node” and become reliable infrastructure components in a multi‑chain system.

That’s the point where you can safely plug them into wallets, explorers, launchpads, and DEXs—and sleep through most nights without being paged because a pruned node, a throttled RPC provider, or a stuck indexer quietly broke your API.

References & Further Reading