The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Build a distroless image with a multi-stage Dockerfile: compile and test in a full builder stage, copy only the executable and required runtime files into a distroless final stage, then use docker buildx build to let BuildKit handle caching, multi-platform output and attestations. Choose the runtime family that matches your binary, run as a non-root user where possible, and keep a separate debug target instead of adding a shell to production.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
This guide answers how to build a distroless Docker image with BuildKit, how to make a multi-stage build smaller and safer, how to debug a distroless container with no shell, and how to create multi-platform images with buildx.
As an Amazon Associate I earn from qualifying purchases.
What a distroless BuildKit image contains
A distroless image is a runtime image deliberately stripped of interactive tools. It normally has no shell, package manager, compiler, or general-purpose command-line utilities. The final filesystem should contain the application, its configuration, certificates, time-zone data, shared libraries and other data files that the program actually needs—nothing more.
The usual design is a multi-stage build. A builder image contains the language toolchain and test tools. A later stage starts from a distroless runtime and copies in the build artifact. GoogleContainerTools’ distroless documentation describes this pattern as building application artifacts first and inserting them into the runtime image.
#1 Best Overall
- BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
- EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
- COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
- LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
- WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
Removing tools reduces what an attacker can use after a compromise and makes the runtime contents easier to inventory. It also removes the familiar recovery path of opening a shell in a running container. Build and operational procedures must therefore account for that trade-off rather than treating distroless as a drop-in replacement for a general Linux distribution.
Choose the correct distroless runtime family
Start with the binary’s linking model and runtime requirements. A small image is useful only when it can actually start and perform its work.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Runtime family | Use it when | Important checks |
|---|---|---|
static |
The executable is genuinely statically linked, such as a Go binary built with the appropriate settings. | Confirm that the program does not need dynamically loaded libraries, and add any required certificates or data files. |
base |
The application needs the compatible shared-library environment supplied by the base distroless runtime. | Check the binary’s libc and other library dependencies against the selected Debian release. |
cc |
A C or C++ application, or another dynamically linked program, needs the C/C++ runtime libraries. | Verify every required shared object and its architecture on each target platform. |
| Language-specific images | The language runtime itself must be present in the final container. | Use the tag that matches the application’s runtime and confirm its current release and supported architectures. |
:nonroot variants |
The service can run without root privileges. | Ensure files are readable by the selected user and that only explicitly required directories are writable. |
:debug variants |
You need a shell and diagnostic utilities temporarily. | Use the matching debug image or a dedicated debug stage; do not ship it as the production image merely for convenience. |
Tags and Debian releases change. Before pinning a tag in production, confirm that the language or runtime variant and Debian release are current for your deployment. A scratch-like runtime is not assumed to contain CA certificates, time-zone data or dynamic-linker support; select a compatible image or copy the required files deliberately.
Write the multi-stage Dockerfile
The following Go example follows the recommended separation between build and runtime. Adapt the builder, compilation command and runtime family to your application.
# syntax=docker/dockerfile:1
FROM golang:1.24 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /out/app ./cmd/app
FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=build /out/app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]Keep dependency downloads cacheable
Copy dependency manifests before copying the rest of the source tree. In the example, go mod download can remain cached when application files change but go.mod and go.sum do not. The later source copy and compile step then rebuild only when its inputs change.
Produce an artifact that matches the runtime
CGO_ENABLED=0 and GOOS=linux produce a Linux binary without the C library dependency for this Go example. That is why the static distroless family is appropriate here. If your program uses cgo, native extensions or another form of dynamic linking, do not copy this setting blindly: choose base, cc or a language-specific runtime and verify its libraries instead.
Rank #2
- WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
- AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
- PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
- ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
- COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
Copy runtime data explicitly
Applications that make TLS connections may need a CA certificate bundle. Programs that format local times may need time-zone data. Applications that load templates, migrations, translation catalogs or policy files need those files copied into the final stage as well. Treat each file as an explicit runtime dependency and test the image without access to the builder filesystem.
Set identity and startup behavior in the final stage
The :nonroot tag and USER nonroot:nonroot make the intended identity visible in the Dockerfile. Use an exec-form ENTRYPOINT so the application receives signals directly; there is no shell in the image to provide signal forwarding or command fallback.
Build the image with BuildKit and buildx
docker buildx build invokes BuildKit. BuildKit represents the Dockerfile as a build graph, can execute independent steps concurrently, skips stages that are not needed for the selected result, transfers only changed context data and reuses cache with more precision than the legacy builder.
Build and publish a multi-platform image
This command builds Linux images for both amd64 and arm64, stores cache in a registry, emits maximum-detail provenance and an SBOM, and pushes the resulting manifest and attestations.
Free tools Windows power users keep installed
One-click scans. No signup required.
docker buildx build
--platform linux/amd64,linux/arm64
--tag registry.example.com/acme/app:1.0.0
--cache-from type=registry,ref=registry.example.com/acme/app:buildcache
--cache-to type=registry,ref=registry.example.com/acme/app:buildcache,mode=max
--provenance=mode=max
--sbom=true
--push .Replace the registry and image name with your own. Registry output is important for a multi-platform result: BuildKit must publish each platform image and the manifest that points to them. The registry credentials used by the builder need permission to push both the image and its cache reference.
Build locally during development
For a local iteration loop, omit --push and select an output supported by the builder you are using. A multi-platform result cannot normally be loaded as one runnable local image in the same way as a single-platform build, so choose one platform for local execution or export an artifact in a format your workflow supports.
Rank #3
- Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
- Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
- Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
- ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
- Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
Select a stage deliberately
If the Dockerfile defines a named debug or test stage, select it with --target debug. This is useful for running tests or obtaining temporary diagnostics without changing the production stage. BuildKit can skip unrelated stages when a target is selected.
How to create multi-platform images with buildx
Use --platform linux/amd64,linux/arm64 (or the exact platform list you support) on the build command. Every compilation step must produce an executable for the target operating system and architecture. A build that succeeds on amd64 does not prove that a dynamically linked binary, native module or copied data file works on arm64.
Cross-compilation requirements
- Set the compiler’s target OS and architecture using the language’s supported mechanism.
- Ensure native dependencies are available for every target architecture; a cgo or C/C++ build may require target-specific toolchains or emulation.
- Use architecture-aware base images in both builder and runtime stages.
- Run a smoke test for each published platform, not just the platform on the CI worker.
Inspect the published manifest
After pushing, inspect the registry manifest with registry-aware tooling such as docker buildx imagetools inspect registry.example.com/acme/app:1.0.0. Confirm that every intended platform is listed and that the digest you deploy corresponds to the build you verified.
Use cache correctly in CI
BuildKit cache is separate from the final image. --cache-from type=registry,ref=… reads reusable layers from a registry reference, while --cache-to type=registry,ref=…,mode=max exports a broad cache, including intermediate results. A shared cache can reduce repeated dependency downloads and compilation work across CI runners, but it must be treated as disposable: a missing or evicted cache should make the build slower, not incorrect.
- Keep dependency manifests in an earlier Dockerfile layer than frequently changing source files.
- Use a stable cache reference for the branch or project policy, and ensure concurrent jobs do not unintentionally overwrite one another.
- Do not mistake a cache hit for a security review; rebuilds still need tests, scanning and attestation checks.
- Pin builder and runtime inputs according to your reproducibility policy, then update them deliberately.
Add provenance and SBOM attestations
BuildKit can attach supply-chain metadata to the build result. The --provenance=mode=max option requests detailed provenance, while --sbom=true requests an SBOM. Docker describes these as attestations attached to the build result rather than ordinary files inside the runtime filesystem.
BuildKit generates an SPDX JSON SBOM wrapped in an in-toto attestation. By default, the SBOM scan covers the final result. If you also need to account for files in the build context or intermediate stages, enable the documented scopes with environment variables:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #4
- Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
- Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
- 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
- Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
- USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC
BUILDKIT_SBOM_SCAN_CONTEXT=true
BUILDKIT_SBOM_SCAN_STAGE=trueSet these variables in the builder environment or CI configuration according to your BuildKit setup. Context and intermediate-stage coverage can reveal source or toolchain components that never enter production, which is useful for audit and license review but should not be confused with the contents of the shipped runtime image.
Verify metadata after publication
- Check that the registry shows the expected image digest and platform manifest.
- Use registry-aware attestation inspection to confirm provenance is attached to that digest.
- Confirm that the SBOM identifies the final image and, when requested, the intended context or stages.
- Record the builder version, source revision and build parameters in the release record used by your deployment process.
How do I debug a distroless container with no shell?
The absence of a shell is intentional. Running docker exec -it container sh against a production distroless image fails because sh is not present. Do not add a shell and package manager to the production stage just to make this command work; that changes the attack surface and the artifact you are trying to operate.
Use a matching debug variant
Distroless publishes :debug variants. Temporarily run the same application with the matching debug tag and override the entrypoint:
docker run --rm -it --entrypoint=sh gcr.io/distroless/static-debian13:debugUse the equivalent debug tag for the runtime family and Debian release used by your production image. Reproduce the startup command, environment, mounts and network conditions that matter, then discard the debug container. The debug image is a diagnostic tool, not the release artifact.
Define a dedicated debug or test target
A separate Dockerfile stage can include diagnostic utilities while sharing the same compiled artifact and configuration setup. Build it only when needed with --target debug. Keeping this target explicit prevents an accidental shell, compiler or package manager from leaking into the final stage.
Diagnose without entering the container
- Read the container’s stdout and stderr logs.
- Inspect the image configuration, entrypoint, user and environment with your container runtime.
- Run the application in a controlled debug target with the same read-only mounts, secrets and network policy.
- Check the image manifest and architecture when an executable fails before it can produce logs.
- Use health-check output and orchestrator events to distinguish startup failure from readiness failure.
Troubleshooting common failures
“Executable file not found” or an immediate startup exit
Verify the copied path, executable permission and CPU architecture. An architecture mismatch often presents as an execution error even when the file exists. For dynamically linked programs, also verify the ELF interpreter and every required shared library in the selected distroless family.
Best Value
- Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
- Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
- Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
- Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
- Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.
TLS connections fail inside the image
A minimal image may not include CA certificates. Select a runtime that supplies the needed certificate bundle or copy a deliberately managed bundle into the final stage. Test an actual TLS connection from the built image; a successful build does not prove certificate availability.
Local-time formatting is wrong
If the program needs named time zones, provide compatible time-zone data in the runtime image or use an application strategy that does not depend on host files. Test the zones your service actually serves.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →The process cannot write files
The non-root user should normally be unable to write arbitrary parts of the image. Identify the exact directories that must be writable, create or mount them explicitly, and assign ownership or permissions during the image build. Avoid switching the whole container back to root as a shortcut.
Health checks or graceful shutdowns do not work
Distroless images do not provide a shell for shell-form health checks or wrapper scripts. Use an executable health-check program or an orchestrator-level probe that can run without shell syntax. Ensure the exec-form entrypoint handles termination signals and closes connections before its grace period expires.
The cache is unexpectedly cold
Confirm that the CI job can read the exact --cache-from reference and that the previous job successfully exported --cache-to. Changes to dependency manifests, build arguments, base-image digests or relevant source files legitimately invalidate layers. Cache misses affect speed, not correctness.
The SBOM or provenance is missing
Check that the builder supports the requested attestations, that the command included --provenance and --sbom, and that the chosen output preserved metadata. For registry output, inspect the pushed digest rather than only a locally loaded image. If context or intermediate-stage coverage is expected, verify the corresponding BUILDKIT_SBOM_SCAN_CONTEXT and BUILDKIT_SBOM_SCAN_STAGE settings.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRootless and daemonless BuildKit in CI
BuildKit can run without a Docker daemon. This is useful in restricted CI environments where a privileged Docker socket is not acceptable. GitLab documents a rootless multi-platform pattern using moby/buildkit:rootless, buildctl-daemonless.sh and registry output.
In a rootless design, grant the job permission to read the source and push to the target registry, provide the platform and cache settings required by the pipeline, and keep the builder container unprivileged. Validate the exact runner, kernel and storage constraints in your CI environment; rootless operation changes how snapshotters, networking and credential forwarding are configured.
Verification checklist before release
- Build the final stage from the intended distroless runtime family and confirm the pinned tag or digest policy.
- Check that the final filesystem contains only the executable, required configuration, certificates, time-zone data and application data.
- Run as the non-root user when the application supports it.
- Test every platform in the published manifest, including dynamically linked binaries and native extensions.
- Exercise startup, health checks, signal handling, shutdown and restart behavior.
- Verify writable-directory requirements with a read-only root filesystem where your platform supports it.
- Keep a separate debug image or target and document who may use it and how it is discarded.
- Inspect the pushed manifest, provenance and SBOM attestations by digest.
- Record the source revision, builder inputs and release digest so the artifact can be reproduced or investigated later.
Distroless versus a general-purpose runtime: the real trade-offs
| Decision axis | Distroless with BuildKit | General-purpose runtime image |
|---|---|---|
| Runtime compatibility | Requires deliberate selection of libraries, certificates, data files and user permissions. | Usually includes a broader compatibility baseline and more utilities. |
| Attack surface and identity | Fewer tools are available after compromise, and non-root variants make least privilege explicit. | More packages and utilities increase the runtime inventory; root may be the default. |
| Debuggability | No interactive shell in production; use a matching debug variant or target. | Interactive troubleshooting is usually available immediately. |
| Supply-chain evidence | BuildKit can attach provenance and SPDX SBOM attestations, with configurable scan scope. | Attestations are still possible, but the larger runtime needs a broader inventory review. |
| Build and delivery performance | Multi-stage copying keeps the final result focused, while BuildKit’s graph solving and cache reduce repeated work. | Simpler Dockerfiles may be easier to begin with but can carry build tools and invalidate larger layers. |
There is no universal “smallest image” choice. The correct design is the smallest runtime that contains every verified dependency, runs under the intended identity and can be diagnosed through an approved workflow. Measure image size and build time for your own application rather than relying on an assumed percentage reduction.
Quick Recap
A practical release sequence
- List the executable, libraries, certificates, time-zone data, configuration and writable paths the service needs.
- Build and test the artifact in a full builder stage.
- Select
static,base,ccor a language-specific distroless runtime based on the artifact’s actual dependencies. - Create a minimal final stage, set the non-root identity where supported and use an exec-form entrypoint.
- Add a separate debug or test target rather than adding tools to production.
- Run
docker buildx buildwith the required platforms, registry cache, provenance and SBOM options. - Test each platform and inspect the pushed manifest and attestations.
- Deploy the verified digest, monitor health and shutdown behavior, and retain the debug procedure for incidents.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
