Java Code Geeks

Testcontainers + Spring Boot 4: The Integration Test Setup Teams Actually Use

Eleftheria Drosopoulou — Wed, 26 Aug 2026 16:01:00 +0000

Testcontainers + Spring Boot 4: The Integration Test Setup Teams Actually Use

Not a getting-started guide. The opinionated patterns teams converge on once the novelty wears off and the suite has to run in CI a hundred times a day.

Every Testcontainers tutorial teaches the same first step, annotate a field with @Container, drop in @Testcontainers, watch a database spin up. That setup works for one test class. It falls apart at the tenth, when your suite is spending more time starting Postgres than running assertions. This is the setup that teams actually land on once that happens, updated for Spring Boot 4 and Spring Framework 7, which changed more about test startup than most migration guides mention.

Pattern One: Singleton Containers, Not @Container Lifecycle

The default JUnit 5 extension, @Testcontainers plus @Container, starts a container before a test class and stops it after. That’s fine once. It’s expensive across twenty test classes, and Testcontainers’ own documentation is explicit that this extension has only been tested against sequential execution, parallel use is unsupported and can have unintended side effects. The pattern teams actually converge on skips that extension entirely for shared infrastructure, and starts the container exactly once, in a static initializer on a base class every integration test extends.

abstract class AbstractIntegrationTest {

    @ServiceConnection
    static final PostgreSQLContainer<?> POSTGRES =
        new PostgreSQLContainer<>("postgres:17-alpine");

    static {
        POSTGRES.start();
    }
}

class OrderServiceTest extends AbstractIntegrationTest {
    // reuses the same running container, no @Testcontainers, no @Container
}

The mistake everyone makes once: combining this pattern with @Testcontainers and @Container on the same base class. The extension stops the container after the first test class finishes, so every subsequent class inherits a base class pointing at a dead container. Spring’s test context caching keeps the old context around, and you get connection failures that look like flakiness but are actually a lifecycle bug in the setup itself. The fix is to leave those two annotations off entirely for anything meant to be shared.

Cumulative container startup time across a ten-class suite, illustrative, based on a documented case study of PostgreSQL containers averaging 30-60 seconds each to start.

Pattern Two: @ServiceConnection Instead of @DynamicPropertySource

Before @ServiceConnection existed, wiring a container’s connection details into the Spring context meant a @DynamicPropertySource method, manually reading the container’s JDBC URL, username, and password, and pushing each one into a property key by hand. @ServiceConnection replaces all of that with one annotation on the container field itself. Spring Boot detects the container type, or the Docker image name for a generic container, and automatically creates the matching ConnectionDetails bean, no property keys to get wrong.

Old approach	@ServiceConnection
Manual `@DynamicPropertySource` method per container	One annotation on the container field or bean
Property keys typed out by hand, easy to typo	Connection details generated automatically from the container type
Breaks silently if a property key changes upstream	Tracks the auto-configuration directly, no property keys involved
Works for whatever you wire up manually	Built-in support for Postgres, MySQL, MongoDB, Redis, Kafka, RabbitMQ, and a growing list of others in Spring Boot 4

Spring Boot 4 keeps extending that built-in list, MongoDB’s Atlas local container support shipped as a @ServiceConnection target in this release specifically. The annotation isn’t tied to the @Testcontainers extension either, it works just as well on a manually started static field, which is exactly what makes it compatible with the singleton pattern above.

Pattern Three: Reuse Is Not a Substitute for Singleton

Testcontainers ships a separate feature called container reuse, .withReuse(true) plus testcontainers.reuse.enable=true in a local ~/.testcontainers.properties file, which keeps a container alive after the JVM exits so the next test run can find and reuse it instead of starting fresh. It’s genuinely useful, and it’s also frequently confused with the singleton pattern, to the point that Testcontainers’ own documentation states directly that reuse does not replace a proper shared instance for improving test performance.

The distinction matters because the two solve different problems. The singleton pattern eliminates redundant startups within a single test runacross separate test runs, useful on a developer’s laptop running the same suite repeatedly during TDD, but explicitly unsuited for CI, where you generally want a clean container per run rather than one that’s been accumulating state from every previous build. Teams that reach for reuse as their primary speedup mechanism in CI are optimizing for the wrong axis.

Where each mechanism actually belongs

Singleton base class: always, it’s what makes a multi-class suite fast in both CI and local runs.
Container reuse: local development only, layered on top of the singleton pattern, never relied on as the sole speedup in a pipeline that spins up a fresh environment each run.
@ServiceConnection: always, it’s strictly less code than manual property wiring with no real downside.

Pattern Four: Parallel Isolation, Told Honestly

Running integration tests in parallel is where most of the advice online quietly stops being precise. Yes, JUnit 5 supports parallel execution through junit.jupiter.execution.parallel.enabled=true. Yes, a shared singleton container works fine with it, in the sense that it will still be running and reachable from multiple threads. What doesn’t automatically follow is data isolation, a shared Postgres container doesn’t know or care that two test classes are hitting the same tables at the same time, and Testcontainers’ own JUnit 5 extension documentation, again, only claims to have been validated for sequential runs.

The pattern that actually holds up in practice separates two concerns that tutorials tend to blur together: container-level concurrency, which the singleton pattern already handles by not relying on the untested extension lifecycle, and data-level concurrency, which is entirely your application’s responsibility. A configuration teams reach for often is parallelizing across classes while keeping methods within a class sequential:

# junit-platform.properties
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=same_thread
junit.jupiter.execution.parallel.mode.classes.default=concurrent

That configuration alone doesn’t stop two classes from stepping on the same row. The actual isolation still has to come from the test data itself, cleaning tables in a @BeforeEach, wrapping each test in a transaction that rolls back, or giving each test class its own schema or keyspace inside the shared container. None of that is automatic, and any article that implies parallel execution plus a shared container is isolation by itself is skipping the part that actually takes engineering effort.

What Spring Boot 4’s AOT Changes Do to Test Startup

This is the part of the migration most teams underestimate. Spring Boot 4 and Spring Framework 7 lean much further into Ahead-of-Time processing than Spring Boot 3 did, and it changes the cost profile of every @SpringBootTest that loads a full application context.

Reported startup improvement from Spring Data AOT, which moves query generation from runtime reflection to compile-time source generation. Figures as reported across multiple Spring Boot 4 release write-ups.

Two changes do most of the work. Spring Data AOT turns repository query methods into generated source code at build time instead of parsing them via reflection when the context starts, which is where the widely cited 50 to 70 percent faster startup figures for Spring Boot 4 actually come from. Separately, Spring Boot 4’s autoconfiguration modules were broken apart into smaller, more focused jars, which means less classpath scanning during context startup regardless of how many repositories your test actually touches. Combined with BeanRegistrar, a reflection-free way to register beans that the AOT compiler can process at build time, the net effect for a heavy @SpringBootTest suite is a noticeably shorter wait before your containers and your context are both actually ready.

The gotcha teams hit during migration: Spring Boot 4.1 removed the ability to skip AOT processing of tests with Maven’s -DskipTests flag. The Spring Boot Maven plugin now only reacts to maven.test.skip, so a CI step that used to skip test compilation with -DskipTests can silently behave differently after upgrading, worth checking explicitly rather than discovering it mid-pipeline.

What We Learned

The Testcontainers setup teams actually run once a suite matures looks different from the getting-started tutorial in four specific ways. Containers are started once, in a static initializer on a base class, deliberately bypassing the @Testcontainers/@Container lifecycle that Testcontainers itself only claims to have validated for sequential execution. @ServiceConnection replaces manual property wiring outright, with no real downside, and it works fine on that same manually managed static field.

Container reuse is a genuinely useful local-development optimization that Testcontainers’ own documentation is explicit is not a substitute for the singleton pattern, and treating it as your CI speedup strategy is a category error. Parallel execution is safe at the container level once you’ve adopted the singleton pattern, but data isolation between concurrently running tests is still entirely on you, no configuration flag does that part for you. And Spring Boot 4’s AOT investment, Spring Data AOT repositories and modularized autoconfiguration in particular, genuinely shortens the time between “container is up” and “context is ready,” with one real migration gotcha around Maven’s test-skipping flag worth checking before you assume your pipeline still behaves the way it used to.

Tags

Spring AI with Local LLMs Using LM Studio

Yatin Batra — Wed, 26 Aug 2026 14:19:00 +0000

Enterprise Java

Spring AI with Local LLMs Using LM Studio

Large Language Models (LLMs) are commonly accessed through cloud APIs provided by services such as OpenAI, Anthropic, or Google Gemini. However, there are many situations where developers may want to execute an LLM locally instead. Running an LLM locally can be useful for development, experimentation, privacy-sensitive applications, offline environments, and situations where calling an external AI service for every request is unnecessary. LM Studio makes running local language models relatively simple by allowing developers to download and execute compatible open-source models and expose them through an HTTP API. More importantly for Java developers, LM Studio provides an OpenAI-compatible API. Spring AI already supports the OpenAI API format, allowing a Spring Boot application to communicate with LM Studio without creating a custom HTTP client.

1. Understanding Local LLMs and LM Studio

In this article, we will build a simple Spring Boot application that integrates with a local Large Language Model (LLM) running in LM Studio using Spring AI. The overall flow is straightforward: a client sends a question to the Spring Boot REST API, the controller passes the prompt to Spring AI, and Spring AI sends an OpenAI-compatible request to LM Studio. LM Studio then forwards the prompt to the locally loaded LLM, which generates a response and returns it through LM Studio and Spring AI back to the Spring Boot application, where the final answer is sent to the client.

1.1 What is a Local LLM?

A local LLM is a language model that runs directly on your computer or on infrastructure you control, rather than relying on an external cloud-based AI service. This means prompts, such as “Explain dependency injection in Java,” can be processed locally without being sent to a third-party API. Popular model families that can be run locally include Llama, Mistral, Qwen, Gemma, Phi, and DeepSeek. The right model depends on factors such as available system memory, CPU or GPU capabilities, desired response quality, model size, and expected inference speed.

1.1.1 Why Use Local LLMs?

Running LLMs locally provides several advantages, particularly for privacy, cost, and development flexibility. Since prompts can be processed directly on the local machine, sensitive information does not need to be sent to an external AI provider. Once a model has been downloaded, it can also perform inference without an active Internet connection, making it useful for offline environments. Local models do not have per-request API charges because they use your own computing resources, although hardware and electricity costs still apply. They are also convenient for developing and testing AI-powered applications without repeatedly calling external services. In addition, developers have greater control over which model is used, how it is configured, and where the inference process takes place.

1.2 What is LM Studio?

LM Studio is a desktop application that allows developers to download, load, and run LLMs locally. One of its most useful features is the built-in local API server, which is commonly available at http://localhost:1234. LM Studio exposes OpenAI-compatible endpoints such as GET /v1/models, POST /v1/chat/completions, and POST /v1/embeddings. For this example, the most important endpoint is POST http://localhost:1234/v1/chat/completions, which is used to send prompts to the locally running model. Since Spring AI already supports the OpenAI API format, we do not need to create a custom LM Studio client. Instead, we can simply configure Spring AI’s OpenAI integration to use LM Studio’s local server URL.

2. Integrating Spring AI with LM Studio

2.1 Maven Dependencies

To get started, we need to configure the required dependencies in the project’s pom.xml file. The following Maven configuration includes Spring Web for creating the REST API and Spring AI’s OpenAI-compatible integration for communicating with the local LLM running in LM Studio.

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="
             http://maven.apache.org/POM/4.0.0
             https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>stable__jar__version</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.0</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>local-llm-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <name>local-llm-demo</name>
    <description>Spring AI integration with LM Studio</description>

    <properties>
        <java.version>21</java.version>
        <spring-ai.version>2.0.0</spring-ai.version>
    </properties>

    <dependencies>

        <!-- Spring MVC / REST -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring AI OpenAI-compatible client -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>

    </dependencies>

    <dependencyManagement>
        <dependencies>

            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>

            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>

        </plugins>
    </build>

</project>

The Maven configuration uses spring-boot-starter-parent as the project parent and Java 21 as the Java version. The spring-boot-starter-web dependency provides Spring MVC and the components required to expose REST endpoints, while spring-ai-starter-model-openai provides Spring AI’s OpenAI-compatible chat model integration, which can communicate with LM Studio because LM Studio exposes an OpenAI-compatible API. The spring-ai-bom is imported through dependencyManagement to keep Spring AI dependency versions consistent, and the spring-boot-maven-plugin allows the application to be packaged and run as a Spring Boot application.

2.2 Configure application.properties

Next, we need to configure the Spring Boot application so that Spring AI communicates with the local LLM through LM Studio instead of an external OpenAI server. Add the following properties to the src/main/resources/application.properties file, and make sure to replace the model name with the actual model ID loaded in your LM Studio instance.

spring.application.name=local-llm-demo

# LM Studio local server
spring.ai.openai.base-url=http://localhost:1234

# LM Studio does not require an API key by default.
# Spring AI expects a value, so we provide a placeholder.
spring.ai.openai.api-key=lm-studio

# Replace this with the model ID shown by LM Studio
spring.ai.openai.chat.options.model=qwen2.5-7b-instruct

spring.ai.openai.chat.options.temperature=0.7

server.port=8080

This configuration sets the application name to local-llm-demo and points Spring AI’s OpenAI client to the LM Studio server running at http://localhost:1234. The spring.ai.openai.api-key property uses lm-studio as a placeholder because LM Studio does not require an API key by default, while Spring AI expects this property to have a value. The spring.ai.openai.chat.options.model property specifies the local model that will process the prompts, so qwen2.5-7b-instruct should be replaced with the model ID available in your LM Studio setup. The temperature value of 0.7 controls the variability of generated responses, while server.port=8080 configures the Spring Boot application to run on port 8080.

2.3 Create the Spring Boot Application

Now, create the main Spring Boot application class that serves as the entry point for the project. The LocalLlmApplication class starts the Spring application, initializes the application context, and enables Spring Boot’s auto-configuration so that the required Spring Web and Spring AI components can be configured automatically.

// LocalLlmApplication.java
package com.example.localllm;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class LocalLlmApplication {

    public static void main(String[] args) {
        SpringApplication.run(LocalLlmApplication.class, args);
    }
}

The @SpringBootApplication annotation marks this class as the main configuration class and combines component scanning, auto-configuration, and Spring Boot configuration. The main() method calls SpringApplication.run() to start the application and initialize the Spring context. During startup, Spring Boot discovers components such as controllers and services and configures the Spring AI integration based on the settings defined in application.properties.

2.4 Create the Response Model

Next, create a simple response model that represents the data returned by our REST API. Instead of returning the LLM-generated answer as plain text, we will wrap it in a ChatResponse record so that Spring Boot automatically returns the response in a clean JSON format.

// ChatResponse.java
package com.example.localllm;

public record ChatResponse(String answer) {
}

The ChatResponse record contains a single answer field that stores the text generated by the local LLM. Java records provide a concise way to create immutable data carrier classes without manually writing constructors, getters, or other boilerplate code. When a ChatResponse object is returned from the REST controller, Spring Boot automatically serializes it into JSON, producing a response such as {"answer":"Spring Boot simplifies the development of Spring applications."}.

2.5 Create the LLM Service

Next, create a service class that handles the interaction between the Spring Boot application and the local LLM running in LM Studio. The LocalLlmService uses Spring AI’s ChatClient to build a prompt, send the user’s message to the configured model, and return the generated response.

// LocalLlmService.java
package com.example.localllm;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class LocalLlmService {

    private final ChatClient chatClient;

    public LocalLlmService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    public String ask(String message) {

        return chatClient
                .prompt()
                .system("""
                        You are a helpful Java programming assistant.
                        Explain concepts clearly and concisely.
                        Use simple examples when appropriate.
                        """)
                .user(message)
                .call()
                .content();
    }
}

The @Service annotation registers LocalLlmService as a Spring-managed component, while ChatClient.Builder is injected through the constructor and used to create a ChatClient. Inside the ask() method, prompt() starts building the request, system() provides instructions that define how the model should respond, and user(message) adds the actual question received from the user. The call() method sends the request through Spring AI to the OpenAI-compatible endpoint provided by LM Studio, where the local LLM generates the response, and content() extracts and returns the generated text.

2.6 Create the REST Controller

Finally, create a REST controller that exposes an HTTP endpoint for interacting with the local LLM. The ChatController receives the user’s message as a request parameter, passes it to LocalLlmService for processing, and returns the model-generated answer as a ChatResponse object.

// ChatController.java
package com.example.localllm;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class ChatController {

    private final LocalLlmService localLlmService;

    public ChatController(LocalLlmService localLlmService) {
        this.localLlmService = localLlmService;
    }

    @GetMapping("/chat")
    public ChatResponse chat(@RequestParam String message) {

        String answer = localLlmService.ask(message);

        return new ChatResponse(answer);
    }
}

The @RestController annotation marks ChatController as a REST API controller, while @RequestMapping("/api") defines the base path for its endpoints. The @GetMapping("/chat") annotation exposes the GET /api/chat endpoint, and @RequestParam String message reads the user’s prompt from the message query parameter. The controller passes this message to the LocalLlmService.ask() method, which sends it to the local LLM through Spring AI and LM Studio. The generated answer is then wrapped in a ChatResponse object and automatically serialized by Spring Boot into a JSON response.

2.7 Run and Test the Application

Before running the Spring Boot application, make sure LM Studio is running, the required LLM is loaded, and the local API server is started on http://localhost:1234. Once LM Studio is ready, start the Spring Boot application using the following Maven command.

mvn spring-boot:run

After the application starts successfully, it will be available on port 8080. We can now test the REST endpoint by sending a message through the message query parameter using the following command.

curl "http://localhost:8080/api/chat?message=Explain%20dependency%20injection%20in%20Java"

The request is received by ChatController and passed to LocalLlmService, which uses Spring AI to send the prompt to the local model running in LM Studio. The generated answer is then returned by the application as a JSON response. Since the response is generated by an LLM, the exact content may vary depending on the model and its configuration.

{
  "answer": "Dependency injection is a design pattern in which a class receives its dependencies from an external source instead of creating them itself. In Spring, dependencies are commonly provided through constructor injection."
}

This output confirms that the complete integration is working successfully: the client sends a request to the Spring Boot REST API, Spring AI communicates with LM Studio through its OpenAI-compatible API, the local LLM processes the prompt, and the generated response is returned to the client without requiring a cloud-based LLM API.

3. Conclusion

Integrating a local LLM with Spring Boot using Spring AI and LM Studio provides a simple way to build AI-powered Java applications without depending on a cloud-based LLM service. LM Studio makes it easy to download and run models locally while exposing an OpenAI-compatible API, and Spring AI provides the ChatClient abstraction needed to communicate with that API using familiar Spring programming patterns. With only a few dependencies, configuration properties, a service, and a REST controller, we can send prompts from a Spring Boot application to a locally running model and return the generated responses to clients. This approach is particularly useful for local development, experimentation, offline environments, and applications where greater control over model execution and data privacy is important.

Tags

[FREE EBOOKS] Microsoft 365 Excel Office Scripts For Dummies, Infinite & Four More Best Selling Titles

Java Code Geeks — Wed, 26 Aug 2026 10:30:30 +0000

Meta JCG

[FREE EBOOKS] Microsoft 365 Excel Office Scripts For Dummies, Infinite & Four More Best Selling Titles

Hello fellow geeks,

Fresh offers await you on our Information Technology Research Library, please have a look!

	Microsoft 365 Excel Office Scripts For Dummies ($34.99 Value) FREE for a Limited Time Unlock the full potential of automation in the online version of Excel online with this easy-to-follow guide. Microsoft 365 Excel Office Scripts For Dummies, by experienced Microsoft MVP Michael Alexander, explains how to use Office Scripts to unlock VBA-like capabilities in the online version of Excel. Alexander demonstrates exactly how to automate repetitive tasks, streamline workflows, and customize your spreadsheet experience with the same power previously available only to users of Excel’s desktop version. This comprehensive guide walks you through the practical application of Office Scripts using TypeScript. It walks you through basic automation scripts before moving on to advanced integration features you can access with Power Automate. The author’s hands-on approach helps you master the techniques you need to transform your Excel online experience from repetitive drudgery to automated efficiency, showing you how to maximize your productivity in a huge variety of settings. Learn how to: Master TypeScript fundamentals specifically tailored for Excel automation and scripting. Automate table formatting, data cleaning, and sorting processes to eliminate repetitive manual work. Create dynamic charts and enhance PivotTables with custom scripts for professional reporting. Integrate Power Automate features to build sophisticated workflows across Microsoft 365 applications. Apply range definitions and advanced scripting techniques for complex data manipulation tasks. Perfect for business professionals, data analysts, and advanced Excel users who work mostly with the online version of Excel and who want to automate their workflows, Microsoft 365 Excel Office Scripts For Dummies is a must-read for everyone interested in managing large datasets, creating regular reports, and streamlining routine tasks. Get it FREE!
	Infinite: How Visionary Leaders Transform Today’s Businesses into AI-Forward Companies ($34.00 Value) FREE for a Limited Time Transform your organization by making AI foundational — not just functional. Infinite: How Visionary Leaders Transform Today’s Businesses into AI-Forward Companies, written by two senior ServiceNow leaders, introduces the concept of the “Infinite Company”-a new class of organization built with artificial intelligence at its core. Rather than treating AI as an add-on, this book provides a strategic blueprint for seamlessly integrating human talent and AI to achieve greater innovation, productivity, and scale. Infinite guides readers through the evolution from traditional digital transformation to AI-driven innovation. It challenges conventional business models, exploring how AI-native companies are disrupting legacy organizations and offering strategies for leaders to rethink how they work, measure success, and structure their teams. The book presents a framework for building infinitely adaptable organizations led by AI-native leaders. Readers will also discover: How to shift from AI-enabled operations to building organizations with artificial intelligence embedded at the structural core. Strategies for developing an AI-native leadership mindset that moves beyond traditional digital transformation approaches. A framework for creating infinitely adaptable organizations that scale innovation, productivity, and competitive advantage simultaneously. Insights into how AI-first companies are disrupting legacy business models and rewriting the rules of competition. Practical guidance on rethinking success metrics, team structures, and workflows for an AI-driven operational environment. Infinite is written for business and technology leaders responsible for guiding their organizations through the shift to AI-driven operations. Whether leading enterprise transformation or building new AI-native ventures, this book delivers the strategic framework needed to compete against organizations already rewriting the rules of business. Get it FREE!
	Artificial Intelligence, Cybersecurity and Cyber Defense ($30.00 Value) FREE for a Limited Time Is the prospect of machines that can make their own decisions, formulate their own plans and “think” something that army commanders can dream of at the beginning of this 21st Century?. The aim of the book is to analyze and understand the impacts of artificial intelligence in the fields of national security and defense; to identify the political, geopolitical, strategic issues of AI; to analyze its place in conflicts and cyberconflicts, and more generally in the various forms of violence; to explain the appropriation of artificial intelligence by military organizations, but also law enforcement agencies and the police; to discuss the questions that the development of artificial intelligence and its use raise in armies, police, intelligence agencies, at the tactical, operational and strategic levels. Get it FREE!
	Marketing 7.0: A Guide for Thinking Marketers in the Age of AI ($30.00 Value) FREE for a Limited Time Level up your marketing strategy by understanding how the human mind works in the age of artificial intelligence (AI). Marketing 7.0 explores mind-centric marketing, a new approach that shifts the focus from AI-driven performance optimization to understanding how people think, connect, and buy. With the insights in this book, readers will be prepared to engage a new breed of consumers: the augmented human. Written by Philip Kotler, one of the world’s leading authorities on marketing, together with Hermawan Kartajaya and Iwan Setiawan from the leading marketing consulting firm MCorp, this book discusses ideas such as: Why digitalization, AI, and immersive technology unlock the consumer mind. How performance marketing and AI obsessions kill authenticity. How to extract customer insights to design brand storytelling, value propositions, selling approaches, and customer experiences. Marketing 7.0 earns a well-deserved spot on the bookshelves of executives, business leaders, and marketers alike as a guide to marketing in the age of AI. Offer Expires 8/25/2026. Get it FREE!
	7 Prompt Engineering Mistakes With ChatGPT and Fixes ($21 Value) FREE For a Limited Time Stop weak AI outputs. Learn the seven common prompt mistakes and the simple fixes for better ChatGPT prompts, faster workflows, and consistent results. Weak prompts waste hours. Vague asks, missing context, and no structure lead to poor answers. This guide shows the seven mistakes that derail ChatGPT prompts, with practical rewrites you can use today. You get clear examples, tight templates, and a repeatable process. You will see how to add context so the model understands your role and goal. You will learn to give precise instructions, not broad topics. You will stop treating ChatGPT like a search box and start requesting structured outputs. You will also break complex tasks into steps, iterate with feedback, and set tone and format. Each section includes before and after prompts you can copy. The result is faster work, better ideas, and higher quality deliverables. Keywords include ChatGPT prompts and prompt engineering. Download now and level up your AI productivity tools. In this book you will learn: – How to add role, goal, and audience for instant context. – How to write precise instructions with scope, length, and sources. – How to request structured outputs instead of open questions. – How to work step by step, then refine with iteration. – How to set format, tone, and examples to guide style. Get it FREE!
	25 GPT-5 ChatGPT Sales Prompts That Close Deals ($21 Value) FREE For a Limited Time Write sharper pitches and CTAs with 25 proven ChatGPT prompts. Turn features into benefits, handle objections, and improve close rates with clear, repeatable workflows. Sales pitches often get complex. Prospects lose the thread. This guide gives you 25 ChatGPT prompts that keep your message clear and persuasive. Use them to shape UVPs, improve proof points, and refine calls to action. You get fast, practical prompts grouped by use case. Product intros, CTAs, role play, objection handling, and slide improvements. Each prompt is specific, so you know what to ask and what to expect. Use simple prompt engineering to turn raw inputs into strong talking points. The result is a tighter pitch and faster decisions. In this book you will learn: – How to turn features into benefits prospects remember. – How to frame a UVP without taking shots at competitors. – How to write CTAs that reduce inertia and drive action. – How to practice with role play prompts for tough questions. – How to simplify slides and message flow for clarity. This resource is built for busy teams. Copy the prompts into ChatGPT, adapt the brackets, and ship a stronger pitch in minutes. Keywords include ChatGPT prompts, prompt engineering, and AI productivity tools. Get your copy now. Get it FREE!

That’s it for now, we hope you found them insightful. Stay tuned for more!

Till next time, keep geeking!

Tags

How to Deploy a Java Side Project on a Budget

Java Code Geeks — Wed, 26 Aug 2026 08:55:09 +0000

Java

How to Deploy a Java Side Project on a Budget

Image attributed to Pexels.com

Having a Java side project operate locally is important, but deploying it is another step. Live deployments let you test the project in real-world situations, including remote database connections, network traffic, server resource limits, and application restarts. It also simplifies sharing the project with new employers, partners, clients, and users. Creating a simple Java application doesn’t require a costly hosting configuration.

Instead of buying capacity that you will never use, choose infrastructure that fits the project’s existing scale. A small database and limited resources are enough for a modest virtual server or personal application. Consider the public face early on. SSL, memorable domain, etc. Before you get Hostinger domains cheaper, developers can compare registration, renewal, and hosting fees to save money. These minor improvements can cover launch costs.

Choosing a Java Project to Deploy

Spring Boot, REST APIs, tiny backend services, portfolio projects, and problem-solving tools are excellent choices for launching Java projects. First deployment is simplest for small projects with minimal dependencies. A PostgreSQL REST API may be easier to run than an app with several external services, message queues, and background workers. Spring Boot is ideal for side projects since you can bundle an app as an executable JAR and launch it with server-loaded Java. Consider the application’s RAM, persistent storage, and usage frequency before deploying.

Preparing the Application for Production

Configure production and development separately. Environment variables or other secure setups should hold database passwords, API credentials, signing keys, and other sensitive data, not the source repository. Logging, error handling, and production database settings should be sufficient in the software. If the project is exposed to the internet, check authentication, authorization, input validation, and dependency versions before deployment. Spring Boot profiles provide different development and production setups. Database migrations should apply schema changes consistently with new versions.

Choosing Where to Host It

Java hosting options include shared, virtual private, and cloud services. Although shared hosting is cheap, it can restrict Java support and give developers little control over the runtime. VPSs are more flexible because you can add Java, a database, a reverse proxy, and monitoring tools. Cloud solutions simplify deployment with managed databases, containers, and automated scaling, but adding services may affect prices. A plan with enough RAM and CPU to keep the monthly bill predictable is ideal for a small side project.

Deploying a Java Application to a VPS

A basic VPS deployment includes server creation, security upgrades, and a Java runtime. Copy the packed JAR to the server and run it in production. Avoid terminal sessions and run your software as a service so it restarts if the server reboots or the application crashes. Nginx or another reverse proxy may manage HTTPS traffic and forward requests to your Java application port. Firewalls should expose only necessary services. If the application stores user data or other non-duplicable data, back it up regularly.

Keeping Hosting Costs Under Control

Purchase hosting resources based on predicted traffic to save money. Start with the smallest server. After deployment, monitor CPU/memory/storage/database usage in real time and update only when the application hits its limits. Beyond promotional discounts, compare monthly VPS, managed databases, backups, and domain rates. Consider pricing before buying because renewals cost more than new registrations. Promotions and domain-hosting bundles cut registration costs. Monitoring and upgrading slowly is cheaper than scaling too early, especially for a side project.

Access Request and Response Body in HandlerInterceptor

Yatin Batra — Wed, 26 Aug 2026 06:47:06 +0000

Enterprise Java

Access Request and Response Body in HandlerInterceptor

In a Spring Boot application, we sometimes need to inspect or log the HTTP request body and response body. This can be useful for debugging, auditing, troubleshooting, or request-response logging. Spring provides the HandlerInterceptor interface, which allows us to execute custom logic before and after a controller method is called. However, directly reading the request body or response body inside an interceptor is not straightforward because HTTP streams are normally consumed during request processing. A simple solution is to use ContentCachingRequestWrapper and ContentCachingResponseWrapper inside a servlet filter. The interceptor can then access the cached request and response content.

1. Accessing Request and Response Bodies in HandlerInterceptor

Suppose we have the following Spring Boot API: HTTP POST /api/users. The client sends user details to the API as JSON in the HTTP request body.

{"name":"John","email":"john@example.com"}

After processing the request, the API returns the result to the client in the HTTP response body.

{"message":"User created successfully"}

We want to log both values from a Spring MVC interceptor:

Request Body: {"name":"John","email":"john@example.com"}

Response Body: {"message":"User created successfully"}

In Spring MVC, a request body is typically read by an HttpMessageConverter when Spring converts JSON into a Java object for an @RequestBody parameter. Since the servlet request input stream is normally read only once, trying to call request.getReader() or request.getInputStream() later inside a HandlerInterceptor may return no content. The response body has a similar limitation. Once the response is written to the servlet output stream, an interceptor does not automatically have a reusable copy of that data. To solve this, Spring provides ContentCachingRequestWrapper and ContentCachingResponseWrapper. These wrappers cache the content while the request is being read and the response is being written.

The wrappers should be applied before the request reaches the Spring MVC interceptor, usually inside a servlet filter. The request then follows this flow: Client → Filter (Wrap request and response) → HandlerInterceptor → Controller → HandlerInterceptor (Read cached content) → Filter (Copy response back to client) → Client. An important point is that ContentCachingRequestWrapper does not read the request body by itself. It only caches the bytes when Spring or another component actually reads them. Therefore, the request body may still be empty in preHandle(), while it is normally available later in the request lifecycle. Using these wrappers allows the controller to process the request normally while giving the interceptor access to a cached copy of both the request and response bodies.

1.1 How HandlerInterceptor Works

A Spring HandlerInterceptor allows us to intercept requests during Spring MVC request processing. The main interceptor methods are:

preHandle() – Executes before the controller method. It is commonly used for authentication, validation, or request checks. Returning true continues the request, while false stops it.
postHandle() – Executes after the controller method completes but before the response is fully processed. It can be used to perform additional processing on the response.
afterCompletion() – Executes after the complete request-response cycle finishes. It is useful for logging, cleanup, and accessing cached request and response data.

1.2 Understanding ContentCachingRequestWrapper and ContentCachingResponseWrapper

Spring provides ContentCachingRequestWrapper and ContentCachingResponseWrapper to cache the content of an HTTP request and response. They wrap the original HttpServletRequest and HttpServletResponse without changing how the controller normally processes them.

ContentCachingRequestWrapper caches the request body as it is read by Spring. The cached content can later be retrieved using getContentAsByteArray(). It is important to note that creating the wrapper does not immediately read the request body; the content is cached only when the body is actually consumed.
ContentCachingResponseWrapper caches the data written to the HTTP response. This allows the response body to be retrieved using getContentAsByteArray() before it is finally sent to the client.

1.3 Key Points to Consider

This solution is useful for debugging and request-response logging, but there are a few practical points to keep in mind.

Avoid logging sensitive information such as passwords, tokens, authorization headers, or payment details.
Request and response bodies are stored in memory, so avoid logging very large uploads or downloads.
The request cache may be empty inside preHandle() because the controller has not read the request body yet.
Always call copyBodyToResponse() when using ContentCachingResponseWrapper.

2. Implementing Request and Response Body Logging

The example contains a simple REST endpoint that accepts a user and returns a success message.

2.1 Define the Request DTO

package com.example.demo.dto;

public class UserRequest {

  private String name;
  private String email;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }
}

The UserRequest class is a simple DTO (Data Transfer Object) used to represent the JSON data received in the request body. It contains the name and email fields along with their getter and setter methods. When this class is used with @RequestBody, Spring automatically converts the incoming JSON request into a UserRequest object.

2.2 Create the REST Controller

package com.example.demo.controller;

import com.example.demo.dto.UserRequest;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation. * ;

import java.util.Map;

@RestController@RequestMapping("/api/users")
public class UserController {

  @PostMapping
  public ResponseEntity < Map < String, String >> createUser(@RequestBody UserRequest request) {
    return ResponseEntity.ok(Map.of("message", "User created successfully"));
  }
}

The UserController class defines a REST API for handling user requests. The @RestController annotation marks the class as a REST controller, while @RequestMapping("/api/users") sets the base URL. The @PostMapping method handles HTTP POST requests, and @RequestBody converts the incoming JSON body into a UserRequest object. Finally, ResponseEntity.ok() returns an HTTP 200 response containing the "User created successfully" message.

2.3 Add the Content Caching Filter

package com.example.demo.filter;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.util.ContentCachingRequestWrapper;
import org.springframework.web.util.ContentCachingResponseWrapper;

import java.io.IOException;

@Component
public class ContentCachingFilter extends OncePerRequestFilter {

  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
    ContentCachingRequestWrapper requestWrapper = new ContentCachingRequestWrapper(request);
    ContentCachingResponseWrapper responseWrapper = new ContentCachingResponseWrapper(response);

    try {
      filterChain.doFilter(requestWrapper, responseWrapper);
    } finally {
      responseWrapper.copyBodyToResponse();
    }
  }
}

The ContentCachingFilter extends OncePerRequestFilter, ensuring that the filter runs once for each request. Inside doFilterInternal(), the original request and response are wrapped using ContentCachingRequestWrapper and ContentCachingResponseWrapper so their content can be cached and accessed later. The wrapped objects are passed through the filter chain using filterChain.doFilter(). Finally, copyBodyToResponse() copies the cached response body back to the actual response so it can be returned to the client.

2.4 Create the Request-Response Logging Interceptor

package com.example.demo.interceptor;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.util.ContentCachingRequestWrapper;
import org.springframework.web.util.ContentCachingResponseWrapper;

import java.nio.charset.StandardCharsets;

@Component
public class RequestResponseLoggingInterceptor implements HandlerInterceptor {

  @Override
  public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {

    if (request instanceof ContentCachingRequestWrapper requestWrapper) {
      byte[] requestContent = requestWrapper.getContentAsByteArray();
      String requestBody = new String(requestContent, StandardCharsets.UTF_8);
      System.out.println("Request Body: " + requestBody);
    }

    if (response instanceof ContentCachingResponseWrapper responseWrapper) {
      byte[] responseContent = responseWrapper.getContentAsByteArray();
      String responseBody = new String(responseContent, StandardCharsets.UTF_8);
      System.out.println("Response Body: " + responseBody);
    }
  }
}

The RequestResponseLoggingInterceptor implements HandlerInterceptor and uses the afterCompletion() method to access the request and response after processing is complete. It first checks whether they are instances of ContentCachingRequestWrapper and ContentCachingResponseWrapper. The cached content is retrieved using getContentAsByteArray(), converted from a byte array to a UTF-8 String, and then printed to the console as the request body and response body.

2.5 Register the Interceptor

package com.example.demo.config;

import com.example.demo.interceptor.RequestResponseLoggingInterceptor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

  private final RequestResponseLoggingInterceptor interceptor;

  public WebConfig(RequestResponseLoggingInterceptor interceptor) {
    this.interceptor = interceptor;
  }

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(interceptor).addPathPatterns("/api/**");
  }
}

The WebConfig class implements WebMvcConfigurer to customize Spring MVC configuration. The RequestResponseLoggingInterceptor is injected through the constructor and registered inside the addInterceptors() method. The addPathPatterns("/api/**") configuration ensures that the interceptor is applied only to requests whose URLs start with /api/.

2.6 Run the Application and Verify the Output

Run the Spring Boot application and send an HTTP POST request to /api/users with the following JSON request body:

{"name":"John","email":"john@example.com"}

After the request is processed, the API returns the following response:

{"message":"User created successfully"}

The interceptor reads the cached request and response bodies and prints the following output in the application console:

Request Body: {"name":"John","email":"john@example.com"}
Response Body: {"message":"User created successfully"}

3. Conclusion

In this article, we learned how to access the request and response bodies in a Spring HandlerInterceptor. Since the request and response streams cannot be safely read multiple times, we used ContentCachingRequestWrapper and ContentCachingResponseWrapper inside a filter to cache their content. The interceptor can then retrieve the cached data using getContentAsByteArray() after request processing is complete. This approach provides a simple and effective way to log or inspect request and response bodies in Spring Boot applications.

Tags

Project Valhalla in Practice: Writing Your First Value Class

Eleftheria Drosopoulou — Wed, 26 Aug 2026 05:27:00 +0000

Core Java

Project Valhalla in Practice: Writing Your First Value Class

JEP 401 is real, it’s in an early-access build today, and you can run it right now. It just isn’t landing where most people think it is.

A decade of conference talks, name changes, and rewritten prototypes has led to this: JEP 401, Value Classes and Objects, has real syntax, a real JVM implementation, and a real early-access build you can download today. Before writing a single line, it’s worth getting one detail straight, because it’s been misreported enough that it’s worth correcting directly.

Correcting the record: JEP 401 is not targeted at JDK 26. As of this month, it has been integrated into the OpenJDK mainline targeting JDK 28, due in March 2027, as a preview feature. Early-access builds tied to it have existed for a while, some built on JDK 26 and JDK 27 codebases along the way, but the destination release has now been locked in as JDK 28. The early-access build available right now lives at jdk.java.net/28, and that’s what this walkthrough uses.

Getting the Early-Access Build Running

Download the JDK 28 early-access build, unzip it, and point your terminal at its bin directory. Every command from here on needs the preview flag, since value classes are a preview feature, disabled by default even in this build.

export JAVA_HOME="$PWD/jdk-28/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

java --version
# openjdk 28-ea ...

jshell --enable-preview

Everything that follows, both the javac compile step and the java run step, needs --enable-preview on the command line. Forget it on either side and the JVM refuses to run the class file.

Declaring Your First Value Class

The simplest way in is a value record, since records already give you final fields and a generated constructor for free. Add the value modifier and the class loses its identity:

jshell> value record Point(int x, int y) {}
created record Point

jshell> Point p = new Point(17, 3)
p ==> Point[x=17, y=3]

jshell> Objects.hasIdentity(p)
$1 ==> false

jshell> new Point(17, 3) == p
$2 ==> true

That last line is the one worth sitting with. For an ordinary class, == compares references, two separately constructed objects are never ==, no matter what fields they hold. For a value object, == has nothing to compare but state, so two Point instances built from the same coordinates are simply equal. Objects.hasIdentity(), added alongside this JEP, is the straightforward way to check which kind of object you’re holding, and it turns out a handful of existing JDK classes, including Integer and LocalDate, already flip over to value classes the moment preview mode is on.

Ordinary classes can declare themselves as value classes too, not just records, as long as every field is final:

value class Money {
    private final long cents;
    private final String currency;

    Money(long cents, String currency) {
        this.cents = cents;
        this.currency = currency;
    }

    long cents() { return cents; }
    String currency() { return currency; }
}

What You Lose: Identity and Synchronization

Giving up identity is not a cosmetic change, it removes real capabilities the object used to have, and the JVM enforces the loss rather than just discouraging it.

Capability	Identity class	Value class
Meaningful reference equality (`==`)	Yes, compares memory identity	No, compares field state instead
`synchronized` blocks or methods	Allowed	Disallowed; the JVM rejects locking on a value object
`System.identityHashCode()`	Meaningful, stable per object	Not meaningful, there’s no identity to hash
`WeakReference` / `SoftReference`	Supported	Throws an exception; there’s no single canonical instance to hold weakly
Mutable fields	Allowed	Disallowed; every field must be final

The synchronization loss deserves a second look, since it’s the one most likely to surprise a team migrating an existing class. If any code path anywhere locks on an instance of a type you’re converting to a value class, that code stops compiling, or stops working, the moment the conversion lands. It’s a genuinely useful early-warning signal, in most cases a class holding pure immutable data was never a sensible thing to synchronize on anyway, but it means the migration is not always as simple as adding one keyword.

What You Gain: Flat Memory Layout and JIT Inlining

The payoff for giving up identity is that the JVM no longer has to guarantee a value object lives at one canonical heap address. Without that guarantee, the runtime is free to embed the object’s fields directly into whatever’s holding it, a containing object’s fields, or consecutive slots in an array, instead of storing a pointer to a separately allocated block of memory. This is the mechanism the Valhalla team calls heap flattening, and it’s the reason value classes exist at all, not the syntax, the flattening.

Illustrative memory cost per element for an array of 1,000,000 two-int Point objects, based on documented JVM object layout rules (8-byte compact header, 8-byte array reference, 8 bytes of int fields). Actual savings depend on JIT decisions and array size.

An array of a million ordinary Point objects stores a million 8-byte references, each pointing to a separately allocated object carrying its own header plus its two int fields. An array of a million flattened value Points can, when the JIT chooses to flatten it, store the sixteen bytes of actual field data back-to-back with nothing else, no header per element, no pointer indirection, no separate allocation to chase during a cache miss. That’s the concrete shape of the win Valhalla has been chasing since 2014: primitive-like storage density for something that still looks and behaves like a class.

Benchmarking the Difference

Oracle’s own walkthrough for this early-access build includes a small, repeatable demo worth reproducing rather than taking on faith. It runs a date-heavy computation across several iterations, once using ordinary identity objects and once using value objects for the same data, and reports the timing for each pass. In that walkthrough’s own results, later iterations using value objects settled into roughly the mid-20-millisecond range, down from around 40 milliseconds on the first pass, as the JIT warmed up and began applying flattening-related optimizations that simply aren’t available to identity objects.

How to run your own version of this benchmark

Treat any single machine’s numbers as directional. Oracle’s own walkthrough is explicit that results vary by hardware and array size, this is preview software, and JIT heuristics around flattening are still being tuned.

Write the same computation twice, once against a plain class, once against its value class equivalent, changing nothing but that one modifier.

Run each version for enough iterations to let the JIT warm up, a handful of passes at minimum, and discard the first few results before measuring.

Prefer a proper microbenchmarking harness like JMH over hand-rolled System.nanoTime() loops if you’re publishing the numbers anywhere.

From Project Valhalla’s start to a preview build you can download today.

What We Learned

JEP 401 gives Java a real, runnable way to declare a class that trades away object identity for a flatter, cheaper memory representation, and after a decade of design churn, that trade is finally something you can compile and run against an early-access build rather than read about in a talk. Declaring one takes a single value modifier on a class or record with only final fields, but the cost is concrete, not cosmetic: no synchronizing on the instance, no meaningful reference equality, no weak references, enforced by the JVM rather than left to convention.

The reward is equally concrete, once the JVM can stop guaranteeing a canonical address for an object, it can flatten that object’s fields directly into arrays and containing objects, cutting out header and pointer overhead entirely for data-heavy workloads. The one thing worth being precise about, given how much of the coverage has gotten it wrong, is where this actually lands: JEP 401 is a preview feature targeting JDK 28 in March 2027, not JDK 26, even though the early-access build to try it on is sitting there right now.

Tags

Structured Concurrency: What Changes for the Try/Catch Generation

Eleftheria Drosopoulou — Tue, 25 Aug 2026 16:52:00 +0000

Core Java

Structured Concurrency: What Changes for the Try/Catch Generation

A real CompletableFuture chain, rewritten into StructuredTaskScope, plus the JDBC cancellation gap nobody’s fixed yet.

Java developers who learned concurrency on CompletableFuture chains and manual thread pools are about to get a genuinely different tool. Structured Concurrency changes how failure, cancellation, and thread lifetimes work, not just the syntax. But before getting to the migration, it’s worth correcting a detail that’s spreading faster than the feature itself: Structured Concurrency is not finalized. Not yet.

Where Things Actually Stand

As of JDK 27, due in September 2026, Structured Concurrency is in its seventh preview, delivered as JEP 533. It has previewed, in some form, in every release since JDK 19 in 2022, and JEP 533’s own text does not commit to a finalization timeline. The API is converging, the changes each round are smaller than the last, but “converging” and “final” are different words for a reason. If you’re planning production code around this feature today, it still needs --enable-preview at compile time and runtime, and the API surface can still shift under you between JDK versions.

What is finalized, and worth using without hesitation, is Scoped Values, delivered as JEP 506 in JDK 25. Scoped Values are the replacement for ThreadLocal in virtual-thread code, and they integrate directly with structured concurrency scopes, subtasks automatically inherit the scoped value bindings of the parent. If you’re adopting one of these two features now, Scoped Values is the one you can ship without a preview flag.

The Old Way: A CompletableFuture Chain

Here’s a common pattern: fetch a user record and that user’s orders concurrently, combine them into a response, and give up if either call takes too long.

CompletableFuture<User> userFuture = CompletableFuture
    .supplyAsync(() -> findUser(userId), executor)
    .orTimeout(2, TimeUnit.SECONDS);

CompletableFuture<List<Order>> ordersFuture = CompletableFuture
    .supplyAsync(() -> fetchOrders(userId), executor)
    .orTimeout(2, TimeUnit.SECONDS);

CompletableFuture<Response> combined = userFuture
    .thenCombine(ordersFuture, Response::new)
    .exceptionally(ex -> {
        userFuture.cancel(true);
        ordersFuture.cancel(true);
        throw new CompletionException(ex);
    });

Response response = combined.join();

This works, but every line is doing manual bookkeeping the language should be handling. The .exceptionally() block has to manually cancel the sibling future because thenCombine won’t do it for you, and even that cancellation is mostly cosmetic: CompletableFuture.cancel(true) marks the future as cancelled, it does not reliably interrupt the thread actually running findUser() unless you’ve wired that up yourself. A thread dump under load shows a flat pool of generically named threads with no indication which request they belong to. None of this is a bug in CompletableFuture, it’s simply an API built on unstructured concurrency, where tasks have no enforced relationship to each other.

The New Way: StructuredTaskScope

The same logic, expressed with the current preview API from JEP 505 and JEP 525:

Response handle(String userId) throws InterruptedException, ExecutionException {
    try (var scope = StructuredTaskScope.open(
            StructuredTaskScope.Joiner.awaitAllSuccessfulOrThrow(),
            cfg -> cfg.withTimeout(Duration.ofSeconds(2)))) {

        StructuredTaskScope.Subtask<User> user =
            scope.fork(() -> findUser(userId));
        StructuredTaskScope.Subtask<List<Order>> orders =
            scope.fork(() -> fetchOrders(userId));

        scope.join();

        return new Response(user.get(), orders.get());
    }
}

The cancellation logic that took a manual .exceptionally() block before is now the scope’s job. If either subtask fails, or the two-second timeout fires, join() throws, the try-with-resources block closes the scope, and the scope interrupts whichever subtask is still running before returning control to the caller. Nobody wrote that coordination by hand, it’s a property of the scope itself.

CompletableFuture concept	StructuredTaskScope equivalent
`supplyAsync(fn, executor)`	`scope.fork(() -> ...)`, runs on a virtual thread by default
`.orTimeout(...)` per future	One timeout on the whole scope, via the configuration lambda
Manual `.cancel(true)` on siblings	Automatic, scope cancels remaining subtasks on any failure
`.thenCombine()` / `.join()`	`scope.join()`, then read each `Subtask.get()`
Flat, unlabeled thread pool in a dump	Threads grouped under their owning scope in the thread dump

Where It Still Falls Short: The JDBC Problem

The gap that matters most in practice: Structured Concurrency’s entire cancellation model depends on subtasks actually responding to interruption. The JEP’s own specification says it plainly, subtasks that block on methods that are not interruptible may delay the closing of a scope indefinitely, and the close() method will wait for them to finish no matter what. That’s exactly what happens with most JDBC drivers today.

A large share of production Java services fork a subtask to run a JDBC query. JDBC calls are blocking by design, and the underlying socket reads inside many drivers do not honor Thread.interrupt() the way NIO channels do. When a sibling subtask fails and the scope tries to cancel that still-running database call, the interrupt gets delivered, but the thread sitting inside a blocking socket read simply doesn’t notice. The scope’s close() call then blocks too, waiting for a subtask that has no intention of stopping until the underlying query finishes or the connection times out on its own. The clean, structured cancellation the whole feature is built around quietly stops working at exactly the boundary where most Java applications spend most of their I/O time.

This isn’t a defect in Structured Concurrency, and it isn’t really a defect in JDBC either, it’s a mismatch between a cooperative interruption model and drivers written decades before that model existed. It also compounds with a related, separate issue: some JDBC drivers still use synchronized blocks internally that pin virtual threads to their carrier during blocking calls, which is a scheduling problem rather than a cancellation one, but shows up in the same code paths and makes diagnosing the root cause harder.

Every JDK release Structured Concurrency has touched, and which preview round it shipped as. No release has finalized it yet.

What to actually do about it today

Adopt Scoped Values now, they’re finalized in JDK 25 and safe to use without a preview flag.
Gate any Structured Concurrency code behind --enable-preview, and expect the API to keep shifting slightly until it actually finalizes.
Audit which of your subtasks make blocking JDBC calls, and test what actually happens to scope shutdown time when one of those calls hangs.
Where possible, set aggressive query timeouts at the JDBC driver or connection-pool level, don’t rely on scope cancellation alone to bound a slow query.
Watch driver changelogs, several major JDBC drivers are actively working through virtual-thread and interruption compatibility issues; this gap is closing, not permanent.

What We Learned

Structured Concurrency replaces the manual bookkeeping of CompletableFuture chains, cancelling siblings by hand, chasing down which thread belongs to which request, with a scope that owns that coordination itself: fork subtasks, call join(), and let a single timeout or failure cancel everything else automatically. But the feature is still in its seventh preview as of JDK 27, with no committed finalization date, so treat “production-ready” claims about it with the same caution the JEP authors themselves are showing. And its cancellation model has a real, specification-acknowledged limit: it only works if the code being cancelled actually responds to interruption, which a great deal of JDBC traffic still doesn’t.

Scoped Values, by contrast, are finalized today and worth adopting regardless of how the rest of this story plays out. The try/catch generation isn’t being asked to abandon everything it knows, just to recognize that the biggest win here is structural correctness, not a syntax upgrade, and that the win still has a real edge where blocking I/O meets a cooperative cancellation model that assumes everyone plays along.

Tags

Compact Object Headers in Production: The Free 15–25% Heap Reduction Nobody Enabled

Eleftheria Drosopoulou — Tue, 25 Aug 2026 05:44:00 +0000

Core Java

Compact Object Headers in Production: The Free 15–25% Heap Reduction Nobody Enabled

JEP 519 shipped stable in JDK 25. It shrinks every single object header on the heap. It’s one JVM flag. Most teams still haven’t flipped it.

Here’s a JVM optimization that costs nothing to try, requires no code changes, and has already been validated across hundreds of production services at Amazon. It shipped as a stable, production-ready feature in JDK 25. And if your team is like most, it’s sitting there unused. This is the story of Compact Object Headers, what they actually do, what the real numbers look like, and why “it’s automatic now” is the myth that’s keeping teams from claiming savings they’re already entitled to.

What’s Actually Sitting in Every Object Header

Every object on the Java heap carries a header before any of its actual data. That header isn’t optional, and until recently, it wasn’t small. On a typical 64-bit JVM with compressed object pointers enabled, a plain object header consumes 96 bits, 12 bytes, made up of a mark word (used for locking, garbage collection state, and identity hash codes) and a compressed class pointer. On larger heaps, above roughly 32 GB, where compressed pointers stop working, that header grows to 128 bits, 16 bytes.

For an application with a handful of large objects, that overhead barely registers. But most real Java applications aren’t shaped like that. Spring Boot services, data pipelines, caching layers, anything built around small domain objects, DTOs, wrapper types, list nodes, tends to allocate enormous numbers of small objects. When each one is paying a fixed 12-to-16-byte tax just to exist, that tax adds up fast. It’s routine for header overhead alone to account for 15 to 25 percent of total heap usage in object-heavy workloads.

The Fix: One 64-Bit Word Instead of Two

JEP 519, Compact Object Headers, takes the mark word and the class pointer, previously two separate fields, and merges them into a single compact 64-bit word. The class pointer itself gets compressed further, down to 22 bits, still enough headroom for roughly four million distinct classes, far beyond what any real application will ever load. The net result is straightforward: every object header on the heap shrinks from 96 or 128 bits down to a flat 64 bits, and every object gets smaller without a single line of application code changing.

This didn’t appear out of nowhere in JDK 25. It’s the first shipped result of Project Lilliput, the OpenJDK effort dedicated specifically to shrinking object memory overhead, and it spent a full release cycle as an experimental feature under JEP 450 in JDK 24 before graduating to a stable product feature. Enabling it takes one flag:

-XX:+UseCompactObjectHeaders

That’s the entire integration cost. No dependency changes, no application code touched, no build configuration beyond a JVM flag you can add to a deployment manifest today.

The Myth: “It’s On by Default in Java 25”

The misconception: Because JEP 519 promoted compact object headers to a stable, production-ready feature, plenty of teams assume upgrading to JDK 25 gets them the savings automatically. It doesn’t. Compact object headers remain opt-in in JDK 25. A separate proposal, JEP 534, exists specifically to flip the default and currently targets JDK 27, and its own text is explicit that the JDK 25 team deliberately held off, in their words, changes this size are best introduced carefully and gradually. If you’ve upgraded to JDK 25 and never added the flag, you’re running with the old 96-to-128-bit headers exactly as before.

That gap, between “production-ready” and “on by default,” is precisely why this savings is still sitting unclaimed on so many clusters. Teams read “stable in JDK 25” and reasonably assume stable means enabled. It means tested, not turned on.

Object header size before and after JEP 519, per the OpenJDK specification.

The Real Numbers, Not Marketing Numbers

The headline figures come straight from OpenJDK’s own JEP 519 text, not a vendor benchmark. Running the SPECjbb2015 benchmark with compact object headers enabled showed 22 percent less heap space used, 8 percent less CPU time, and 15 percent fewer garbage collections with both the G1 and Parallel collectors, all with no application changes involved. A separate, highly parallel JSON parsing benchmark ran 10 percent faster. Those figures are exactly where the “15 to 25 percent” range in the title comes from, not a rounded-up marketing number.

The validation behind those numbers is unusually thorough for a JVM-level change. Amazon ran compact object headers across hundreds of production services before JDK 25 ever shipped, largely using backports of the feature to JDK 17 and JDK 21. SAP went further still, enabling compact object headers by default in SapMachine, its own OpenJDK distribution, ahead of the upstream default flip. That’s not a lab result, it’s production traffic at two of the largest JVM operators on the planet.

From experimental flag to stable feature to a proposed default, across three release cycles.

Where the FinOps Case Writes Itself

For any team already tracking JVM memory against container limits, this is about as close to a free lunch as infrastructure optimization gets. Smaller headers mean lower heap usage at the same workload, which means either a smaller memory request per pod, or more headroom before you hit a limit and get OOM-killed. Lower heap usage also means less garbage collection work per cycle, since the collector is scanning fewer bytes of live header data on every pass. If your team has already gone through the exercise of right-sizing JVM container memory requests, compact object headers is the next lever, and it’s a lever you pull with one flag instead of a re-architecture.

Rollout checklist before you flip the flag

Confirm you’re on JDK 25 or later, or a distribution that has backported JEP 519.
Check your heap size. Compact headers rely on compressed class pointers, which stop working above roughly 32 GB per heap.
Audit any native code or JNI integrations that assume a fixed object header layout, these are the most likely source of surprises.
Re-check debugging and profiling tooling. Anything that parses raw object headers needs to be header-layout aware.
Roll out to a non-critical service first and compare heap and GC metrics before and after, the same way you’d validate any other JVM flag change.

What We Learned

Compact Object Headers, delivered through JEP 519, shrink every Java object’s header from 96 or 128 bits down to a single 64-bit word by merging the mark word and a compressed class pointer, with OpenJDK’s own SPECjbb2015 numbers showing 22 percent less heap and 8 percent less CPU time as a direct result. It shipped as a stable, production-ready feature in JDK 25, validated against hundreds of real production services at Amazon before it ever reached that milestone. The catch is entirely about defaults, not readiness, the feature is opt-in behind a single flag, and a separate JEP proposing to make it the default hasn’t landed yet. For any object-heavy Java workload running in containers with a memory limit attached to a cost line, that single flag is one of the highest-leverage, lowest-risk changes available today, and most teams simply haven’t flipped it yet.

Tags

The Actor Model’s Long Lineage: From Hewitt’s 1973 Paper to Kotlin Coroutines

Eleftheria Drosopoulou — Mon, 24 Aug 2026 16:36:00 +0000

Software Development

The Actor Model’s Long Lineage: From Hewitt’s 1973 Paper to Kotlin Coroutines

Every “actor” you’ve used, Erlang’s, Akka’s, Kotlin’s, descends from a single 1973 formalism. What survived the trip from language primitive to library is not the same in each case.

It’s common to hear the actor model described as “Erlang’s concurrency thing,” with Akka and its imitators treated as ports of an Erlang idea to other platforms. That framing skips a generation. The actor model didn’t originate with Erlang at all. It comes from a 1973 artificial intelligence paper by Carl Hewitt, Peter Bishop, and Richard Steiger, written more than a decade before Erlang existed, and Erlang itself arrived at similar ideas independently rather than by implementing Hewitt’s paper directly. Tracing the lineage properly, from a formal model, to a language built around it, to a library bolted onto languages that were never designed for it, shows exactly which guarantees survive each step and which ones quietly become the programmer’s responsibility instead of the runtime’s.

The 1973 Formalism

Hewitt, Bishop, and Steiger’s “A Universal Modular ACTOR Formalism for Artificial Intelligence” was not a systems paper about concurrency for its own sake. It was a position paper for the 1973 International Joint Conference on Artificial Intelligence, proposing actors as a single universal primitive underneath everything, control structures, data structures, even AI reasoning itself. The paper explicitly credits Alan Kay’s Smalltalk and Flex work as an influence, and the actor it describes is defined by exactly three capabilities: it can create new actors, it can send messages to actors it knows about, and it can designate how it will behave the next time it receives a message. Nothing else is a primitive. Everything else in a computation, in Hewitt’s formulation, is built out of those three moves.

Two consequences follow directly from that definition, and both turn out to matter enormously once the model becomes real software decades later. First, actors never share mutable state; the only way to affect another actor is to send it a message, never to reach into its memory. Second, message delivery is asynchronous, an actor sends a message and continues, it does not block waiting for the message to be received or processed.

Erlang: The Model Becomes a Language

Joe Armstrong, Robert Virding, and Mike Williams built Erlang at Ericsson starting in 1986, aiming to solve a very concrete problem, telecom switching software that could not be allowed to go down. They arrived at a design built entirely around lightweight, isolated processes communicating only by message passing, and multiple retrospective accounts note that this converges conceptually with Hewitt’s 1973 actor formalism despite having been developed independently for a different purpose. In Erlang, the actor is not a design pattern you opt into, it is the only unit of concurrency the language gives you. There is no shared-memory alternative sitting next to it.

Because the actor is a language-level primitive, the Erlang runtime, the BEAM virtual machine, can enforce guarantees that a library bolted onto another language simply cannot. Every Erlang process gets its own private heap and its own garbage collector, so a collection pause in one process never stops any other process in the system. A newly spawned process starts at roughly 327 words of memory, according to Erlang’s own official documentation, cheap enough that spawning a million of them is an ordinary benchmark rather than a stunt. On top of process isolation, Erlang’s OTP framework layers supervision trees and a “let it crash” philosophy: a process is allowed to fail outright, and a dedicated supervisor process, not the crashing process itself, decides how to recover, restart, or escalate the failure.

Approximate memory overhead per unit of concurrency, log scale. Erlang and Akka figures are from their own official documentation; the JVM native thread figure is HotSpot’s default 64-bit stack size.

Akka: The Model Becomes a Library

Jonas Bonér started Akka in 2009 explicitly because he wanted Erlang’s approach to concurrency and fault tolerance available on the JVM, where Java and Scala developers were still managing shared-memory threads and locks by hand. Akka’s actors keep the parts of the model that a library running inside an existing language runtime can still enforce by convention: each actor has a private mailbox, processes one message at a time, and Akka layers supervisor hierarchies on top, deliberately modeled on Erlang’s, to handle failure by restarting or stopping child actors rather than letting an exception propagate uncontrolled.

What Akka cannot do is change the ground it’s standing on. The JVM itself has no concept of an isolated, per-actor heap, every Akka actor’s state lives on the same shared heap as everything else in the process, garbage collected together. Nothing in the JVM stops one actor’s code from directly touching another actor’s fields; the isolation Erlang’s runtime enforces mechanically, Akka can only ask you to respect by not writing code that reaches across actor boundaries. It is convention backed by documentation and API design, not a guarantee the underlying platform makes impossible to violate. Akka’s own materials cite roughly 2.5 million actors per gigabyte of heap, remarkably lightweight for a JVM library, but that efficiency comes from actors sharing a small pool of real OS threads through Akka’s dispatcher, not from each actor getting anything resembling Erlang’s dedicated per-process heap and scheduler slice.

Kotlin Coroutines: The Model Becomes a Pattern

Kotlin’s coroutines library shipped an actor coroutine builder, a coroutine paired with a Channel that serves as its mailbox, giving you the surface shape of an actor, a single point of message entry, sequential processing, without any of the surrounding machinery. There is no supervision hierarchy. There is no isolated failure handling beyond ordinary coroutine cancellation. There is no scheduler-level guarantee about how the actor’s work is isolated from anything else running in the same process. It is, structurally, a convenience wrapper around a channel and a loop.

The kotlinx.coroutines project itself eventually conceded the point. The actor builder was marked with the @ObsoleteCoroutinesApi annotation, and its own documentation states plainly that it will become obsolete once a more complete actor implementation exists, a replacement that, years later, still has not shipped as a first-class API. The library’s 0.26 release, which introduced structured concurrency as Kotlin’s primary concurrency model, deprecated standalone builders like the original actor function in favor of scoped, structured alternatives. What began as “Kotlin has actors too” quietly became “Kotlin has a channel with a for-loop that we used to call an actor.”

Property	Erlang (language primitive)	Akka (library on the JVM)	Kotlin coroutines (deprecated builder)
Isolated per-actor heap	Yes, enforced by the BEAM	No, shared JVM heap	No, shared JVM heap
Supervision hierarchy	Yes, built into OTP	Yes, modeled on Erlang’s	No
Preemptive scheduling of actors	Yes, BEAM schedulers use reduction counting	Cooperative, via dispatcher thread pool	Cooperative, via the coroutine dispatcher
“Let it crash” failure semantics	Yes, a first-class runtime feature	Approximated through supervisor strategies	No equivalent; failures are ordinary exceptions
Status today	Core language feature	Actively maintained library	Marked obsolete by its own maintainers

The actor model’s path from formalism to language to library to a deprecated convenience API.

What actually survives the trip to a library

The mailbox. Every implementation here preserves the idea of a single, ordered inbox per actor, this is cheap to build on any platform and rarely gets cut.
Sequential message processing. One actor handles one message at a time everywhere in this lineage, since it’s the easiest guarantee to keep without runtime support.
What tends to disappear first is failure isolation. Supervision and “let it crash” depend on the runtime actually stopping a fault from spreading, and that’s exactly what a library running inside a general-purpose language cannot fully guarantee.
Memory isolation is the hardest guarantee to port. It requires a dedicated per-actor heap and garbage collector, which only a purpose-built runtime like the BEAM provides.

What We Learned

The actor model didn’t start as a concurrency mechanism at all, it started as Carl Hewitt’s 1973 attempt at a universal computational primitive for artificial intelligence, built on nothing but actors that create other actors, send messages, and decide how to handle the next one. Erlang, arriving at similar ideas independently more than a decade later, turned that formalism into a language where isolation, preemptive scheduling, and supervised failure are enforced by a purpose-built runtime, the BEAM. Akka carried the mailbox and the supervision philosophy onto the JVM, but as a library it can only ask actors to respect isolation the shared heap doesn’t actually enforce.

Kotlin’s coroutine-based actor builder went further still, keeping only the mailbox and sequential processing, and its own maintainers eventually marked it obsolete because a channel with a loop was never really the same guarantee Hewitt described in 1973. The lineage is real, but each step down from language primitive to library is a step where the runtime does less and the programmer’s discipline is asked to do more.

Tags

Containerize a Node.js App with Docker and Deploy with GitHub Actions

Omozegie Aziegbe — Mon, 24 Aug 2026 16:20:42 +0000

Node.js

Containerize a Node.js App with Docker and Deploy with GitHub Actions

Building an application is only one part of the software development process. Once an application is ready, it needs to be packaged, tested, distributed, and deployed consistently across different environments. Performing these tasks manually can quickly become repetitive and error-prone, especially when an application is updated frequently.

Docker and GitHub Actions provide a practical solution to this problem. For example, Docker packages a Node.js application and its dependencies into a portable container image, while GitHub Actions automates the process of testing, building, and publishing that image. The deployment environment can then retrieve the newly published image and start the updated application automatically.

In this article, we will build a workflow for a Node.js application. We will start by creating the application, containerize it with Docker, publish the image to Docker Hub, and then configure a GitHub Actions workflow that automatically builds and publishes a new image whenever changes are pushed to the GitHub repository.

1. The Problem with Traditional Deployments

A traditional deployment often requires a developer to manually connect to a server, retrieve the latest source code, install dependencies, restart the application, and verify that everything is working correctly.

This process may appear manageable for a small project. However, as an application evolves and deployments become more frequent, manual operations introduce unnecessary risk. We might forget to install a dependency, use the wrong Node.js version, leave an old process running, or deploy code that has not been tested properly.

There is also the problem of environment differences. The development machine might use one Node.js version while the production server uses another. Operating system libraries, environment variables, filesystem configuration, and dependency versions can also differ.

Docker addresses the environment problem by packaging the application with the runtime environment it requires. Instead of asking the production server to recreate the application’s environment manually, the server runs a Docker image containing the application and its required dependencies.

CI/CD addresses another part of the problem: automation. Instead of manually testing and packaging every change, a pipeline can perform these operations whenever code is pushed to a particular branch. The result is a deployment process that is more consistent, repeatable, and easier to maintain.

2. What is Docker and How It Works

Docker provides a way to package applications into lightweight, isolated containers. A Docker container contains the application and the software required to run it, allowing the application to behave consistently across environments.

There are several Docker concepts that are important for this article. A Dockerfile describes how an application image should be built. A Docker image is the packaged result of that build process. A container is a running instance of an image. Finally, a container registry stores images so that they can be downloaded by other systems.

For example, we can build an image locally and run it as a container. The same image can then be pushed to Docker Hub and pulled onto a Virtual Private Server.

This separation is useful because the server does not need to rebuild the application from source code. It simply downloads the already-built image and runs it.

Docker images are also immutable in the sense that a particular image represents a specific application build. When a new version is created, a new image can be published. This makes it easier to identify which version is running and, when appropriate, roll back to an earlier image.

Key Docker Concepts

Image
A blueprint for creating containers. It is built from a Dockerfile.

Container
A running instance of an image.

Dockerfile
A script that defines how an image is built.

Registry
A storage location for Docker images (e.g., Docker Hub, GitHub Container Registry).

3. Prerequisites

This tutorial assumes that the application will be developed locally, stored in a GitHub repository, published to Docker Hub, and eventually deployed to a Linux-based Virtual Private Server.

You should have Node.js and npm installed locally, together with Docker and Git. You will also need a GitHub account and a Docker Hub account.

For the deployment portion, you will need a VPS with Docker installed and SSH access configured. The exact VPS provider is not important because the deployment process relies primarily on SSH and Docker.

It is also useful to have a basic understanding of Node.js, Express, Git, Docker commands, and YAML configuration files. You do not need previous experience with GitHub Actions because the workflow will be explained.

4. Build a Production-Ready Node.js Application

The first step is to create the application that will eventually be placed inside a Docker container. Although the example application is intentionally small, the same principles can be applied to larger REST APIs and backend services.

Create a new Node.js project and initialize npm.

mkdir node-docker-app 
cd node-docker-app 
npm init -y 
npm install express

These commands create the project directory, initialize a Node.js project, and install Express as the application’s web framework. The resulting project will contain a package.json file describing the application and its dependencies.

Create an index.js file containing the application logic.

const express = require("express");
const app = express();
app.use(express.json());

const PORT = process.env.PORT || 3000;

app.get("/", (req, res) => {
    res.json({
        message: "Hello from a Dockerized Node.js application",
        environment: process.env.NODE_ENV || "development"
    });
});

app.get("/health", (req, res) => {
    res.status(200).json({
        status: "OK"
    });
});

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

The application exposes two endpoints. The root endpoint provides a simple response that confirms the application is running, while /health acts as a health endpoint that can be used by deployment and monitoring systems.

Notice that the application obtains its port from the PORT environment variable and falls back to port 3000. This is important for containerized applications because the same image can be deployed in environments where the application port is configured differently.

Update the package.json scripts:

  "scripts": {
    "start": "node src/index.js"
  }

The start script provides a standard command for launching the application. Docker and deployment environments can use this command rather than depending on a machine-specific startup process.

Before introducing Docker, test the application locally:

npm start

Running the application locally first provides a useful baseline. If the application does not work before containerization, Docker is unlikely to solve the underlying application problem.

5. Understanding the Dockerfile

The Dockerfile is the central configuration file used to transform the Node.js project into a Docker image. It describes the base image, working directory, dependencies, source files, exposed port, and command used to start the application.

Create a file named Dockerfile in the root of the project.

FROM node:20-alpine 

WORKDIR /app 

COPY package*.json ./ 

RUN npm ci --omit=dev

COPY . . 

ENV NODE_ENV=production 

EXPOSE 3000 

CMD ["node", "src/index.js"]

The FROM instruction selects the Node.js runtime used by the application. The Alpine variant provides a relatively small base image, which can reduce image size and transfer time.

WORKDIR establishes /app as the working directory inside the container. The package files are copied before the rest of the source code so Docker can reuse the dependency installation layer when application source files change but the dependencies remain unchanged.

RUN npm ci --omit=dev installs the exact dependency versions recorded in package-lock.json and excludes development dependencies. Development-only packages are excluded because they are not required to run the application in production.

Note
The ordering of these instructions is important because Docker builds images in layers. Structuring the Dockerfile properly allows Docker to reuse unchanged layers and significantly reduce build time.

Optimizing with .dockerignore

Not every file in the project should be copied into the Docker build context. Local dependencies, Git metadata, logs, and development files are unnecessary for the production image.

Create a .dockerignore file:

node_modules 
npm-debug.log 
.git 
.gitignore 
Dockerfile 
.dockerignore 
.env
README.md

This configuration prevents unnecessary files from being sent to Docker during the build. In particular, excluding node_modules is important because dependencies should be installed inside the image using the package manifest.

The .env file is also excluded because sensitive configuration should not be baked into the Docker image. Production secrets should instead be supplied through the deployment environment. Keeping the Docker build context small can improve build performance and reduce the possibility of accidentally exposing development files or sensitive information.

6. Building and Running the Container

With the Dockerfile and .dockerignore in place, the application can now be converted into a Docker image.

Build the image with:

docker build -t node-docker-app .

The docker build command reads the Dockerfile and creates an image. The -t option assigns the image the name node-docker-app, while the final period tells Docker to use the current directory as the build context.

After building the image, start a container:

docker run -p 3000:3000 --name node-app node-docker-app

The -p option maps port 3000 on the host machine to port 3000 inside the container. The --name option gives the container a convenient name. The application can now be accessed through the host machine at port 3000.

For a background process, the container can be started in detached mode:

docker run -d -p 3000:3000 --name node-app node-docker-app

The -d option runs the container in the background. This is closer to how a container will normally run on a server. You can inspect the running container with:

docker ps

And stop it with:

docker stop node-app

These commands are useful during local development because they allow us to verify that the Docker image behaves correctly before introducing the CI/CD pipeline.

Multi-Stage Builds for Smaller Images

For simple Node.js applications, a single-stage Dockerfile may be sufficient. Larger applications, however, can benefit from multi-stage builds. A multi-stage build allows the Dockerfile to use one stage for building the application and another stage for running it.

FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./

RUN npm ci

COPY src ./src


FROM node:20-alpine AS production

WORKDIR /app

COPY package*.json ./

RUN npm ci --omit=dev

COPY --from=builder /app/src ./src

ENV NODE_ENV=production

EXPOSE 3000

CMD ["node", "src/index.js"]

The first stage installs all dependencies and prepares the application. The second stage starts from a clean Node.js image and copies the application from the builder stage.

The final image does not need to contain the tooling or development dependencies used during the build stage. This can reduce the size of the final image and decrease the amount of unnecessary software present in the production container.

For applications that require compilation, TypeScript, frontend builds, or other build-time tooling, multi-stage Dockerfiles become particularly useful.

7. Tagging and Pushing to a Registry

A locally built Docker image is not automatically available to a production server. The image needs to be published to a container registry that the deployment server can access.

Docker Hub is one option for storing container images. First, authenticate with Docker Hub:

docker login

After authentication, tag the image using your Docker Hub repository name:

docker tag node-docker-app yourusername/node-docker-app:latest

The tag identifies where the image should be published. The latest tag is commonly used for the most recent build, although version-specific tags are preferable for production deployments.

Push the image:

docker push yourusername/node-docker-app:latest

Docker uploads the image layers to Docker Hub. Once the operation completes, another machine with permission to access the repository can pull the image.

Version tags can also be used:

docker tag node-docker-app yourusername/node-docker-app:1.0.0 
docker push yourusername/node-docker-app:1.0.0

Versioned images make deployments easier to trace because a deployment can explicitly reference a known version instead of relying entirely on a moving latest tag.

8. Introduction to GitHub Actions CI/CD

At this point, the application can be containerized and published manually. The next step is to remove that manual work by introducing GitHub Actions. GitHub Actions provides automation directly within a GitHub repository. A workflow can respond to repository events, execute commands, run tests, build Docker images, and publish artifacts.

The goal of this article is to create a workflow where we can edit the source code, commit the change, and push it to GitHub. Once the change reaches the configured branch, GitHub Actions takes over the repetitive deployment tasks.

The complete process will be:

Code Change → Git Commit → Git Push → Automated Tests → Docker Image Build → Docker Hub Publication → VPS Deployment

This approach turns the Git repository into the starting point for the deployment process.

Creating the Workflow File

GitHub Actions workflows are YAML files stored inside the .github/workflows directory of the repository. Create a file named deploy.yml.

name: Node.js CI/CD

on:
  push:
    branches:
      - main

jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build Docker image
        run: docker build -t ${{ secrets.DOCKER_USERNAME }}/node-docker-app:latest .

      - name: Push Docker image
        run: docker push ${{ secrets.DOCKER_USERNAME }}/node-docker-app:latest

This workflow is triggered whenever code is pushed to the main branch. GitHub creates an Ubuntu-based runner and executes the defined steps sequentially.

The first step checks out the repository so that the workflow has access to the Node.js source code, package.json, package-lock.json, Dockerfile, and other project files.

The Node.js setup step configures Node.js 20 on the GitHub Actions runner. The npm ci command then installs the dependencies specified by package-lock.json. Using npm ci is appropriate for CI environments because it provides a clean and reproducible dependency installation.

After the dependencies are installed, the workflow authenticates with Docker Hub using credentials stored as GitHub Actions secrets. It then builds the Docker image using the Dockerfile located in the project root.

The image is tagged using the Docker Hub username stored in DOCKER_USERNAME:

yourusername/node-docker-app:latest

Finally, docker push publishes the image to Docker Hub. At this point, the newly built image is available for the deployment environment to retrieve.

At this stage, the project should have a structure similar to the following:

node-docker-app/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── src/
│   └── index.js
├── .dockerignore
├── .env
├── .gitignore
├── Dockerfile
├── package.json
└── package-lock.json

The src directory contains the Node.js application, while the Dockerfile describes how the application is packaged into a container. The .github/workflows/deploy.yml file contains the CI/CD workflow that GitHub Actions will execute.

Managing Secrets Securely

A CI/CD pipeline frequently needs access to credentials, API keys, SSH keys, and other sensitive configuration. These values should never be committed directly to the repository. Docker Hub credentials are used by the GitHub Actions workflow to authenticate with Docker Hub before building and publishing the image.

Go to:

GitHub repository → Settings → Secrets and variables → Actions → Secrets → New repository secret

Add these two secrets:

Secret	Value
DOCKER_USERNAME	Your Docker Hub username
DOCKER_PASSWORD	Your Docker Hub access token

GitHub injects these values into the workflow when it runs without requiring them to appear in the source code. For a VPS deployment, additional secrets will be required, such as the server hostname, username, and SSH private key. This separation is important because the workflow definition can remain in the repository while sensitive credentials remain protected by the GitHub Actions secrets mechanism.

Commit and Push the Workflow

After creating the workflow file, stage it, create a commit with and push the changes to the main branch using:

git add .
git commit -m "Add GitHub Actions CI/CD workflow"
git push origin main

The push to main is what triggers the GitHub Actions workflow.

After pushing the workflow, open the GitHub repository in your browser and select the Actions tab. You should see a workflow named: Node.js CI/CD.

Click the workflow run to see the individual steps being executed. A successful run should show steps similar to:

Figure 1: GitHub Actions workflow for containerizing a Node.js application with Docker and deploying it automatically.

Once the workflow completes successfully, open your Docker Hub repository. You should see: node-docker-app:latest. This confirms that GitHub Actions successfully built the Docker image and published it to Docker Hub.

At this point, the CI portion of the pipeline is working. The next stage is to configure the Virtual Private Server so that it can pull the newly published Docker image and automatically restart the application whenever a new image is available.

9. Deploying the Docker Image to a VPS

Once GitHub Actions has successfully built the Docker image and published it to Docker Hub, the image can be deployed to a Virtual Private Server or another Docker-enabled server. The server does not need the application source code because it can retrieve the already-built image directly from Docker Hub.

First, connect to your VPS through SSH and pull the latest image:

docker pull yourusername/node-docker-app:latest

Replace yourusername with your actual Docker Hub username. The docker pull command downloads the image published by the GitHub Actions workflow to the server.

Once the image has been downloaded, Docker has everything required to start the application without needing to clone the GitHub repository or install Node.js directly on the VPS.

After pulling the image, start the application with:

docker run -d \
  --name node-app \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e PORT=3000 \
  yourusername/node-docker-app:latest

When a new version of the application is pushed to main, GitHub Actions builds a new Docker image and publishes it to Docker Hub. The VPS can then retrieve the latest image and replace the currently running container.

10. Using Docker Compose for Better Management

As the application grows, managing containers with long docker run commands can become difficult, especially when environment variables, restart policies, volumes, and networking need to be configured. Docker Compose provides a cleaner way to define the application’s container configuration in a YAML file and manage the container with simple commands.

Create a compose.yml file in the project root:

services:
  app:
    image: yourusername/node-docker-app:latest
    container_name: node-app
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: 3000
    restart: unless-stopped

The image property specifies the Docker image that Docker Compose should run, while container_name gives the container a predictable name.

The ports configuration maps port 3000 on the VPS to port 3000 inside the container. The environment section supplies the production environment variables used by the Node.js application.

The restart: unless-stopped policy tells Docker to automatically restart the container if it stops unexpectedly or if the VPS is restarted. The container will remain stopped only when it has been explicitly stopped by the administrator.

The application can then be started with:

docker compose up -d

Health Checks and Monitoring

A running Docker container does not necessarily mean that the application inside it is functioning correctly. The Node.js process could stop responding while the container itself remains running, which is why a health check is useful. The /health endpoint already implemented in this application provides a simple way to verify that the Express server is responding.

Docker Compose can use this endpoint to determine whether the application is healthy. Add a healthcheck configuration to the Compose file:

services:
  app:
    image: yourusername/node-docker-app:latest
    container_name: node-app
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: 3000
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

The healthcheck instructs Docker to periodically request the application’s /health endpoint. The interval determines how frequently the check runs, while timeout specifies how long Docker waits for a response.

The retries property specifies how many consecutive failures are required before Docker considers the container unhealthy. The start_period gives the Node.js application a short amount of time to start before health checks begin counting failures.

You can check the health status with:

docker compose ps

A healthy container should show a status similar to:

NAME        IMAGE                              STATUS
node-app    yourusername/node-docker-app:latest   Up ... (healthy)

11. Conclusion

In this article, we explored how to containerize a Node.js application with Docker and build a CI/CD pipeline using GitHub Actions. We started by creating a Dockerfile for the Node.js application and used a multi-stage build to separate the application preparation process from the production runtime image. We then configured environment variables, built and tested the Docker image locally, and published the image to Docker Hub through an automated GitHub Actions workflow.

We also covered how the published Docker image can be deployed to a Virtual Private Server and managed using Docker Compose. The deployment process can pull new images from Docker Hub and recreate the running container with the latest application version. Finally, we added a health-check endpoint and Docker health checks to provide a simple way to verify that the application is running correctly.

The resulting workflow provides a foundation for continuous delivery: we push changes to GitHub, GitHub Actions builds the Docker image and publishes it to Docker Hub, and the VPS can retrieve and run the latest version.

12. Download the Source Code

This article explored the process of packaging a Node.js application with Docker and deploying it using GitHub Actions.

Download
You can download the full source code of this example here: containerize a node js app with docker and deploy with github actions

Tags

Java Code Geeks

Testcontainers + Spring Boot 4: The Integration Test Setup Teams Actually Use

Pattern One: Singleton Containers, Not @Container Lifecycle

Pattern Two: @ServiceConnection Instead of @DynamicPropertySource

Pattern Three: Reuse Is Not a Substitute for Singleton

Where each mechanism actually belongs

Pattern Four: Parallel Isolation, Told Honestly

What Spring Boot 4’s AOT Changes Do to Test Startup

What We Learned

Thank you!

Spring AI with Local LLMs Using LM Studio

1. Understanding Local LLMs and LM Studio

1.1 What is a Local LLM?

1.1.1 Why Use Local LLMs?

1.2 What is LM Studio?

2. Integrating Spring AI with LM Studio

2.1 Maven Dependencies

2.2 Configure application.properties

2.3 Create the Spring Boot Application

2.4 Create the Response Model

2.5 Create the LLM Service

2.6 Create the REST Controller

2.7 Run and Test the Application

3. Conclusion

Thank you!

[FREE EBOOKS] Microsoft 365 Excel Office Scripts For Dummies, Infinite & Four More Best Selling Titles

Microsoft 365 Excel Office Scripts For Dummies ($34.99 Value) FREE for a Limited Time

Infinite: How Visionary Leaders Transform Today’s Businesses into AI-Forward Companies ($34.00 Value) FREE for a Limited Time

Artificial Intelligence, Cybersecurity and Cyber Defense ($30.00 Value) FREE for a Limited Time

Marketing 7.0: A Guide for Thinking Marketers in the Age of AI ($30.00 Value) FREE for a Limited Time

7 Prompt Engineering Mistakes With ChatGPT and Fixes ($21 Value) FREE For a Limited Time

25 GPT-5 ChatGPT Sales Prompts That Close Deals ($21 Value) FREE For a Limited Time

Thank you!

How to Deploy a Java Side Project on a Budget

Choosing a Java Project to Deploy

Preparing the Application for Production

Choosing Where to Host It

Deploying a Java Application to a VPS

Keeping Hosting Costs Under Control

Thank you!

Access Request and Response Body in HandlerInterceptor

1. Accessing Request and Response Bodies in HandlerInterceptor

1.1 How HandlerInterceptor Works

1.2 Understanding ContentCachingRequestWrapper and ContentCachingResponseWrapper

1.3 Key Points to Consider

2. Implementing Request and Response Body Logging

2.1 Define the Request DTO

2.2 Create the REST Controller

2.3 Add the Content Caching Filter

2.4 Create the Request-Response Logging Interceptor

2.5 Register the Interceptor

2.6 Run the Application and Verify the Output

3. Conclusion

Thank you!

Project Valhalla in Practice: Writing Your First Value Class

Getting the Early-Access Build Running

Declaring Your First Value Class

What You Lose: Identity and Synchronization

What You Gain: Flat Memory Layout and JIT Inlining

Benchmarking the Difference

How to run your own version of this benchmark

What We Learned

Thank you!

Structured Concurrency: What Changes for the Try/Catch Generation

Where Things Actually Stand

The Old Way: A CompletableFuture Chain

The New Way: StructuredTaskScope

Where It Still Falls Short: The JDBC Problem

What to actually do about it today

What We Learned

Thank you!

Compact Object Headers in Production: The Free 15–25% Heap Reduction Nobody Enabled

What’s Actually Sitting in Every Object Header

The Fix: One 64-Bit Word Instead of Two

The Myth: “It’s On by Default in Java 25”

The Real Numbers, Not Marketing Numbers

Rollout checklist before you flip the flag

What We Learned

Thank you!

The Actor Model’s Long Lineage: From Hewitt’s 1973 Paper to Kotlin Coroutines