Skip to content

Java SDK Deployment Cookbook

Best practices and repeatable recipes for Spring Boot–based extensions.

Scaffold & structure

  • Use kiket extensions scaffold my-java-extension --sdk java to generate .kiket/manifest.yaml, replay fixtures, and GitHub Actions.
  • Keep handlers in src/main/java/.../handlers and wire them in Main.java or via Spring configuration classes.

Build & package

./mvnw clean package
java -jar target/my-extension.jar
  • For container builds, use a multi-stage Dockerfile (Maven → slim JRE).
  • Set JAVA_OPTS="-Dserver.port=8080" if your platform injects a different port.

Deployment targets

Platform Notes
Cloud Run Package as a container, set min instances for guard hooks, and map secrets via Secret Manager → env vars.
GKE / Kubernetes Deploy the jar image, configure readiness probe against /health, and set resource requests for consistent latency.
VM / EC2 Run the jar under systemd, add log rotation, and export /health to your load balancer.

CI workflow

Add the following to GitHub Actions / Jenkins:

  1. kiket extensions lint
  2. ./mvnw verify
  3. kiket extensions replay --template workflow.before_transition --url $DEPLOY_URL/v/1/webhooks/workflow.before_transition
  4. Deploy artifact

Secrets & configuration

  • Declare secrets in the manifest and sync via kiket marketplace secrets sync.
  • During deploys, inject them as KIKET_SECRET_<KEY> env vars or use your preferred secret manager (HashiCorp Vault, AWS Secrets Manager, etc.).
  • Use context.getSecrets().rotate() when you need temporary API tokens for downstream services.

Telemetry & logging

  • Leave telemetry enabled so admins can view error/latency trends.
  • Add a feedbackHook that routes to SLF4J/Logback for local debugging.
  • Ship logs in JSON to simplify correlation with the marketplace telemetry dashboard.

Custom data recipes

var client = context.getEndpoints().customData(projectId);
var response = client.list("com.example.crm.contacts", "automation_records", options -> {
    options.setFilters(Map.of("status", "active"));
    options.setLimit(50);
});

if (response.getData().isEmpty()) {
    client.create("com.example.crm.contacts", "automation_records", Map.of(
        "email", payload.get("primary_email"),
        "metadata", Map.of("source", "campaign")
    ));
}
  • Model schemas under .kiket/modules/<namespace>/schema.yml.
  • Use the CLI (kiket extensions modules validate) before publishing.

Upgrade strategy

  • Register v2 handlers alongside v1 and branch on context.getEventVersion().
  • Update the manifest version and publish a new tag; installations can opt in through the marketplace upgrade assistant.

Checklist

  • CLI lint/test/replay pass.
  • /health returns status: ok.
  • Telemetry visible under Admin → Marketplace → SDK Telemetry.
  • Secrets injected via env vars or Secret Manager.
  • Alerting (PagerDuty/Slack) connected to context.getEndpoints().notify.

References