Spring Boot in Real Production: What My Lakaut Codebase Taught Me That the Official Docs Leave Out

A datasource pool is basically like the ticket booth at a sold-out stadium show. When the crowd is light, everything works perfectly — people show up, grab their spot, walk in. But when the stadium fills up all at once and 300 people are trying to get through the gate simultaneously, the whole system collapses. Not because it's broken. Because it was never designed for that peak moment. And the official Spring Boot documentation shows you the empty ticket booth. It never shows you the concert.

That's exactly what I ran into at Lakaut Hub — the core system for Lakaut AC, the digital certification authority where I work as architect. Real production. Real load. Logs that don't lie.

My thesis is an uncomfortable one: Spring Boot is documented for an idealized environment that doesn't exist on PaaS platforms like Railway. The defaults are built for local development with infinite resources, and in production with real JVM tuning and PostgreSQL connections under load, those defaults will burn you. I know because I have the logs.

The spring.jpa.open-in-view Problem Nobody Explains Seriously

When I started on Lakaut Hub, the app booted, worked fine, and somewhere in the logs there was a warning I ignored for weeks:

WARN  o.s.b.autoconfigure.orm.jpa.JpaBaseConfiguration$JpaWebConfiguration
      - spring.jpa.open-in-view is enabled by default.
        Therefore, database queries may be performed during view rendering.
        Explicitly configure spring.jpa.open-in-view to disable this warning

open-in-view=true is the default. What that means in practice: the Hibernate session stays open for the entire lifecycle of the HTTP request, from the moment the request comes in until the response finishes rendering. The docs mention it. What they don't tell you is what it costs you in terms of datasource pool connections held under load.

I measured this directly in Lakaut Hub with Actuator enabled:

# application.yml — before the fix
spring:
  jpa:
    open-in-view: true  # silent default that eats your connections

With an endpoint making multiple JPA queries, every request was holding a connection from the pool from the moment it entered until the JSON response went out — including any business logic, validations, and serializations that didn't need the database at all. With 50 concurrent requests during peak moments at Lakaut Hub, we started seeing connection pool acquisition timeouts. It wasn't a bug in the app. It was the default.

The fix is one line, but the understanding is what matters:

# application.yml — after the fix
spring:
  jpa:
    open-in-view: false  # release the connection back to the pool as soon as you're done with the DB
  datasource:
    hikari:
      maximum-pool-size: 10       # for Railway: don't exceed what your plan supports
      minimum-idle: 5             # don't start from zero on every spike
      connection-timeout: 20000   # 20s before throwing HikariTimeoutException
      idle-timeout: 300000        # release idle connections after 5 min
      max-lifetime: 1200000       # 20 min max lifetime per connection

The p95 response time on Lakaut Hub's most critical endpoint dropped noticeably after this change. I don't have a magic number to show you because load conditions vary, but the trend in the Actuator logs was clear and immediate. If you're running JPA on Railway, turn off open-in-view from day one.

JVM Tuning on Railway: The Defaults Kill You in Containers

This is the most dangerous gotcha, and the one that took me the longest to understand.

Railway runs the JVM inside a container. The JVM, by default, reads resources from the physical host — not the container. By 2026 this is mostly addressed with container-aware flags, but the problem is more subtle: Spring Boot doesn't explicitly tell you which flags to pass to the JVM, and the default garbage collector isn't tuned for a container with 512MB or 1GB of RAM.

When I first deployed Lakaut Hub on Railway, the startup time was erratic:

# Railway log — startup without tuning
Started LakautHubApplication in 18.432 seconds (process running for 19.1)

Eighteen seconds. For a service that needs to be available and responding to digital certificate requests. Unacceptable.

The problem was twofold: automatic heap sizing that didn't respect container limits, and the default GC (G1GC) configured for large heaps. I adjusted the Dockerfile and Railway's JAVA_OPTS:

# Dockerfile — Lakaut Hub
FROM eclipse-temurin:21-jre-alpine

# Copy the jar from the build stage
COPY --from=builder /app/target/lakaut-hub.jar app.jar

# Explicit flags for containers: tell the JVM to read container limits
ENTRYPOINT ["java", \
  "-XX:+UseContainerSupport", \
  "-XX:MaxRAMPercentage=75.0", \
  "-XX:InitialRAMPercentage=50.0", \
  "-XX:+UseZGC", \
  "-XX:+ZGenerational", \
  "-Dspring.profiles.active=production", \
  "-jar", "app.jar"]

Why ZGC and not G1GC: in a container with limited memory, G1GC pauses become unpredictable under load. ZGC with generational mode (available since Java 21) has sub-millisecond pauses and performs better in environments where heap is bounded. That's not theory — I measured it on Railway with startup logs:

# Railway log — after tuning
Started LakautHubApplication in 6.891 seconds (process running for 7.4)

From 18 seconds to 7. Without touching a single line of business code. Just JVM flags and a GC switch.

The official Spring Boot docs don't cover this. There's a section on "Optimizing Startup Time" that mentions lazy initialization, but JVM tuning for containers on specific PaaS platforms isn't there. You're on your own, with the logs and trial and error.

The @Transactional Proxy Gotcha That Cost Me an Incident

This is the one I'm most embarrassed to document, but also the most useful.

Spring Boot implements @Transactional through AOP proxies. The basic rule is: if you call a @Transactional method from within the same class, the proxy gets bypassed and the transaction doesn't exist. The docs say so. What they don't tell you is which real-world scenarios make this explode silently.

In Lakaut Hub we have a digital certificate issuance service. Simplified, it looked like this:

@Service
public class CertificateService {

    // This method DOES have a transaction — called from outside
    @Transactional
    public void issueCertificate(IssuanceRequest request) {
        validateRequest(request);
        persistCertificate(request);
        // SILENT ERROR: this calls a method on the same class
        notifyIssuance(request);
    }

    // This method also has @Transactional, but it will NEVER participate
    // in a separate transaction because Spring can't intercept it —
    // it's called directly (this.notifyIssuance), not through the proxy
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    private void notifyIssuance(IssuanceRequest request) {
        // We wanted this to run in its own transaction
        // so a failure here wouldn't roll back the certificate issuance.
        // It never did. And there was no error — it just ran in the same tx.
        logNotificationService.register(request.getCertificateId());
    }
}

The result: when notifyIssuance failed, it rolled back the entire issueCertificate transaction. The certificate was lost. The incident lasted two hours diagnosing why there were issuances showing up in the business logs but not in the database.

The fix requires breaking the self-invocation. There are several approaches — the cleanest in our case was separating the service:

@Service
public class CertificateService {

    private final NotificationService notificationService; // separate service

    @Transactional
    public void issueCertificate(IssuanceRequest request) {
        validateRequest(request);
        persistCertificate(request);
        // Now it goes through the Spring proxy — separate transaction guaranteed
        notificationService.notifyIssuance(request);
    }
}

@Service
public class NotificationService {

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void notifyIssuance(IssuanceRequest request) {
        // This one actually runs in its own transaction
        logNotificationService.register(request.getCertificateId());
    }
}

The interesting part is that this gotcha is decades old. It's in the documentation, on Stack Overflow, in Spring books. And I still hit it in production in 2026, in a codebase I wrote myself. Because in the domain context, the separation of responsibilities wasn't obvious until the incident made it obvious.

Debugging concurrency in production is similar to what I described in the post about mutex deadlock in Rust and diagnostic patterns in a real codebase — the lesson is the same: concurrency and transaction problems are silent until they aren't.

Application Context Under Restart and the Railway Gap

Last gotcha, and the most PaaS-specific one.

Railway does zero-downtime deployments using rolling restarts. When you push a new version, there's a window where the old instance and the new one run simultaneously. With Spring Boot and state in the ApplicationContext, this can produce weird conditions if you have stateful beans or in-memory caches that initialize at startup.

In Lakaut Hub we have a CRL (Certificate Revocation List) cache that initializes at startup from the database. During the rolling restart, the new instance would boot with an empty cache and start serving requests before the cache was warm. The first 30–60 seconds of a new instance had noticeably higher latencies.

The fix was implementing a real health check that Railway uses to determine when the instance is actually ready:

@Component
public class CrlCacheHealthIndicator implements HealthIndicator {

    private final CrlCacheService crlCacheService;

    @Override
    public Health health() {
        // Railway won't send traffic until this returns UP
        if (!crlCacheService.isWarmedUp()) {
            return Health.down()
                .withDetail("reason", "CRL cache still loading")
                .withDetail("entriesLoaded", crlCacheService.getLoadedCount())
                .build();
        }
        return Health.up()
            .withDetail("crlEntries", crlCacheService.getLoadedCount())
            .build();
    }
}

# application.yml — health check configuration for Railway
management:
  endpoints:
    web:
      exposure:
        include: health, metrics, info
  endpoint:
    health:
      show-details: always
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

And in railway.toml:

[deploy]
healthcheckPath = "/actuator/health/readiness"
healthcheckTimeout = 60  # seconds Railway waits before considering the deploy failed

Without this, Railway assumes the instance is ready as soon as the port is open. And Spring Boot's port is open before the ApplicationContext finishes initializing completely. Railway's docs don't mention this for Java. Spring Boot's docs don't talk about Railway. You're in the gap.

That kind of gap between what a provider promises and what happens in real production reminds me of the analysis I did on supply chain attacks in npm where the scanner doesn't see everything — the official promise and reality always have a distance that only closes with your own evidence.

Common Mistakes That Aren't in the Official Docs

1. Trusting spring.datasource.url without ?sslmode=require on Railway PostgreSQL
Railway PostgreSQL requires SSL. Without the explicit parameter, some versions of the JDBC driver connect without SSL and the connection fails silently or with cryptic messages. Always: ?sslmode=require&sslrootcert=system.

2. Using spring.jpa.hibernate.ddl-auto=update in production
The docs advise against it. People use it anyway. In Lakaut Hub I found it in a PR branch that almost reached main. update can lose data on non-trivial migrations. In production: validate + Flyway or Liquibase, always.

3. Ignoring startup warnings
open-in-view, lazy initialization disabled without justification, beans with duplicate names — Spring Boot logs these as WARN and people ignore them. I ignored them. It cost me weeks of diagnosis that could have been avoided with ten minutes of reading the first deploy's logs.

4. Not separating profiles by environment
A single application.properties for everything. Lakaut Hub started that way. The problem is that dev values (small heap, minimal pool, verbose logging) end up in production by default. Separating into application-production.yml with the correct values is mandatory from day one, not after the problem is already there.

FAQ — Spring Boot in Real Production

What datasource pool size do you recommend for Railway with PostgreSQL?
It depends on your Railway plan and the connection limits of the Postgres server. As a starting point: maximum-pool-size between 5 and 10, minimum-idle at half that. HikariCP's formula suggests (cores * 2) + spindle_disks, but on Railway you need to measure what connection limit your plan has and not exceed it across all instances.

ZGC or G1GC for Spring Boot in containers?
For Java 21+ in containers with bounded heap (512MB–2GB), ZGC Generational is my current choice. G1GC works well with large heaps (4GB+). With limited memory on Railway, G1GC pauses become unpredictable. I measured the switch in Lakaut Hub and the difference was clear in startup time and p99 latency.

How do you diagnose a connection pool problem in production without direct database access?
Spring Boot Actuator with the /actuator/metrics/hikaricp.connections endpoint gives you real-time pool state: active, idle, pending, timeouts. If hikaricp.connections.pending climbs, the pool is saturated. If hikaricp.connections.timeout has any non-zero values, you've already had real timeouts.

@Transactional at the Controller layer or only in Service?
Only in Service. Never in Controller. The Controller shouldn't know anything about transactions — mixing concerns there breaks layer separation and makes it harder to test business logic in isolation. At Lakaut Hub we have this as a code review checklist rule.

What's the difference between liveness and readiness in Spring Boot Actuator?
liveness says whether the app is alive (if it fails, Railway/Kubernetes restarts it). readiness says whether it's ready to receive traffic (if it fails, Railway pulls traffic but doesn't restart it). For cache warmup and the startup gap, readiness is the one you care about. Configuring only a generic health without separating these two states means you're throwing away half the value of health checking.

Is Spring Boot worth it for small projects, or is it overkill?
Depends on the context. For Lakaut Hub, where the domain is complex (PKI, X.509 certificates, CRLs, TSA), the Spring Security, Spring Data JPA ecosystem and Bouncy Castle integration justify the overhead. For a simple CRUD with three endpoints, Quarkus or Micronaut will probably start faster and use less memory. The question isn't "is Spring Boot good?" but "what does this specific problem actually need?"

The Docs Are the Starting Point, Not the Destination

Three years running Spring Boot in real production at Lakaut AC left me with one conviction: the official documentation is an onboarding guide, not an operations manual. It's written to get your app running. Not to survive a sold-out stadium show.

The four gotchas I documented here — open-in-view and the pool under load, JVM tuning for Railway containers, @Transactional proxies and self-invocation, and the readiness gap in rolling restarts — aren't bugs in Spring Boot. They're design decisions that make sense in the context they were made in. The problem is that context isn't real production on a PaaS with limited resources.

What I don't buy from the Spring ecosystem in 2026 is the tendency to hide complexity under defaults that look magical. open-in-view=true by default is a design choice made so tutorials work without extra configuration. In real production, that default has a price tag. The log disclaimer is useful but insufficient.

What I do accept: when Spring Boot is properly configured and genuinely understood, it's a solid stack for complex domains. Lakaut Hub runs on Railway with JVM 21, PostgreSQL, and the gotchas documented here are resolved. The system issues digital certificates in production every single day. The docs didn't get me there — the logs did.

If you're running Java in production and you've hit gotchas that aren't here, I want to know about them. I'm building out the Java category on this blog from evidence, not from tutorials. There's a lot more to document.

If production diagnosis using real logs is useful to you, I also documented the real guardrails analysis for autonomous agents after a concrete incident — the evidence-first approach applies equally to complex distributed systems.

This article was originally published on juanchi.dev