Use StageX with OCI Runtimes

Target audience: Developers, Platform engineers Goal: Integrate StageX images with Docker, Podman, and Kubernetes.

Prerequisites

• Podman or Docker installed
• Access to docker.io/stagex (or quay.io/stagex mirror)
• kubectl and a cluster (for the Kubernetes section)
• Familiarity with basic OCI runtime commands

Pulling StageX Images

StageX publishes images to two registries. You can pull by digest to pin to an exact build, or by tag for release tracking.

# Pin by digest (fully reproducible)
podman pull docker.io/stagex/pallet-rust@sha256:2fbe7b164dd92edb9c1096152f6d27592d8a69b1b8eb2fc907b5fadea7d11668

# Tag by release date
podman pull docker.io/stagex/pallet-rust:sx20260501

# Rolling latest
podman pull quay.io/stagex/pallet-rust:latest

For detailed build and run instructions, see Quick Start.

Running Containers

=== "Podman"

# Interactive shell
podman run -it --rm stagex/stage3

# Python one-liner
podman run -it --rm stagex/pallet-python -c "print('hello from stagex')"

# Override entrypoint (pallet images default to cargo/gcc/python3/node)
podman run -it --rm --entrypoint "" stagex/pallet-rust /bin/sh

# Interactive shell
docker run -it --rm stagex/stage3

# Python one-liner
docker run -it --rm stagex/pallet-python -c "print('hello from stagex')"

# Override entrypoint (pallet images default to cargo/gcc/python3/node)
docker run -it --rm --entrypoint "" stagex/pallet-rust /bin/sh

Podman runs rootless by default (better security isolation); Docker runs as root unless configured otherwise. For production, consider --read-only to mount the container filesystem as read-only, preventing runtime modifications.

StageX images are built FROM scratch — they contain only the application binary and its runtime dependencies, with no shell or package manager unless you explicitly add them.

Command Comparison

Signature Verification per Runtime

StageX images carry GPG multi-signatures co-signed by at least two independent maintainers before publication.

• Podman — native support via policy.json. Configure signature verification in /etc/containers/policy.json (system-wide) or ~/.config/containers/policy.json (per-user). See Verify Multi-Signature Attestations for the complete setup.
• Docker — no native signature verification for image manifests. Use docker trust (Notary) for sign-and-push workflows, or verify GPG signatures manually as shown in Verifying Your First StageX Image.
• containerd / Kubernetes — use Ratify or Connaisseur for admission-time signature verification. Both support notation and cosign; configure them to require StageX GPG signatures.

Kubernetes Integration

StageX images integrate naturally with Kubernetes. Because they are built FROM scratch, they minimize attack surface — no shell, no package manager, no unnecessary binaries.

apiVersion: v1
kind: Pod
metadata:
  name: stagex-python-demo
spec:
  containers:
    - name: python
      image: docker.io/stagex/pallet-python:sx20260501
      command: ["python3", "-c", "print('hello from stagex')"]
      imagePullPolicy: IfNotPresent
      securityContext:
        readOnlyRootFilesystem: true
        runAsNonRoot: true
        allowPrivilegeEscalation: false
        capabilities:
          drop: ["ALL"]
  restartPolicy: Never

Best practices:

• Pin by digest in production (image: docker.io/stagex/pallet-rust@sha256:...). Use imagePullPolicy: IfNotPresent for release tags, Always for :latest.
• Set runAsNonRoot: true — StageX binaries are compiled as static position-independent executables and run safely under arbitrary UIDs.
• Admission control with Ratify or Connaisseur to enforce signature verification at deploy time. Both tools integrate with OCI registries and can reject unsigned or mismatched images.

Self-Hosted Registry Mirror

You can mirror StageX images to a private registry for air-gapped environments, bandwidth caching, or compliance.

# Mirror with skopeo (preserves digest references)
skopeo copy docker://docker.io/stagex/pallet-rust:latest \
          docker://registry.example.com/stagex/pallet-rust:latest

# Mirror with docker pull + tag + push
docker pull docker.io/stagex/pallet-rust:sx20260501
docker tag docker.io/stagex/pallet-rust:sx20260501 \
         registry.example.com/stagex/pallet-rust:sx20260501
docker push registry.example.com/stagex/pallet-rust:sx20260501

If you build from source (see Reproduce Builds Locally), the StageX Makefile provides registry-* targets that build and push directly to your registry:

make registry-pallet-rust \
  BUILDER="docker buildx" \
  REGISTRY_USERNAME=registry.example.com/stagex

The publish-* targets handle the full pipeline: OCI layout extraction, docker load, tagging (:version, :latest, :sx$(RELEASE)), and push to both docker.io/stagex and quay.io/stagex.

Troubleshooting

See Also

• Quick Start: Your First Reproducible Build
• Verify Multi-Signature Attestations
• Reproduce Builds Locally
• OCI-Native Package Management
• Verifying Your First StageX Image