SteeltoeOSS Docker Images

GitHub repo for server images to use for local development with SteeltoeOSS.

Images

Name	Description
steeltoe.azurecr.io/config-server	Spring Cloud Config Server
steeltoe.azurecr.io/eureka-server	Spring Cloud Netflix Eureka Server
steeltoe.azurecr.io/spring-boot-admin	Spring Boot Admin
steeltoe.azurecr.io/uaa-server	Cloud Foundry UAA Server

See Common Tasks for instructions on how to run these images.

---

Architecture

Excluding UAA, each server image (config-server, eureka-server, spring-boot-admin) has a ready-to-build Gradle project in its source/ directory. The source/ directory is regenerated from scratch by update-project.ps1 whenever the Spring Boot version or dependencies need to change.

update-project.ps1
    │  1. Download fresh project zip from start.spring.io
    │  2. Apply patches/         <-- modify Initializr-generated files
    │  3. Apply customizations/  <-- add content Initializr never generates
    │  4. Regenerate gradle.lockfile
<image>/source/    <-- committed, ready-to-build
    │
build.ps1  -->  bootBuildImage  -->  Docker image

patches/ vs customizations/

Use patches when modifying content that Initializr generates (Java source files, application.properties). Patches are standard unified diff files applied with patch -p1.

Use customizations for content that Initializr never generates:

• build.gradle.append - appended to the generated build.gradle. Contains the image-build hardening: digest-pinned builder/runImage, a reproducible createdDate, dependencyLocking, and the bootBuildImage --> test dependency gate. An append is used rather than a patch because this block is entirely new content. A line-anchored patch at the end of a file that Initializr can restructure is fragile.
• overlay/ - files copied verbatim over the generated project, mirroring the project layout. Contains hand-written tests and any other files Initializr would never produce (for example: BasicOrNoAuthConfig.java for config-server).

Edit patches or customizations, not source/ directly. Then run update-project.ps1 to regenerate.

Reproducible Builds

Images are built reproducibly:

• Builder and run images are pinned by digest in build.gradle.append
• Dependency versions are locked in gradle.lockfile (regenerated by update-project.ps1)
• The image creation timestamp is derived from the git commit, not the wall clock

gradle-wrapper.jar

The Gradle wrapper jar is not committed (.gitignore). build.ps1 downloads it from GitHub on first use and validates its SHA-256 checksum against Gradle's official distribution on every build, regardless of whether the jar was just downloaded. This defends against a tampered or substituted jar from any source.

---

Building

Prerequisites

The following tools are required to build any image in this repository:

1. PowerShell or pwsh
2. Docker or Podman

Config Server, Eureka, and Spring Boot Admin additionally require:

1. JDK 25
2. Internet access (to download the Gradle distribution and Maven dependencies on first build)

If you do not have a JDK installed, consider Scoop:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
scoop bucket add java
scoop install java/temurin25-jdk

Build a specific image

./build.ps1 config-server

The build runs the project's tests first and fails if any test fails.

List created images

docker images

---

Updating Source

Run update-project.ps1 to regenerate source/ from start.spring.io and apply all patches and customizations:

.\update-project.ps1                                     # update all Java images
.\update-project.ps1 -Names config-server                # update one image
.\update-project.ps1 -Names config-server,eureka-server  # update multiple images

Requires JDK 25 and network access (resolves dependencies to regenerate gradle.lockfile). Also requires patch in your PATH (installed with Git for Windows).

The script checks start.spring.io for a newer Spring Boot version in your current track (major.minor) and reports if a newer compatible version is available. It also resolves the current Spring Cloud or Spring Boot Admin artifact version from the Spring Cloud BOM POM and automatically updates IMAGE_VERSION when a new version is detected.

Workflow for a version bump

1. Run update-project.ps1 - it will auto-update IMAGE_VERSION in metadata/ and regenerate source/
2. Review the changes in source/ (especially the lockfile)
3. If patches no longer apply cleanly, update the relevant patch file
4. Run ./build.ps1 -Name <image> to verify the Docker image build
5. Commit metadata/, patches/, customizations/, and source/

Workflow for a patch or customization change

1. Edit the relevant file under patches/ or customizations/
2. Run update-project.ps1 to regenerate source/
3. Run ./build.ps1 -Name <image> to verify the Docker image build
4. Commit everything

---

Releasing

Releases are triggered by publishing a GitHub release. The release workflow builds and smoke-tests each image, then pushes the following tags:

• <version> - exact version (for example: 4.3.1)
• <major.minor> - floating minor alias (for example: 4.3)
• <major> - floating major alias (for example: 4)
• latest

IMAGE_REVISION - hotfix releases

IMAGE_REVISION allows publishing a new image for the same package version without changing the version number (for example:, after a buildpack or infrastructure fix). The lifecycle:

• Normal release: IMAGE_REVISION is empty --> published tag is 4.3.1, floating aliases updated
• Hotfix: set IMAGE_REVISION to 2, commit, trigger a release --> published tag is 4.3.1-2, floating aliases updated
• Subsequent hotfixes: increment to 3, 4, etc. Do not clear IMAGE_REVISION after each release - the number stays set so the next hotfix knows where to start
• Version bump: clear IMAGE_REVISION (back to empty) when IMAGE_VERSION is bumped. update-project.ps1 does this automatically when it detects and applies a new version.

---

Debugging

Inspect container contents

Via StackOverflow:

1. Find the id of the stopped container: docker ps -a
2. Commit it to a new image: docker commit $CONTAINER_ID test_image
3. Run with a shell: docker run -ti --entrypoint=sh test_image