fix(examples): use proper image and align with SDK conventions by mp-orkes · Pull Request #118 · conductor-oss/java-sdk

mp-orkes · 2026-05-11T21:59:31Z

What

Docker image: replace orkesio/orkes-conductor-standalone:1.2.3 (doesn't exist) with conductoross/conductor:latest. Pinning to a fixed version would be the best practice, but since these are examples I'm using :latest so demos stay current without periodic PRs.
Env var rename: CONDUCTOR_BASE_URL → CONDUCTOR_SERVER_URL everywhere (helper, run.sh, docker-compose.yml, RUNNING.md, PRODUCTION.md docs). Matches the SDK convention.
Drop the helper's env-var plumbing: each ConductorClientHelper.java no longer carries a static CONDUCTOR_SERVER_URL field with its own ternary fallback. The builder calls .useEnvVariables(true), which the SDK already implements in ConductorClient.Builder.applyEnvVariables() — that method reads CONDUCTOR_SERVER_URL from the environment.
Build via dockerized Maven in run.sh: run.sh now invokes Maven inside a maven:3.9-eclipse-temurin-21 container (bind-mounting the example directory and ~/.m2) instead of calling host mvn. No mvnw files added to the repo.

Why

The Quick Start in examples/README.md and docker run in examples/RUNNING.md referenced an image that doesn't exist.
Follow the SDK's conventions for env-var naming and resolution rather than carrying parallel plumbing in every example.
Docker is already a stated prerequisite for the examples; having to install Maven on the host on top of that was needless friction.

Behavior changes

CONDUCTOR_SERVER_URL is now required when running the bare jar. The old helper fell back to http://localhost:8080/api; the SDK throws RuntimeException("env variable CONDUCTOR_SERVER_URL is not set") instead. run.sh and every docker-compose.yml already set the var, so the documented happy paths are unaffected.
examples/basics/docker-setup and examples/task-patterns/chaining-http-tasks exposed a getServerUrl() helper that returned the now-deleted constant. Both now return client.getBasePath() (instance method); the docker-setup Example main was reordered to instantiate the helper before the health-check probe.
examples/basics/orkes-cloud left untouched — its helper has a dual-mode (local + cloud) design with custom header-supplier auth and explicit (serverUrl, keyId, keySecret) constructor that doesn't fit the useEnvVariables pattern.

How to test

docker run -d --name conductor -p 8080:8080 -p 1234:5000 conductoross/conductor:latest
# wait ~30s for health
curl -sf http://localhost:8080/health   # healthy:true
open http://localhost:1234              # UI loads

# run.sh builds the jar inside Docker (no host Maven needed) and runs it against the local Conductor
cd examples/basics/hello-world
./run.sh
# expects: Result: PASSED

# Bare jar with no env should fail clearly:
java -jar target/hello-world-1.0.0.jar
# expects: RuntimeException("env variable CONDUCTOR_SERVER_URL is not set")

…var with SDK The Quick Start in examples/README.md and ~790 docker-compose.yml files referenced orkesio/orkes-conductor-standalone:1.2.3, which is a private Orkes commercial image on GHCR (anonymous pulls return 401). Swap to the public conductoross/conductor:3.22.3 (newest GA on Docker Hub, server + UI bundled, same internal port 5000 for the UI). Rename CONDUCTOR_BASE_URL to CONDUCTOR_SERVER_URL across the helper, run.sh, docker-compose.yml, RUNNING.md and PRODUCTION.md docs so the example env var name matches the Conductor Java SDK convention (ConductorClient.Builder.applyEnvVariables reads CONDUCTOR_SERVER_URL). Users who graduate from the example helper to direct SDK usage no longer trip on a renamed variable. Verified locally by docker-building examples/basics/hello-world and running it end-to-end against conductoross/conductor:3.22.3 — workflow completes, UI reachable on the mapped port. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

codecov · 2026-05-11T22:02:26Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…(true) Drop the per-helper CONDUCTOR_SERVER_URL static field across 790 ConductorClientHelper.java files and call .useEnvVariables(true) on the SDK builder instead. The SDK already reads CONDUCTOR_SERVER_URL in ConductorClient.Builder.applyEnvVariables(); duplicating that logic in each example was redundant. Side effects: - The localhost fallback is gone. CONDUCTOR_SERVER_URL must now be set (run.sh and docker-compose.yml already do this in every example). Running the bare jar with no env now throws a clear RuntimeException from the SDK: "env variable CONDUCTOR_SERVER_URL is not set". - examples/basics/docker-setup and examples/task-patterns/chaining-http-tasks exposed a getServerUrl() helper that returned the now-removed constant. Both now return client.getBasePath() (instance method); docker-setup's Example main was reordered to instantiate the helper before the health check probe. - examples/basics/orkes-cloud intentionally left unchanged — its helper has a dual-mode (local + cloud) design with custom auth and explicit serverUrl/keyId/keySecret constructor. Verified by docker-building and running hello-world, docker-setup, and chaining-http-tasks end-to-end against conductoross/conductor:3.22.3. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Switch from the latest GA (3.22.3) to the newest 3.30.0 release candidate. Smoke-tested locally: container healthy, UI bundled on internal port 5000 unchanged, hello-world end-to-end completes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Replace bare 'mvn package' in every example's run.sh with a one-shot 'docker run ... maven:3.9-eclipse-temurin-21 mvn ...' invocation that bind-mounts the example directory and ~/.m2 for the dep cache. Docker was already a stated prerequisite (RUNNING.md:9); host Maven no longer needs to be installed at all. No mvnw wrapper artifacts added to the repo. Verified locally: hello-world builds in ~2s with a warm ~/.m2 cache and runs end-to-end against conductoross/conductor:3.30.0.rc12. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mp-orkes · 2026-05-12T01:07:01Z

 public class ConductorClientHelper {

-    private static final String CONDUCTOR_SERVER_URL =
-            System.getenv("CONDUCTOR_BASE_URL") != null


Not the env var name our SDKs use. Aligning on CONDUCTOR_SERVER_URL to follow the SDK convention

mp-orkes · 2026-05-12T01:08:22Z

    public ConductorClientHelper() {
        this.client = ConductorClient.builder()
-                .basePath(CONDUCTOR_SERVER_URL)
+                .useEnvVariables(true)


Reads the server URL (and Orkes auth keys, if present) from the SDK's standard env vars: CONDUCTOR_SERVER_URL.

This was shown in several examples.

mp-orkes · 2026-05-12T01:14:57Z

@@ -1,6 +1,6 @@
 services:
  conductor:
-    image: orkesio/orkes-conductor-standalone:1.2.3


:1.2.3 tag doesn't exist in our private registry. It was made up. So this was broken for everyone

mp-orkes · 2026-05-12T01:18:19Z

+    echo "Conductor is running at $CONDUCTOR_SERVER_URL"
    echo "Building and running the example..."
    echo ""
-    mvn -q package -DskipTests 2>/dev/null || mvn package -DskipTests


Requiring a Maven install adds friction. That's exactly why build-tool wrappers (Gradle's gradlew, Maven's mvnw) exist.

Side question: What was the motivation to use Maven? (we've been using Gradle in most of our projects)

mp-orkes · 2026-05-12T01:22:11Z

    echo ""
-    mvn -q package -DskipTests 2>/dev/null || mvn package -DskipTests
-    CONDUCTOR_BASE_URL="$CONDUCTOR_BASE_URL" java -jar target/aggregator-pattern-1.0.0.jar "$@"
+    docker run --rm -v "$PWD":/work -v "$HOME/.m2":/root/.m2 -w /work maven:3.9-eclipse-temurin-21 mvn -q package -DskipTests 2>/dev/null || docker run --rm -v "$PWD":/work -v "$HOME/.m2":/root/.m2 -w /work maven:3.9-eclipse-temurin-21 mvn package -DskipTests


Building via Docker since it's already required by the examples anyway.

Flagging that this contradicts our previous decision to keep Docker out of our examples. Assuming that's no longer our stance.

Switch from a pinned 3.30.0.rc12 to the floating :latest tag for all example image references (READMEs, RUNNING.md, docker-compose files, helper console output). Production code should pin a digest or version, but examples follow whatever GA the upstream image currently points :latest at, which keeps demos current without periodic PR churn. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mp-orkes self-assigned this May 11, 2026

mp-orkes changed the title ~~fix(examples): use public conductoross/conductor image and align env var with SDK~~ WIP - fix(examples): use proper image and align with SDK conventions May 11, 2026

mp-orkes requested review from c4lm, nohup23 and v1r3n May 11, 2026 22:36

mp-orkes and others added 2 commits May 11, 2026 19:38

mp-orkes marked this pull request as ready for review May 12, 2026 01:05

mp-orkes commented May 12, 2026

View reviewed changes

mp-orkes changed the title ~~WIP - fix(examples): use proper image and align with SDK conventions~~ fix(examples): use proper image and align with SDK conventions May 12, 2026

mp-orkes requested review from bradyyie, chrishagglund-ship-it, manan164 and nthmost-orkes May 12, 2026 01:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(examples): use proper image and align with SDK conventions#118

fix(examples): use proper image and align with SDK conventions#118
mp-orkes wants to merge 5 commits into
mainfrom
fix/examples-image-and-envvar

mp-orkes commented May 11, 2026 •

edited

Loading

Uh oh!

codecov Bot commented May 11, 2026 •

edited

Loading

Uh oh!

mp-orkes May 12, 2026

Uh oh!

mp-orkes May 12, 2026

Uh oh!

mp-orkes May 12, 2026

Uh oh!

mp-orkes May 12, 2026

Uh oh!

mp-orkes May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mp-orkes commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Behavior changes

How to test

Uh oh!

codecov Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mp-orkes May 12, 2026

Choose a reason for hiding this comment

Uh oh!

mp-orkes May 12, 2026

Choose a reason for hiding this comment

Uh oh!

mp-orkes May 12, 2026

Choose a reason for hiding this comment

Uh oh!

mp-orkes May 12, 2026

Choose a reason for hiding this comment

Uh oh!

mp-orkes May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mp-orkes commented May 11, 2026 •

edited

Loading

codecov Bot commented May 11, 2026 •

edited

Loading