spawn

A Java framework for programmatically launching and controlling processes, JVMs, and Docker containers.

Overview

spawn provides a unified abstraction over local processes, JVMs, and Docker containers. Define a Specification, call platform.launch(spec), and get back an Application with CompletableFuture-based lifecycle hooks — regardless of the underlying execution environment.

Modules

Module	Purpose
spawn-option	Shared option types
spawn-application	Core abstractions: Platform, Application, Process, Specification, Customizer
spawn-application-composition	Multi-application topology management
spawn-jdk	JDK launch abstractions and SpawnAgent for two-way JVM communication
spawn-local-platform	Local OS process launcher (LocalMachine)
spawn-local-jdk	JDK detection and LocalJDKLauncher
spawn-docker	Docker Engine API interfaces
spawn-docker-jdk	JDK HTTP Client-based Docker implementation

Requirements

• Java 25+
• Maven (wrapper included — no separate install needed)
• Docker (only required for spawn-docker / spawn-docker-jdk modules)

Using this Library

Add individual modules as dependencies. All modules share the same version:

<dependency>
    <groupId>build.spawn</groupId>
    <artifactId>spawn-application</artifactId>
    <version>VERSION</version>
</dependency>

Replace VERSION with the latest version shown in the Maven Central badge above.

When using the Docker modules, add the following JVM flag (Java 25+):

--enable-native-access=ALL-UNNAMED

On macOS and Linux, access to the Docker socket may require a permissions adjustment:

sudo chmod 660 ~/Library/Containers/com.docker.docker/Data/docker.raw.sock
sudo chmod 660 /var/run/docker.sock

If /var/run/docker.sock is missing, recreate the symlink:

sudo ln -s ~/Library/Containers/com.docker.docker/Data/docker.raw.sock /var/run/docker.sock

Building from Source

./mvnw clean install

To build a custom version:

./mvnw -Drevision=x.y.z-SNAPSHOT-my-name clean install

Running Tests

Docker integration tests require several images to be present in the local cache. Pre-pull them once before running:

docker pull alpine:latest && docker pull rabbitmq:latest && docker pull nginx:latest

Contributing

Code style is enforced by Checkstyle: no tabs, no star imports, final locals and parameters, braces required on all blocks, no assert statements. Import order: third-party, standard Java, then static. IntelliJ configuration is at config/intellij/CodeStyle.xml.

Commit messages follow Conventional Commits.

License

Apache 2.0 — see LICENSE