Distroless images concept in Docker - Commands & Configuration

Introduction

Distroless images are minimal container images that contain only your application and its runtime dependencies, without any extra operating system tools or shells. This makes your containers smaller, faster to download, and more secure by reducing attack surface.

When you want to reduce the size of your container images to save bandwidth and storage.

When you want to improve container security by removing unnecessary tools and shells.

When you want to deploy applications with only the essential runtime libraries.

When you want faster startup times for your containers.

When you want to avoid accidental changes or debugging inside the container by removing shells.

Config File - Dockerfile

Dockerfile

FROM gcr.io/distroless/base
COPY my-app /my-app
CMD ["/my-app"]

FROM gcr.io/distroless/base: Uses the minimal distroless base image without a shell or package manager.

COPY my-app /my-app: Copies your compiled application binary into the image.

CMD ["/my-app"]: Sets the command to run your application when the container starts.

Commands

Builds the Docker image named 'my-app-distroless' using the Dockerfile in the current directory.

Terminal

docker build -t my-app-distroless .

Expected Output

Sending build context to Docker daemon  2.56MB

Step 1/3 : FROM gcr.io/distroless/base

 ---> 123abc456def

Step 2/3 : COPY my-app /my-app

 ---> Using cache

 ---> 789def012abc

Step 3/3 : CMD ["/my-app"]

 ---> Using cache

 ---> 456abc789def

Successfully built 456abc789def

Successfully tagged my-app-distroless:latest

Runs the 'my-app-distroless' container and removes it after it stops. This starts your application inside the minimal distroless image.

Terminal

docker run --rm my-app-distroless

Expected Output

Hello from my-app!

→

--rm - Automatically remove the container when it exits

Shows the size and details of the 'my-app-distroless' image to verify it is smaller than typical images.

Terminal

docker images my-app-distroless

Expected Output

REPOSITORY          TAG       IMAGE ID       CREATED         SIZE

my-app-distroless   latest    456abc789def   2 minutes ago   20MB

Key Concept

If you remember nothing else from this pattern, remember: distroless images include only what your app needs to run, making containers smaller and safer.

Common Mistakes

Trying to run shell commands inside a distroless container.

Distroless images do not include shells or package managers, so shell commands will fail.

Build and debug your app outside the container, then run it inside the distroless image without expecting shell access.

Using distroless images for apps that require interactive debugging or shell access.

You cannot open a shell or install tools inside distroless containers, which makes debugging inside the container impossible.

Use distroless images for production deployments and use full base images during development and debugging.

Summary

Build your app into a minimal distroless Docker image using a simple Dockerfile.

Run the container to start your app without extra OS tools or shells.

Check the image size to confirm it is smaller and more secure than typical images.