DEV Community: spmahapatra

Part 1.5: Optimizing Dockerfiles with Multi-Stage Builds

spmahapatra — Sun, 20 Sep 2026 00:18:37 +0000

Part 1.5: Optimizing Dockerfiles with Multi-Stage Builds

Key Takeaways

Platform engineers: Reduce base image sizes by 80% to 95% while enforcing zero-toolchain runtime environments across build pipelines.
SREs on-call: Eliminate KubeletHasDiskPressure node evictions and shorten deployment image pull times from minutes to seconds during autoscaling events.
First-timers: Start by separating your build-time SDKs from runtime binaries using named FROM statements before tuning BuildKit caching mounts.

What Is Multi-Stage Docker Builds?

Multi-stage Docker builds allow you to use multiple FROM statements in a single Dockerfile. Each FROM instruction starts a new build stage with a fresh environment, letting you copy artifacts directly from one stage to another while dropping unnecessary compilers, source files, and temporary tooling.

As of Docker 23.0 and BuildKit v0.11, multi-stage builds execute stages in parallel when dependencies permit, skipping unused stages entirely. Without multi-stage builds, shipping a Go, Rust, or Java application requires either carrying compiler toolchains directly into your execution environment or writing fragile host-level wrapper scripts to clean up files before layer commit.

The Mental Model

Why do single-stage Dockerfiles consistently inflate image size and expose unneeded system packages? Container images build as a series of read-only stackable layers. Deleting a tool in a later RUN command does not reduce the storage footprint of the finished image; the layer containing that tool remains baked into the image history.

Understanding where image bloat originates requires breaking down the container execution stack into distinct operational boundaries:

Build Toolchain & Compiler Layer — Compilers, C headers, git binaries, package managers (your build stage configuration).
Intermediate Artifact Layer — Compiled binaries, object files, dependency download caches (BuildKit engine / host engine storage).
Runtime Dependency Layer — Shared dynamic libraries (libc, musl), CA certificates, system users (your final stage configuration).
Container Runtime Engine Layer — Namespace isolation, cgroups, overlay2 copy-on-write storage driver execution (host OS kernel, out of your hands).

You control layers 1, 2, and 3. Single-stage images force layers 1, 2, and 3 into the final layer stack. Multi-stage builds decouple layer 1 and layer 2 into throwaway stages, pulling only layer 3 into the final image definition.

The Incident

At 03:14 UTC, two nodes in our primary Kubernetes cluster threw KubeletHasDiskPressure warnings. Within four minutes, three critical payment-gateway pods were evicted. Autoscaling attempted to launch replacement pods on surviving nodes, but the new pods stalled in ContainerCreating for 240 seconds.

The monitoring dashboard displayed the following event logs across the cluster:

03:18:12Z node-04 kubelet: WARNING: Disk usage on image filesystem is at 89%
03:19:01Z node-04 kubelet: ERROR: Failed to pull image "registry.internal/payment/api:v2.1.4": context deadline exceeded
03:19:05Z node-05 kubelet: INFO: Evicting pod payment-api-7db5c6c644-8x2ql due to disk pressure

Why did image pulling take four minutes per node pull? I checked the image manifest in our internal registry and found the payment/api:v2.1.4 image measured 1.85 GB.

I spent the first hour convinced our private registry proxy was bandwidth-throttled by cloud egress rules. It was not. I inspected the image layers using docker history and discovered the build shipped the entire Go SDK, GCC compiler, standard header files, git repository history, and npm cache directly into runtime.

CREATED BY                                      SIZE
/bin/sh -c apt-get update && apt-get install…   642MB
/bin/sh -c go build -o /app/server .            480MB
COPY dir:a83b12... in /src                      720MB

Why were we shipping 1.84 GB of build infrastructure to serve a single 22 MB statically compiled binary?

Honestly, I find Go's default static linking flags annoying because -ldflags="-w -s" should be standard in every pipeline template, but engineers keep omitting it. The team had relied on a single-stage Dockerfile based on golang:1.21 without stripping debug symbols or separating the build toolchain from the execution image.

Prerequisites

Docker Engine 20.10.0+ or Docker Desktop 4.0+ with BuildKit enabled (DOCKER_BUILDKIT=1).
Basic familiarity with Docker CLI flags and container layer concepts.
[VERIFY: docker buildx version] returns BuildKit engine active.

Walkthrough

1. Audit image bloat and layer inventory

Before rewriting your build definition, establish a baseline size and inspect which directives introduce unnecessary byte overhead.

# Build the legacy single-stage image
docker build -t app:legacy -f Dockerfile.legacy .

# Inspect total size
docker image ls app:legacy

# Analyze layer breakdown
docker history app:legacy --format "table {{.ID}}\t{{.Size}}\t{{.CreatedBy}}"

What to verify:

Confirm the total size and identify whether package managers (apt, apk), compilers (gcc, go), or source trees account for more than 50% of the total footprint.

docker inspect app:legacy --format='{{.Size}}'

2. Isolate compilation dependencies using build stages

Define a distinct compilation stage using a named FROM clause. Allocate all heavy dependencies, header packages, and build scripts exclusively to this phase.

Create a new Dockerfile:

# Stage 1: Build workspace
FROM golang:1.22-bookworm AS builder

WORKDIR /build

# Copy dependency manifests first to leverage layer caching
COPY go.mod go.sum ./
RUN go mod download

# Copy source code and compile binary
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /build/bin/server .

What to verify:

Verify that building only the intermediate stage succeeds without creating runtime side effects.

docker build --target builder -t app:builder-only .
docker image ls app:builder-only

3. Extract minimal binary targets into runtime images

Add a second FROM instruction targeting a minimal base image like debian:bookworm-slim, alpine, or gcr.io/distroless/static-debian12. Copy only the compiled binary from the builder stage using COPY --from.

# Stage 1: Build workspace
FROM golang:1.22-bookworm AS builder

WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /build/bin/server .

# Stage 2: Minimal Execution Runtime
FROM gcr.io/distroless/static-debian12:nonroot

WORKDIR /app

# Copy executable from builder stage
COPY --from=builder /build/bin/server /app/server

# Expose port and configure non-root runtime environment
EXPOSE 8080
USER 65532:65532

ENTRYPOINT ["/app/server"]

What to verify:

Run the new multi-stage build and compare the final image size against app:legacy.

docker build -t app:optimized .
docker image ls | grep -E "app\s+(legacy|optimized)"

The output must show a dramatic reduction in size (for Go applications, usually dropping from ~1 GB to under 30 MB):

REPOSITORY   TAG         IMAGE ID       CREATED          SIZE
app          legacy      d3f2a1b4c5e6   10 minutes ago   1.85GB
app          optimized   a1b2c3d4e5f6   2 minutes ago    28.4MB

4. Optimize BuildKit cache mounts across workflow stages

While multi-stage builds shrink image size, re-downloading package caches on every build slows pipeline execution speed. Use BuildKit --mount=type=cache options to persist dependency directories across stages without saving those directories into image layers.

Modify the builder stage in your Dockerfile:

FROM golang:1.22-bookworm AS builder

WORKDIR /build

COPY go.mod go.sum ./

# Mount Go module cache and build cache directories
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

COPY . .

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /build/bin/server .

FROM gcr.io/distroless/static-debian12:nonroot
WORKDIR /app
COPY --from=builder /build/bin/server /app/server
USER 65532:65532
ENTRYPOINT ["/app/server"]

Fast path — Build using BuildKit enabled inline:

DOCKER_BUILDKIT=1 docker build -t app:optimized-cached .

Manual path — build engine explicit export command if default context fails:

docker buildx build --output type=docker -t app:optimized-cached .

What to verify:

Execute two sequential builds and check the time delta on the second run.

time docker build -t app:optimized-cached .

The second run should complete in under two seconds due to BuildKit cache target hits.

Decision Framework

Selecting the right base image strategy for your final runtime stage introduces specific trade-offs between attack surface, debugging convenience, and POSIX compliance.

Base Image Strategy	Final Image Footprint	Package Manager Available	Vulnerability Exposure (CVEs)	Debugging Capabilities	Primary Use Case
Full OS Base (`debian:bookworm`, `ubuntu:22.04`)	100 MB - 800 MB	Yes (`apt`)	High (100+ standard packages)	High (shell, curl, gdb present)	Complex legacy applications needing dynamic C libraries
Minimal OS Base (`alpine:3.19`)	5 MB - 15 MB	Yes (`apk`)	Low (fewer system packages)	Moderate (busybox shell present)	Applications requiring POSIX utilities but low disk usage
Distroless (`distroless/static-debian12`)	2 MB - 20 MB	No	Minimal (no shell or package tools)	Low (requires ephemeral debug containers)	Security-critical services with static binaries
Scratch (`scratch`)	0 MB (empty layer)	No	Zero OS-level CVEs	None (no shell or tools)	Purely static binaries (`Go`, `Rust`) with self-contained assets

Increasing security by stripping out shells (distroless/scratch) means your operational debugging workflow changes: you cannot docker exec -it container sh into a failing instance. You must rely on telemetry, distributed tracing, or ephemeral debug sidecars instead.

Command Reference

Command	Operational Purpose
`docker build --target <stage_name> -t img .`	Build up to a specific intermediate stage for debugging or testing.
`docker buildx build --cache-from type=gha --cache-to type=gha,mode=max .`	Enable inline GitHub Actions caching for multi-stage BuildKit execution.
`docker history --no-trunc <image_id>`	Display full un-truncated layer commands to identify layer bloat source.
`docker builder prune --filter type=exec.cachemount`	Clear persistent BuildKit cache mounts from local storage.
`docker build --build-arg BUILDKIT_INLINE_CACHE=1 -t img .`	Embed BuildKit cache metadata directly inside exported registry images.

Debugging & Common Pitfalls

Missing CA certificates in `scratch` base images

When porting a Go or Rust application from alpine or debian to scratch, outgoing HTTPS requests fail immediately upon startup.

2024/03/15 10:22:41 Error fetching upstream API: Get "https://api.stripe.com/v1/charges": x509: certificate signed by unknown authority

The scratch image is entirely empty. It contains no root TLS certificates in /etc/ssl/certs/ca-certificates.crt.

Copy the certificate bundle from your builder stage into your final stage:

FROM golang:1.22-bookworm AS builder
RUN apt-get update && apt-get install -y ca-certificates update-ca-certificates

FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /build/bin/server /app/server
ENTRYPOINT ["/app/server"]

Invalidated layer caching from incorrect directive order

Every COPY or RUN statement invalidates the cache for all subsequent lines if the source files change. Placing COPY . . at the top of a multi-stage Dockerfile causes go mod download or npm install to run on every line modification, ruining CI pipeline speed.

# BAD: Invalidates package cache on any source file edit
COPY . .
RUN go mod download

Separate dependency declarations from source files:

# GOOD: Only re-downloads dependencies when manifests change
COPY go.mod go.sum ./
RUN go mod download
COPY . .

Dynamic C library resolution failure (`glibc` vs `musl`)

A binary compiled on a standard Linux builder stage fails to execute in an Alpine runtime stage.

exec /app/server: no such file or directory

The path /app/server exists, but the dynamic linker loader specified inside the ELF binary header (typically /lib64/ld-linux-x86-64.so.2 from glibc) is absent in Alpine (musl-based).

You have two choices to fix this execution error:

Compile a fully static binary in your build stage:

   RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o /app/server .

Switch your builder or runtime image so both use identical standard libraries (e.g., compile on golang:alpine if deploying to alpine).

References

Docker Documentation: Use multi-stage builds
Open Container Initiative: OCI Image Format Specification v1.0.1
Google Container Tools: Distroless Container Images Specification

FAQ

Does BuildKit automatically skip unused build stages?

BuildKit analyzes the target stage specified in your build invocation and builds a dependency graph. If a stage in your Dockerfile is not referenced by the final stage or by a COPY --from instruction, BuildKit completely skips the execution of that stage's commands.

How do I debug runtime errors when my target image lacks a shell?

You cannot attach a bash shell to scratch or distroless containers directly. In Kubernetes 1.23+, use kubectl debug to attach an ephemeral container containing diagnostic tools (busybox or nicolaka/netshoot) to the running pod's process namespace:

kubectl debug -it <pod-name> --image=cgr.dev/chainguard/busybox --target=<container-name>

For local Docker testing, build a dedicated debug image target by adding a temporary stage ending in FROM alpine or FROM debian:slim.

Can I copy artifacts from an existing external Docker image instead of a local stage?

Pass the target image directly into the --from flag of a COPY instruction. You do not need to write a pre-stage FROM line to pull isolated assets from third-party tools.

# Copy the official HashiCorp Vault binary directly into your runtime image
COPY --from=hashicorp/vault:1.15.2 /bin/vault /usr/local/bin/vault

Will multi-stage builds slow down CI/CD pipelines due to cache hits failing across ephemeral runners?

Ephemeral CI runners start with fresh Docker daemon storage, causing local layer caches to miss on every pipeline run. Mitigate this by exporting inline BuildKit build caches directly to your container registry using --cache-to=type=registry and --cache-from=type=registry flags during the docker buildx build execution step.

Part 1 Dockerising and Standardising Compose

spmahapatra — Sat, 19 Sep 2026 23:42:12 +0000

Part 1: Dockerising and Standardising Compose

Navigation: Part 2: Caching API Calls Efficiently →

How to start building a sample app along with use of different DevOps tools

Welcome to the team! If you are a new developer joining us, this series is your definitive onboarding guide. We are taking a raw application and scaling it to enterprise standards.

Here is our published journey:

Docker Compose Standardisation (This post) — Enforcing strict local environments.
App Creation & Caching (See Part 2) — Building the Flask app and using Redis to solve data latency.
Enterprise ELK Logging (See Part 3) — Structured JSON logs for observability.
Full-Cycle CI/CD (See Part 4) — Shifting CI left to reduce costs.

Key Takeaways

Platform engineers: Standardise Compose setups across your repositories. Use the Compose Specification schema. Remove the version key and add a name at the top level to stop cross-repo namespace clashes.

SREs on-call: Stop silent cross-environment pollution and database corruption. This usually happens when local containers inherit shell exports instead of strict .env fallbacks.

First-timers: Start by splitting your configuration into two distinct layers: Data vs. Architecture.

Data (.env): Injects raw strings and secrets (e.g. DB_PASSWORD). Keep this developer-managed and never commit it.
Architecture (docker-compose.override.yml): Overrides base container physics for local dev (mapping ports to your host, mounting live ./src folders). Keep this repo-managed and always commit it to version control. Keep the base docker-compose.yml strictly for production-ready topologies.

What Is Dockerising and Standardising Compose?

We often see teams using ad-hoc docker-compose.yml files. Standardising means we stop doing this. We replace them with a unified format using Compose V2. Instead of relying on custom wrapper scripts or raw docker run commands, we agree on a strict structure for our services, volumes, and networks.

As of July 2023, Docker Compose V1 (written in Python) reached End-of-Life (EOL). We must now rely on Compose V2 (written in Go), which natively reads the Compose Specification. Under this specification, the top-level version is deprecated, and project identity is set by the root name field, not the folder name. If you skip this, you will face non-deterministic container naming and silent variable overrides across developer machines and CI/CD agents.

The Mental Model

When a developer runs docker compose up, it doesn't just run a simple script. It parses and resolves your configuration through four layers.

Repository Configuration — .env files, shell exports (what you control)
Compose Engine — YAML parsing, variable expansion, inheritance (your local CLI)
Docker Engine API — Translates YAML into API calls (your host daemon)
Host Kernel — cgroup and network allocation (host OS)

If two developers run docker compose up on the same commit but get different results, where did it break? Not at the Engine or Kernel. It broke at the Repository Configuration layer. Unvalidated environment variables mutated the setup before a single API call reached the daemon.

The Incident

At 14:22 UTC, I received a critical page: CRITICAL - DB_STAGING_MUTATION_ALERT. Staging database records were mutating, causing broken foreign keys.

I checked the staging database audit logs immediately.

2023-11-14 14:21:03 UTC [18402]: [3-1] user=app_dev,db=staging_db LOG:  STATEMENT:  TRUNCATE TABLE users CASCADE;

A local developer was running integration tests, thinking they were using a local database. Instead, their local app connected to our staging database over the corporate VPN and ran a destructive migration.

Why did this happen? It was a variable cascade bleed. The developer's project relied on an implicit .env file without a fallback for DATABASE_HOST. Because the developer had previously exported DATABASE_HOST=db-staging.internal.net in their shell session, the local docker compose up silently inherited it.

The trade-off is clear: fixing this requires tight environment file rules and explicit boundaries for every local stack. I spent two days clearing doubts with developers who insisted "it worked fine on my machine", before I finally set up a CI linter to reject unstandardised Compose files.

Prerequisites

Docker Engine: Version 24.0.0 or higher. Precheck your host version using docker version --format '{{.Server.Version}}'.
Docker Compose: Version 2.20.0 or higher (docker compose version).
Assumed Knowledge: Familiarity with container networking and Linux processes.

Walkthrough

1. Precheck legacy configurations and remove deprecated attributes

Inspect the repository for legacy Docker Compose formats. Older files use top-level version keys (like version: '3.8'). This ignores modern features.

Run this command to find all YAML files with the deprecated version attribute:

find . -maxdepth 3 -type f \( -name "docker-compose*.yml" -o -name "docker-compose*.yaml" \) \
  -exec grep -Hn "^version:" {} +

Remove the version field from all files. Replace it with an explicit name attribute in your primary file. This ensures container and volume names are properly scoped.

# Standardised Compose Specification Format
name: core-platform-services

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "${HOST_PORT:-8080}:8080"
    environment:
      - NODE_ENV=${NODE_ENV:-development}
      - DATABASE_URL=${DATABASE_URL:?Doubts: DATABASE_URL must be explicitly provided}
    networks:
      - internal_net

networks:
  internal_net:
    driver: bridge

Verification:

Validate that Compose parses the file without throwing schema errors:

docker compose config --quiet && echo "Schema is valid."

2. Establish a multi-file split

To prevent local settings from leaking into staging, separate the base topology from environment overrides. Use docker-compose.yml for shared definitions and docker-compose.override.yml for developer-specific local mounts.

Create the base docker-compose.yml:

name: billing-system

services:
  app:
    image: registry.internal.net/billing/app:v2.4.1
    restart: unless-stopped
    environment:
      - APP_PORT=3000
    networks:
      - app_bus

Create the local development override file docker-compose.override.yml. Docker Compose automatically merges this file when you run docker compose up:

services:
  app:
    build:
      context: .
      target: dev
    ports:
      - "3000:3000"
    volumes:
      - .:/usr/src/app

Verification:

Verify how Compose merges these files locally:

docker compose config

Verify that the output contains both the base service definition and the local volume mounts.

3. Implement strict environment variable validation

Unset shell variables can cause dangerous fallbacks. Use standard Compose syntax to enforce required variables.

Syntax ${VAR:-default} uses default if VAR is empty.
Syntax ${VAR:?error_message} stops execution if VAR is empty.

First, create a sample .env.example file that developers can copy to .env. This file must point to local dummy credentials, ensuring they never connect to staging by mistake.

# .env.example
# Copy this file to .env before running docker compose up

# Application Environment
NODE_ENV=development

# Database Connection (Hardcoded to local dummy container, NOT staging)
DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_USER=local_dummy_user
DATABASE_PASSWORD=local_dummy_pass

Next, enforce required variable checks inside your services block in docker-compose.yml:

services:
  worker:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD:?Fatal error: REDIS_PASSWORD is missing.}

Verification:

Test that Compose throws an explicit error when executing without required variables:

env -i docker compose config

Real-World Example

You can see a complete, working implementation of these standards in our Rick & Morty API repository.
Check out the split between docker-compose.yml, docker-compose.override.yml, and .env.example to see how we safely expose local ports without compromising the base production configuration.

Debugging & Common Pitfalls

Silent Environment Variable Overrides

Symptom:

Services connect to unintended host ports or external services, bypassing .env values.

Root Cause:

Compose resolves variables using this precedence:

Shell variables set in the active terminal
Environment variables set in .env
Default values in the docker-compose.yml

If a developer exports PORT=9000 in their shell, Compose will use 9000, silently ignoring PORT=3000 inside .env.

Fix:

Clear ambient environment variables before invoking Compose:

env -i HOME="$HOME" PATH="$PATH" docker compose up -d

Volume Namespace Bleed Across Repositories

Symptom:

Spinning up an application in Repository B overwrites persistent data in database volumes created by Repository A.

Root Cause:

Both repositories define generic volume keys like volumes: db_data: without setting a root name attribute. Compose defaults to the current parent directory name. If both projects are inside directories named app/, they will share the exact same volume namespace.

Fix:

Explicitly assign a unique top-level name in every repository's docker-compose.yml.

FAQ

Why should I delete the top-level `version` line?

The version field enforced legacy schema constraints (like '3.8'). Modern Compose V2 automatically detects capabilities based on the target Docker Engine. Including a version string now triggers deprecation warnings and can cause Compose to ignore modern attributes.

Can I run `docker-compose` (with a hyphen) in modern CI pipelines?

You should not rely on docker-compose anymore. The standalone Python binary reached End-of-Life in July 2023. Modern pipelines must use docker compose (space separated), which uses the Go-based plugin integrated into the Docker CLI.

Installing Minikube on Debian

spmahapatra — Sun, 23 Aug 2026 22:59:01 +0000

Installing Minikube on Debian

Minikube is a practical way to run a small Kubernetes cluster on a Debian workstation or development instance. This guide installs Minikube with the Docker driver, starts a named profile, runs a temporary deployment, and removes the test resources afterward.

This is a local development setup, not a production Kubernetes distribution. The commands target Debian 12 (Bookworm), Debian 13 (Trixie), or a compatible newer Debian release on an x86-64 host.

The goal is a repeatable local baseline rather than a particular Minikube release number. Minikube and Kubernetes change over time, so the release documentation remains the authority for supported versions and driver behavior. The commands deliberately verify each boundary: the Debian host, Docker, the Minikube profile, the Kubernetes node, and a real workload. That makes a later failure easier to classify. For example, a failed docker run is a runtime problem, while a successful Docker test followed by a failed rollout belongs in the cluster or workload layer.

Run the commands as the same non-root user who will use Minikube afterward. Mixing sudo minikube with normal-user commands creates separate configuration and cache locations, which can make a healthy cluster appear to be missing. Keeping one user and one named profile throughout the walkthrough avoids that confusing split.

Key Takeaways

You will have a Docker-backed Minikube profile named local-kube-cluster.
Reserve at least 2 CPUs, 4 GiB of memory, and 20 GiB of free disk space for a comfortable first run.
The Docker driver avoids a second virtual machine, but it still needs a working Docker daemon and permission to access it.

What Is Minikube?

Minikube runs a single-node Kubernetes cluster locally so you can develop manifests, test controllers, and follow tutorials without provisioning a remote cluster. The Docker driver runs the node inside a container managed by Docker.

The driver is the important choice: Minikube manages the Kubernetes node, while Docker provides the container runtime and host-level isolation. If either layer is unhealthy, Kubernetes startup errors can be misleading.

The Mental Model

Think of the installation as four independent checks:

Host capacity: the machine has enough CPU, memory, disk, and network access.
Container runtime: Docker is installed, running, and usable by the current user.
Cluster profile: Minikube creates and stores a named cluster configuration. A profile can retain a driver choice and resource settings from an earlier attempt.
Kubernetes workload: a Ready node only proves the control plane started. A deployment and service smoke test proves that the cluster can schedule a workload and expose it through the selected driver.

This model also explains the safest troubleshooting order: check the host first, then Docker, then the Minikube profile, and only then the Kubernetes workload.

Prerequisites

Debian 12, Debian 13, or a compatible newer Debian release
x86-64 Linux, unless you download the matching Minikube architecture binary
A non-root user with sudo access
At least 2 CPUs, 4 GiB RAM, and 20 GiB of free disk space
Outbound access to Debian, Docker, Kubernetes, and Minikube download endpoints
systemd available if you want Docker managed as a system service

Walkthrough

1. Confirm the Debian host has enough capacity

Update the package index, install the utilities used by the setup, and inspect the resources before downloading anything.

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl gnupg lsb-release

nproc
free -h
sudo df -h /

Do not continue with the default profile if the host has fewer than 2 CPUs or less than 4 GiB of usable memory. A cluster can technically start with less, but image pulls and system pods will compete for the same constrained resources.

2. Install and verify Docker Engine

Before continuing, install Docker Engine by following the dedicated Install Docker Engine on Debian guide. It uses Docker's official APT repository and covers conflicting packages, repository key configuration, daemon access, firewall considerations, and cleanup.

After Docker is installed, verify it as the same user who will run Minikube:

sudo systemctl enable --now docker
sudo systemctl is-active docker
docker version
docker run --rm hello-world

If docker version reports a permission error, follow the non-root access and new-login-session instructions in the Docker guide. The Docker group grants root-equivalent control over the host, so only trusted users should receive this access.

3. Install the Minikube binary

Download the latest stable x86-64 Linux binary from Minikube's official release location and install it in /usr/local/bin:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install -o root -g root -m 0755 minikube-linux-amd64 /usr/local/bin/minikube
rm minikube-linux-amd64

Verify the installation and make Docker the default driver:

minikube version
minikube config set driver docker

For ARM64, download the matching binary from the Minikube releases page instead of the x86-64 file above.

4. Install kubectl locally

Install the latest stable x86-64 kubectl binary, verify its SHA-256 checksum, and move it into /usr/local/bin:

set -e
KUBECTL_VERSION="$(curl -fsSL https://dl.k8s.io/release/stable.txt)"
curl -LO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
curl -fLO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl kubectl.sha256

Verify the local client:

kubectl version --client

The commands above target x86-64 Linux. For an ARM64 host, replace amd64 in both download URLs with arm64.

Keep the client and cluster lifecycle separate. kubectl is the command-line client installed on the Debian host, while Minikube owns the local cluster and its certificates. Starting the profile writes or updates a context in the current user's kubeconfig. After activating local-kube-cluster, kubectl uses that active context by default. Run kubectl config get-contexts if you need to inspect available contexts.

5. Start a Docker-backed cluster profile

Create a named profile with explicit resources. Naming the profile makes it possible to inspect, stop, and delete this cluster without affecting another Minikube profile.

minikube start \
  --profile=local-kube-cluster \
  --driver=docker \
  --memory=4096 \
  --cpus=2

Make the named profile active, then check both the Minikube state and the Kubernetes node:

minikube profile local-kube-cluster
minikube status --profile=local-kube-cluster
minikube profile
kubectl config current-context
kubectl get nodes
kubectl get pods --all-namespaces

The minikube profile command should now print local-kube-cluster, and kubectl config current-context should show the same context. The profile should report Running, one node should report Ready, and system pods may need a short time to settle during the first image pull.

6. Run and remove a Kubernetes smoke test

Create a temporary deployment, expose it as a NodePort service, and wait for the rollout:

kubectl create deployment minikube-smoke \
  --image=kicbase/echo-server:1.0
kubectl expose deployment minikube-smoke \
  --type=NodePort --port=8080
kubectl rollout status deployment/minikube-smoke \
  --timeout=120s
kubectl get deployment,service,pods

Ask Minikube for a URL to the service:

minikube service minikube-smoke --profile=local-kube-cluster --url

Remove the temporary objects after the test:

kubectl delete service minikube-smoke
kubectl delete deployment minikube-smoke

Debugging & Common Pitfalls

Docker permission denied

If Docker works with sudo but not as your normal user, the current shell has not picked up the new group membership. Run groups and id -nG, start a new login session, and retry docker run --rm hello-world.

Insufficient resources

Check free -h, nproc, and df -h /. Stop competing workloads or increase the instance size before changing Kubernetes settings. Reducing memory can make the cluster appear to start while leaving system pods unable to schedule reliably.

Profile uses the wrong driver

Profiles retain configuration. Inspect existing profiles and recreate the named profile if it was previously started with another driver:

minikube profile list
minikube delete --profile=local-kube-cluster
minikube start --profile=local-kube-cluster --driver=docker --memory=4096 --cpus=2

Startup fails behind a proxy

Image pulls and package downloads need network access from both the host and Docker. Configure the proxy according to your environment, then inspect the profile diagnostics:

minikube logs --profile=local-kube-cluster
minikube status --profile=local-kube-cluster

A failed start leaves stale resources

Delete the profile and retry only after checking the logs. Repeating minikube start without removing a partially created profile can preserve the original driver or resource settings.

FAQ

Is Minikube suitable for production?

No. Minikube is designed for local development, learning, and repeatable experiments. Use a production-oriented Kubernetes distribution or managed service when you need high availability, durable operations, and multi-node failure handling.

Why install standalone kubectl?

The standalone client provides the normal Kubernetes workflow and can switch among contexts with kubectl config get-contexts. Installing it once also keeps the commands in this guide consistent with other Kubernetes tools and scripts. Minikube still manages the cluster and writes the local-kube-cluster context into your kubeconfig.

Why use the Docker driver on Debian?

It is usually the simplest option when Docker is already part of the development workflow. It avoids managing a second virtual machine, though it still consumes host CPU, memory, disk, and Docker daemon resources.

What should I do when the profile is no longer needed?

Stop it to retain its downloaded data and configuration:

minikube stop --profile=local-kube-cluster

Delete it to remove the profile and its resources:

minikube delete --profile=local-kube-cluster

Install Docker Engine on Debian

spmahapatra — Sun, 23 Aug 2026 22:59:00 +0000

Install Docker Engine on Debian

Docker Engine provides the daemon, CLI, and runtime needed to build and run containers on Debian. This guide installs Docker Engine from Docker's official APT repository, verifies the service with a test container, and configures the current user to run Docker without sudo.

The repository method is preferable for a long-lived Debian instance because APT can receive Docker updates through the normal package workflow. Docker currently documents Debian 13 (Trixie), Debian 12 (Bookworm), and Debian 11 (Bullseye), with packages for amd64, armhf, arm64, and ppc64el. Package names and supported releases can change, so the official Docker Debian installation page remains the authority when this article is updated.

Key Takeaways

Install Docker Engine from Docker's signed APT repository rather than mixing distribution packages with Docker packages.
Test the daemon with docker run hello-world before configuring applications or Kubernetes tools.
Membership in the docker group grants root-equivalent access to the host. Add only trusted users, or keep using sudo.

What Is Docker Engine?

Docker Engine is the host-side service that builds images, stores container data, creates networks, and starts containers. The Docker CLI sends requests to that service through its local socket. Installing the CLI alone does not provide a working container runtime.

The installation has three separate concerns: repository trust, package installation, and daemon access. The repository's signing key lets APT verify Docker packages. The packages install the daemon and related plugins. The Unix socket controls which users can ask that daemon to perform privileged operations.

The Mental Model

Treat the setup as a chain of checks:

Operating system: confirm the Debian release and architecture are supported.
Conflicting packages: remove unofficial packages that can provide overlapping commands or incompatible runtime dependencies.
APT trust: install Docker's keyring and repository definition with readable, explicit permissions.
Engine service: install the daemon, CLI, containerd, Buildx, and Compose plugins, then confirm the service is active.
User access: decide whether commands should use sudo, Docker-group membership, or rootless mode.
Network policy: review firewall behavior before publishing container ports.

A successful docker version proves that the CLI can reach the daemon. A successful docker run hello-world proves that the daemon can pull an image, create a container, start it, and report its output. Run both checks; they catch different failures.

The Incident

On a new Debian instance, I once treated Docker installation as a single package command and moved directly to a Kubernetes setup. The package installation completed, but the normal user could not access the Docker socket, so Minikube reported a driver failure that looked like a Kubernetes problem. I spent time checking cluster settings before checking docker run. The real fix was a new login session after changing group membership. The lesson was simple: validate Docker as the exact user and shell that will run the next tool.

Prerequisites

Debian 11, 12, or 13 on a supported architecture
A non-root user with sudo access
Outbound HTTPS access to Debian mirrors and download.docker.com
A terminal session on the target Debian instance
A firewall plan if containers will publish ports outside the host

Before installing, identify the release and architecture:

. /etc/os-release
printf 'Debian release: %s\n' "$VERSION_ID"
printf 'Codename: %s\n' "$VERSION_CODENAME"
dpkg --print-architecture

Walkthrough

1. Remove conflicting Docker packages

Debian may provide packages such as docker.io, while other tools may install containerd or runc separately. Docker's official packages bundle compatible runtime dependencies. Remove conflicting packages if they are present:

sudo apt remove -y docker.io docker-compose docker-doc docker-buildx podman-docker containerd runc

APT may report that some packages are not installed. This command does not remove Docker's stored images, containers, volumes, or networks. Existing data may still be present under /var/lib/docker and /var/lib/containerd.

2. Configure Docker's signed APT repository

Install the keyring directory and Docker's official signing key, then create a deb822 repository definition. The architecture expression prevents APT from selecting packages for a different architecture.

If Docker was previously configured with an older .list file, remove that duplicate source before adding the .sources definition below. Keeping two entries for the same repository with different signing keys makes APT stop with a Conflicting values set for option Signed-By error. This removes repository configuration only; it does not remove Docker packages or container data.

sudo rm -f /etc/apt/sources.list.d/docker.list

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Refresh package metadata and confirm Docker packages are visible:

sudo apt update
apt list --all-versions docker-ce 2>/dev/null | sed -n '1,5p'

On Debian testing or a derivative distribution, VERSION_CODENAME may not match a Docker repository suite. Check the official documentation before substituting the corresponding Debian codename.

3. Install Docker Engine and its standard plugins

Install the engine, command-line client, containerd, Buildx, and Compose plugin:

sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Check that the service is active and that the client can reach it:

sudo systemctl is-active docker
sudo docker version
sudo docker info

On a normal Debian installation, Docker starts with the service installation. If it is inactive, start it and inspect the service status:

sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

4. Verify the installation with a test container

Run Docker's small verification image:

sudo docker run --rm hello-world

The command downloads the image if necessary, creates a temporary container, prints a confirmation message, and removes the container because of --rm. A failure here should be resolved before installing Minikube, Compose applications, or other Docker-dependent tooling.

5. Configure non-root Docker access deliberately

The simplest access model is to prefix Docker commands with sudo. If the instance is trusted and the workflow requires normal-user commands, add the current user to the Docker group:

sudo usermod -aG docker "$USER"

Start a new login session so the shell receives the new group membership. Then verify the exact user path:

id -nG
docker version
docker run --rm hello-world

Do not use sudo docker as a substitute for refreshing the session when testing group access. The root and non-root clients can use different configuration files and caches, which makes troubleshooting harder.

The Docker group is not equivalent to an ordinary application group. A user who can control the Docker daemon can generally gain root-level access to the host. Use the group only for trusted administrators, or investigate Docker's documented rootless mode when that privilege boundary matters.

6. Verify Compose and Buildx

The installation includes the modern Compose and Buildx plugins. Confirm both are available:

docker compose version
docker buildx version

These are plugin commands, so docker-compose and an old standalone docker-buildx command are not required for the documented workflow. Existing scripts may need updating if they depend on legacy command names.

Working with Docker Daily

Useful commands for a new instance include:

Command	What it does
`docker ps`	List running containers
`docker ps -a`	List running and stopped containers
`docker images`	List locally stored images
`docker logs <container>`	Read container output
`docker exec -it <container> sh`	Open a shell in a running container
`docker inspect <container>`	Show low-level container configuration
`docker system df`	Show Docker disk usage
`docker compose up -d`	Start a Compose application in the background

Keep the daemon healthy with systemctl is-active docker and monitor disk usage. Images, writable layers, build cache, and container logs can fill a small instance even when few containers are running.

Debugging & Common Pitfalls

`docker: permission denied`

The daemon may be healthy while the current user lacks permission to access /var/run/docker.sock. Check the service, socket ownership, and active groups:

sudo systemctl is-active docker
ls -l /var/run/docker.sock
id -nG

Use sudo docker ..., or start a new login session after usermod -aG docker "$USER". Avoid changing the socket to world-writable permissions.

APT cannot find `docker-ce`

The Docker repository may be missing, the codename may be wrong, or sudo apt update may have failed. Inspect the source definition and run the update again:

cat /etc/apt/sources.list.d/docker.sources
sudo apt update

On supported Debian releases, the Suites value should correspond to the Debian codename. Do not blindly use stable as the suite; stable belongs in Components.

Docker service fails to start

Read the service log before reinstalling packages:

sudo systemctl status docker --no-pager
sudo journalctl -u docker.service -n 100 --no-pager

Look for storage-driver, dependency, disk, or network errors. A previous installation may have left incompatible runtime packages or configuration under /etc/docker.

Published ports bypass expected firewall rules

Docker warns that ports published with -p can bypass rules managed by ufw or firewalld. Docker is compatible with iptables-nft and iptables-legacy; rules created only with unsupported native nftables workflows may not behave as expected. Review Docker's firewall documentation and place filtering rules in the DOCKER-USER chain where appropriate before exposing services.

The server runs out of disk

Inspect Docker's usage before deleting anything:

docker system df
sudo du -sh /var/lib/docker /var/lib/containerd

Remove only resources you understand. docker system prune can remove stopped containers, unused networks, dangling images, and build cache; adding --volumes can remove unused data volumes and should be treated as a destructive operation.

FAQ

Should I install `docker.io` or `docker-ce` on Debian?

Use Docker's official packages when you want Docker's documented Engine release stream: docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin. Do not mix the distribution's docker.io package with those packages without checking the resulting dependency and upgrade behavior.

Can I run Docker without `sudo`?

Yes, but adding a user to the Docker group grants root-equivalent control over the host. A new login session is required after changing membership. Keeping sudo is simpler for a tightly controlled administrative workflow; rootless mode is another option when its limitations fit the workload.

Does installing Docker automatically start the daemon?

Docker's Debian package normally starts the service. Verify with sudo systemctl is-active docker, and use sudo systemctl enable --now docker if the service is inactive or is not enabled for boot.

Is the convenience script better than the APT repository?

The convenience script is useful for disposable development environments and automation experiments, but it provides less control over repository setup and package choices. The APT repository is the better default for a Debian instance that will be maintained over time.

How do I completely uninstall Docker?

First remove the packages:

sudo apt purge -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras

Then remove the repository definition and key if they are no longer needed:

sudo rm -f /etc/apt/sources.list.d/docker.sources
sudo rm -f /etc/apt/keyrings/docker.asc

Images, containers, volumes, and custom configuration are not automatically removed by package removal. Delete /var/lib/docker and /var/lib/containerd only after confirming that all required data has been backed up or discarded.

Installing Debian on WSL2 in Windows 11

spmahapatra — Sat, 25 Apr 2026 23:14:06 +0000

Installing Debian on WSL2 in Windows 11

Key Takeaways

WSL2 with Debian gives you a full Linux kernel and systemd support — a legitimate CI parity environment on Windows hardware without running a separate VM.
Take a snapshot with wsl --export before installing any project tooling (Step 7). It's a one-minute operation that has saved me multiple full reinstalls.
Steps 1–5 get you a working Debian environment with systemd. Steps 6–7 (Windows Terminal, snapshot) are worth doing the same session.

What Is WSL2?

WSL2 (Windows Subsystem for Linux 2) ships a real Linux kernel inside a lightweight Hyper-V virtual machine. Unlike WSL1, which translated Linux syscalls into Windows calls, WSL2 runs an actual Linux kernel — meaning full syscall compatibility, systemd, and eBPF all work without a separate VM.

As of Windows 11 22H2, WSL2 supports systemd natively with no workarounds, persistent background services, and GPU passthrough via CUDA on supported hardware. This makes it the first Windows-native environment where you can run production-parity workloads alongside your Windows desktop.

The Mental Model

WSL2 runs inside a single lightweight Hyper-V VM (the "WSL2 utility VM"). Each installed distro is a separate filesystem image (ext4.vhdx) running inside that VM. The VM boots once; all distros share the kernel.

The Windows filesystem (C:\) is mounted at /mnt/c/ — I/O across this boundary is slow. Keep project files in ~/ (inside the distro), not in /mnt/c/Users/...
wsl.exe is your control plane: install, unregister, export, import, and configure distros from PowerShell. Think of it as docker but for Linux distros.
Networking is NAT'd by default: WSL2 gets its own IP that changes on reboot. Windows 11 23H2+ adds a mirrored networking mode that eliminates this.

Prerequisites

Windows 11 (Build 22000 or later — verify with winver)
PowerShell running as Administrator
Virtualization enabled in BIOS (check Task Manager → Performance → CPU → "Virtualization: Enabled")
4 GB free disk space minimum; 10 GB recommended for a comfortable base install

Walkthrough

1. Install WSL2 and Debian

Open PowerShell as Administrator (right-click Start → Terminal (Admin)).

Fast path — works on most Windows 11 machines:

wsl --install -d Debian

This enables the WSL feature, sets version 2 as default, and installs Debian. Once the install finishes, a Debian terminal opens automatically and prompts you to create a user account:

Enter new UNIX username: yourname
New password:
Retype new password:
passwd: password updated successfully

The password won't display as you type — that's normal. Once done, close the Debian window and reboot:

Restart-Computer

Warning: The Microsoft Store's Debian package ships a patched /init that silently breaks systemd — services you enable will appear to succeed but never start. Use wsl --install above, not the Store app, if you need reliable service management.

Manual path — use this if wsl --install errors out:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl --set-default-version 2

Reboot to activate the hypervisor, then after restart run wsl --install -d Debian again — the username/password prompt will appear automatically when install completes.

2. Launch Debian After Reboot

After rebooting, Debian won't open automatically. Launch it from PowerShell:

wsl -d Debian

You should land at your user prompt:

yourname@MACHINE-NAME:~$

What to verify: Launch it from PowerShell:

wsl --status
# Default Version: 2
# Kernel version: 5.15.x or higher

wsl -l -v
# NAME      STATE     VERSION
# Debian    Running   2

If VERSION shows 1, force the upgrade:

wsl --set-version Debian 2

3. Launch Debian — Four Ways

After first-launch setup, Debian won't automatically open on future reboots. Pick whichever method fits your workflow:

From PowerShell or CMD (fastest):

wsl -d Debian

Or just wsl if Debian is your default distro.

From the Start menu:
Search for Debian — it appears as an app. Pin it to your taskbar for one-click access.

From Windows Terminal:
Click the + dropdown tab arrow → select Debian. Each click opens a new tab in your existing terminal window.

From any File Explorer folder:
Right-click inside a folder → Open Linux shell here (Windows 11 with Terminal installed). Opens a Debian shell with that folder already set as the working directory — useful when you want to run Linux tools on Windows files.

Tip: If you get dropped into a root shell instead of your user account, check that [user] default=yourname is set in /etc/wsl.conf (Step 4 covers this).

4. Enable systemd

Inside your Debian terminal:

sudo tee /etc/wsl.conf > /dev/null <<'EOF'
[boot]
systemd=true

[user]
default=your_unix_username
EOF

Restart WSL from PowerShell, then re-enter the distro:

wsl --shutdown
wsl -d Debian

What to verify:

systemctl --no-pager status
# State: running
# (NOT "System is degraded" — if degraded, run: systemctl --failed)

5. Update and Install Base Packages

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  curl wget git build-essential \
  ca-certificates gnupg lsb-release \
  htop tmux jq unzip

sudo timedatectl set-timezone America/New_York   # adjust to your zone

What to verify:

timedatectl
# Local time: ...
# System clock synchronized: yes

6. Install Windows Terminal

WSL2 works in the default console but Windows Terminal is significantly better — tabs, split panes, per-distro profiles, and proper font rendering for tools like tmux and htop.

winget install Microsoft.WindowsTerminal

Or install from the Microsoft Store. Once installed, open it and your Debian distro will already appear as a profile in the + dropdown — no configuration needed.

What to verify:

Open Windows Terminal → click the + dropdown → confirm Debian appears as a profile. Select it — you should land at your Debian user prompt, not a root shell.

7. Export a Backup Snapshot Before Installing Anything Else

Before you install project-specific tooling, export a clean snapshot.

# In PowerShell — create the backup directory first
New-Item -ItemType Directory -Force -Path C:\wsl-backups
wsl --export Debian C:\wsl-backups\debian-clean.tar

To restore from backup:

wsl --unregister Debian
wsl --import Debian C:\WSL\Debian C:\wsl-backups\debian-clean.tar --version 2

What to verify:

wsl -d Debian -e whoami
# Should print your username, not root

Accessing Files Between Windows and Linux

This trips up almost every first-timer. WSL2 runs in its own filesystem, but both sides can reach each other.

From inside Debian — access Windows files:

ls /mnt/c/Users/YourWindowsUsername/

Your Windows drives are mounted under /mnt/.

Warning: I/O across this boundary is 10–30× slower than native Linux I/O. Never run npm install, git clone, or heavy build operations on files under /mnt/c/ — always keep project files in ~/ inside the distro.

From Windows Explorer — browse your Linux filesystem:

Type this path directly in the Explorer address bar:

\\wsl$\Debian

This opens your Debian home directory in Windows Explorer. You can drag, copy, and edit files here as if they were Windows files.

Shortcut — open current Linux folder in Explorer:

explorer.exe .

Run this from any directory inside WSL2 and it opens that exact folder in Windows Explorer. Useful for accessing build artifacts from your IDE.

WSL Command Reference

Command	What it does
`wsl --install -d Debian`	Install a specific distro
`wsl --list --online`	Show all available distros
`wsl -l -v`	List installed distros with version and state
`wsl --shutdown`	Stop all running WSL instances
`wsl --update`	Update the WSL kernel
`wsl -d Debian`	Launch a specific distro by name
`wsl --export Debian file.tar`	Export distro to a backup file
`wsl --import Debian path file.tar`	Restore distro from backup
`wsl --unregister Debian`	Remove a distro (destructive — backup first)
`wsl --set-version Debian 2`	Convert an existing distro to WSL2

Advanced Configuration

These settings are optional — apply them once your base Debian environment is working.

Capping WSL2 Memory Usage

The Hyper-V VM holds memory it has used even after processes exit. Without a cap it can consume several GB that Windows never reclaims. Create C:\Users\YourName\.wslconfig:

[wsl2]
memory=4GB
processors=4
swap=2GB

Apply with wsl --shutdown. Verify inside Debian: free -h should show the capped total.

Mirrored Networking (Windows 11 23H2+)

By default, WSL2 uses NAT and gets a dynamic IP that changes on reboot. Mirrored mode gives WSL2 the same IP as your Windows host — services are reachable from your LAN without port-forwarding rules.

Add to C:\Users\YourName\.wslconfig:

[wsl2]
networkingMode=mirrored

Apply with wsl --shutdown. Verify inside Debian: ip addr should show your Windows LAN IP.

Debugging & Common Pitfalls

`Error: 0x80370102` — virtualization not enabled

This is the most common error on first install. Reboot into BIOS/UEFI and enable Intel VT-x (Intel CPUs) or AMD-V (AMD CPUs). It's usually under Advanced → CPU Configuration. Some corporate laptops have this locked by IT policy.

Distro stuck at "Installing" with 0% progress after reboot

Two common causes:

Virtual Machine Platform not enabled — rerun Step 1 and reboot.
Microsoft Store pending update — open the Microsoft Store, check for pending updates, let them finish, then try again. The Debian app itself sometimes needs to complete a Store update before first launch.

Inspect the event log for the underlying error:

Get-WinEvent -LogName Microsoft-Windows-Hyper-V-Guest-Drivers/Admin -MaxEvents 20

systemctl reports "System is degraded"

Run systemctl --failed to see which units failed. Three common WSL2-specific culprits that are safe to mask:

sudo systemctl mask multipathd.service      # storage multipath — not applicable in WSL2
sudo systemctl mask systemd-remount-fs.service  # WSL2 filesystem quirk
sudo systemctl mask apparmor.service        # WSL2 kernel has no AppArmor modules

`wsl --install` says WSL is already installed but nothing works

Run wsl --update to make sure the kernel is current, then wsl --shutdown and try again:

wsl --update
wsl --shutdown
wsl -d Debian

If the distro still won't launch, check its status: wsl -l -v. If STATE shows "Stopped" and it won't start, export it for backup, unregister, and re-import from your backup snapshot (Step 7, Export a Backup Snapshot).

FAQ

Can I run WSL2 on Windows 10?

Yes — WSL2 is available on Windows 10 version 1903 (Build 18362) and later. However, native systemd support requires Windows 11 22H2 or Windows 10 Build 22000+. On older Windows 10 builds you need the genie or distrod workaround to get systemd running. Everything else in this guide works as written.

My WSL2 distro is slow when accessing files under `/mnt/c/`. Is this normal?

That slowness is real and it doesn't go away. Cross-filesystem I/O crosses a virtual filesystem boundary — Linux talking to a Windows-hosted NTFS volume through a translation layer. Always keep active project files inside the Linux distro filesystem (~/projects/), not under /mnt/c/Users/.... The gap can be 10–30× on large file operations like npm install or git clone.

How do I access my WSL2 Debian from another machine on my LAN?

By default, WSL2 uses NAT and is not directly accessible from the LAN. Three options: (1) Windows port forwarding — netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=$(wsl hostname -I). (2) Switch to mirrored networking in .wslconfig under [wsl2] — available on Windows 11 23H2+ and gives WSL2 the same IP as your Windows host. (3) Expose services via a reverse proxy like Caddy running inside the distro, bound to 0.0.0.0.

DEV Community: spmahapatra

Part 1.5: Optimizing Dockerfiles with Multi-Stage Builds

Part 1.5: Optimizing Dockerfiles with Multi-Stage Builds

Key Takeaways

What Is Multi-Stage Docker Builds?

The Mental Model

The Incident

Prerequisites

Walkthrough

1. Audit image bloat and layer inventory

2. Isolate compilation dependencies using build stages

3. Extract minimal binary targets into runtime images

4. Optimize BuildKit cache mounts across workflow stages

Decision Framework

Command Reference

Debugging & Common Pitfalls

Missing CA certificates in scratch base images

Invalidated layer caching from incorrect directive order

Dynamic C library resolution failure (glibc vs musl)

References

FAQ

Does BuildKit automatically skip unused build stages?

How do I debug runtime errors when my target image lacks a shell?

Can I copy artifacts from an existing external Docker image instead of a local stage?

Will multi-stage builds slow down CI/CD pipelines due to cache hits failing across ephemeral runners?

Part 1 Dockerising and Standardising Compose

Part 1: Dockerising and Standardising Compose

How to start building a sample app along with use of different DevOps tools

Key Takeaways

What Is Dockerising and Standardising Compose?

The Mental Model

The Incident

Prerequisites

Walkthrough

1. Precheck legacy configurations and remove deprecated attributes

2. Establish a multi-file split

3. Implement strict environment variable validation

Real-World Example

Debugging & Common Pitfalls

Silent Environment Variable Overrides

Volume Namespace Bleed Across Repositories

FAQ

Why should I delete the top-level version line?

Can I run docker-compose (with a hyphen) in modern CI pipelines?

Installing Minikube on Debian

Installing Minikube on Debian

Key Takeaways

What Is Minikube?

The Mental Model

Prerequisites

Walkthrough

1. Confirm the Debian host has enough capacity

2. Install and verify Docker Engine

3. Install the Minikube binary

4. Install kubectl locally

5. Start a Docker-backed cluster profile

6. Run and remove a Kubernetes smoke test

Debugging & Common Pitfalls

Docker permission denied

Insufficient resources

Profile uses the wrong driver

Startup fails behind a proxy

A failed start leaves stale resources

FAQ

Is Minikube suitable for production?

Why install standalone kubectl?

Why use the Docker driver on Debian?

What should I do when the profile is no longer needed?

Install Docker Engine on Debian

Install Docker Engine on Debian

Key Takeaways

What Is Docker Engine?

The Mental Model

The Incident

Prerequisites

Walkthrough

1. Remove conflicting Docker packages

2. Configure Docker's signed APT repository

3. Install Docker Engine and its standard plugins

4. Verify the installation with a test container

Missing CA certificates in `scratch` base images

Dynamic C library resolution failure (`glibc` vs `musl`)

Why should I delete the top-level `version` line?

Can I run `docker-compose` (with a hyphen) in modern CI pipelines?

`docker: permission denied`

APT cannot find `docker-ce`

Should I install `docker.io` or `docker-ce` on Debian?

Can I run Docker without `sudo`?

`Error: 0x80370102` — virtualization not enabled

`wsl --install` says WSL is already installed but nothing works

My WSL2 distro is slow when accessing files under `/mnt/c/`. Is this normal?