Deploy with a JVM backend (Java / Kotlin)

This guide pairs the sidecar with a JVM service — Spring Boot, Ktor, Quarkus, Micronaut, plain servlet containers; the pattern is identical. It assumes you have a config bundle or a hand-written sidecar.yaml + token.

The sidecar is not a -javaagent

JVM developers often expect security tooling to attach as a -javaagent inside the JVM. The RingZero sidecar is deliberately not that: it’s a separate process/container next to your service. It never loads into your JVM, can’t affect startup time, GC, or classloading, and needs no changes to your JAVA_TOOL_OPTIONS. Nothing about your application’s deployment artifact changes.

Docker Compose

A typical Spring Boot service with the sidecar as a companion service:

compose.yaml

services:
  app:
    image: acme/acme-web:latest        # your Spring Boot / Ktor image
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: production

  ringzero-sidecar:
    image: ghcr.io/ringzero/sidecar:1
    restart: unless-stopped
    ports:
      - "7301:7301"                    # challenge listener — reachable at every (re)registration
    volumes:
      - ./ringzero-sidecar-config:/etc/ringzero:ro

The sidecar registers the host (the Compose machine), so one sidecar per machine is enough even if you run several JVM services on it.

Kubernetes

On Kubernetes, prefer gateway mode

For ClusterIP-only services (the common case) — and any private cluster — use gateway mode: sidecars dial an in-cluster Scan Gateway outbound, so there’s no ingress to arrange and none of the round-robin problem below. The direct-mode manifests here are for clusters whose pods or nodes are genuinely internet-reachable. In direct mode, a Service round-robins port 7301 to any pod, so for replicated workloads use the DaemonSet per-node pattern — see Kubernetes: direct mode.

The per-pod sidecar (suitable when each pod has its own reachable address):

Kubernetes 1.29+ (native sidecar)

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: acme-web
spec:
  replicas: 1
  selector:
    matchLabels: { app: acme-web }
  template:
    metadata:
      labels: { app: acme-web }
    spec:
      initContainers:
        - name: ringzero-sidecar
          image: ghcr.io/ringzero/sidecar:1
          restartPolicy: Always          # makes it a native sidecar
          ports:
            - containerPort: 7301
          volumeMounts:
            - name: ringzero-config
              mountPath: /etc/ringzero
              readOnly: true
          resources:
            requests: { cpu: 10m, memory: 16Mi }
            limits: { memory: 64Mi }
      containers:
        - name: app
          image: acme/acme-web:latest
          ports:
            - containerPort: 8080
      volumes:
        - name: ringzero-config
          secret:
            secretName: ringzero-sidecar

Older Kubernetes

deployment.yaml (fragment)

# identical, but the sidecar goes under `containers` instead of
# `initContainers` — it has no ordering guarantee relative to the app,
# which is fine: registration is independent of your app's lifecycle.
containers:
  - name: app
    image: acme/acme-web:latest
    ports:
      - containerPort: 8080
  - name: ringzero-sidecar
    image: ghcr.io/ringzero/sidecar:1
    ports:
      - containerPort: 7301
    volumeMounts:
      - name: ringzero-config
        mountPath: /etc/ringzero
        readOnly: true

Create the ringzero-sidecar Secret from your config bundle as shown in Automated setup. If the pod’s own address isn’t reachable from the internet, set challenge.advertise_address. Consider the hardening securityContext for the sidecar container.

Bare metal / VMs (systemd)

For JVM services deployed as jars/wars on VMs, run the sidecar binary as a systemd unit next to your service — the unit file and install steps are stack-independent. One sidecar per host covers every JVM (and non-JVM) service on it.

Verify

Same as any deployment: sidecar logs show host registered, Settings → Hosts lists the host as active (see the host lifecycle for what that buys you), and the health probe reports "registered": true. Troubleshooting lives in the manual setup guide.