App-Team Getting Started

Choose a catalog image, generate a starter, build with the matching Dev image, and certify the app image before deployment. No Nix required.

Role boundary

Platform teams own the fork, Nix builds, release evidence, and catalog. Application teams use Docker, Podman, Kubernetes, Cosign, devcontainers, and the ClearCutt CLI.

Prove The CLI From A Clean Clone

Start with the committed fixture catalog. After your platform team publishes a catalog, replace the fixture path with that generated catalog directory.

git clone https://github.com/northcutted/clearcutt.git
cd clearcutt
go -C cli build -o ../clearcutt ./cmd/clearcutt

./clearcutt --catalog cli/internal/testdata/catalog list
./clearcutt --catalog cli/internal/testdata/catalog inspect java21-distroless
./clearcutt --catalog cli/internal/testdata/catalog verify image java21-distroless \
  --require-signature \
  --require-sbom \
  --require-provenance \
  --max-critical 0 \
  --max-high 3 \
  --allow-preview

Generate A Starter App

The starter includes a Dockerfile, devcontainer, certification policy, release workflow, and rebase workflow.

./clearcutt app template java --output examples/my-java-service --name my-java-service

Use The Dev Path

Use the matching Dev image for build tools. The first command is fixture-backed and prints a devcontainer; the container command needs Docker or Podman access to the configured dev image.

./clearcutt --catalog cli/internal/testdata/dev-catalog dev java21-distroless --devcontainer --print
./clearcutt --catalog cli/internal/testdata/dev-catalog dev java21-distroless --container --engine docker --command 'java -version'

Build And Certify

Certify the app image archive before deployment or admission.

docker build -t ghcr.io/acme/payments-api:1.0.0 examples/my-java-service
docker push ghcr.io/acme/payments-api:1.0.0
APP_DIGEST=$(docker buildx imagetools inspect ghcr.io/acme/payments-api:1.0.0 \
  --format '{{json .Manifest.Digest}}' | tr -d '"')
docker save ghcr.io/acme/payments-api:1.0.0 -o payments-api.tar

./clearcutt certify payments-api.tar \
  --base java21-distroless \
  --policy examples/my-java-service/certification-policy.yaml \
  --image-ref "ghcr.io/acme/payments-api@${APP_DIGEST}"

Use JSON exec form

Distroless has no shell. Use ENTRYPOINT ["java","-jar","/workspace/app.jar"], not shell form.

Keep tools in dev

Install and compile dependencies in the Dev stage, then copy only runtime artifacts into the final image.

Separate proof paths

Use verify image for catalog policy checks and registry-side commands for cryptographic evidence.

Open app lifecycle Browse catalog Audit evidence