Developer Onboarding Guide

Start building hardened, supply-chain verified container images using the ClearCutt ecosystem in under 5 minutes.

ONBOARDING CLARITY CARD

Do I Need Nix?
No Nix Required.

Application developers do not need Nix installed. Pull, run, and verify published image matrices natively using standard OCI container runtimes (docker, podman, or Kubernetes). Nix is for platform engineers who fork the kit and customize the runtime fleet.

Create a Hardened Multi-Stage Containerfile

ClearCutt images are divided into functional matrix tiers. Developers use the dev tier as their compiler environment, then copy built application artifacts into slim or shell-free distroless runtime tiers:

Hardens JRE execution by removing JShell, package managers, and executing purely within the rootless unprivileged boundary:

# 1. Compiler Stage
FROM ghcr.io/northcutted/clearcutt/clearcutt-java25:dev-latest AS builder
WORKDIR /app
COPY . .
RUN ./gradlew bootJar --no-daemon

# 2. Execution Stage (hardened distroless runtime)
FROM ghcr.io/northcutted/clearcutt/clearcutt-java25:distroless-latest
WORKDIR /app
COPY --from=builder /app/build/libs/app.jar app.jar

# Enforces unprivileged execution natively. Execute JRE directly.
ENTRYPOINT ["java", "-jar", "app.jar"]

Uses virtual environment isolation inside the runtime container, discarding developer compilers and header files:

# 1. Builder Stage
FROM ghcr.io/northcutted/clearcutt/clearcutt-python3.14:dev-latest AS builder
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /opt/venv && \
    /opt/venv/bin/pip install --no-cache-dir -r requirements.txt

# 2. Runtime Stage (lean diagnostic slim runtime)
FROM ghcr.io/northcutted/clearcutt/clearcutt-python3.14:slim-latest
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
COPY . .
ENV PATH="/opt/venv/bin:$PATH"

ENTRYPOINT ["python", "main.py"]

Set Up the Local Governance CLI

Automate image validation, conformance audits, and supply chain policy checks locally inside your shell.

1. Compile and link to PATH

# Clone and build the binary
git clone https://github.com/northcutted/clearcutt.git
cd clearcutt
make cli-build

# Move to PATH for global access
chmod +x clearcutt
sudo mv clearcutt /usr/local/bin/clearcutt

2. Enforce local policies

Validate OIDC signatures and verify that active image vulnerability risks fall below your custom SLA limits:

clearcutt verify image java25-distroless \
  --require-signature \
  --require-sbom \
  --max-critical 0 \
  --max-high 3

3. Declarative down-stream OCI certification

Before uploading downstream applications, audit them offline to ensure compliance bounds (e.g. no dynamic package managers, no interactive shells):

# Save OCI image to archive
docker save my-app:latest -o my-app.tar

# Certify completely offline
clearcutt certify my-app.tar \
  --base java25-distroless \
  --policy certification-policy.yaml

4. Build rebasable app images

Assemble a prebuilt artifact onto a ClearCutt base, then rebase later from CI without recompiling the app layer:

clearcutt app build \
  --base java21-distroless \
  --artifact target/app.jar \
  --dest /workspace/app.jar \
  --entrypoint '["java","-jar","/workspace/app.jar"]' \
  --image ghcr.io/acme/payments-api:1.0.0

clearcutt app diff-base \
  --image ghcr.io/acme/payments-api:1.0.0 \
  --candidate-base java21-distroless

Rebase examples for every stack

Top 3 Developer Hardening Tips

1. Direct JSON syntax

Because distroless contains no shell, using a standard string execution like CMD "python main.py" will crash instantly. Always declare arguments as a JSON list: ENTRYPOINT ["python", "main.py"].

2. Pre-declare libraries

You cannot execute runtime commands like apt-get install or pip install inside production environments. Copy all compiled dynamic dependencies out of the dev compilation stage instead.

3. Local Audits

Run conformance audits offline with clearcutt conformance run --expect-runtime java to verify DNS, CA certificate chains, timezone mappings, and rootless sandboxes before deployment.