DEV Community: spmahapatra

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

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

5. Configure non-root Docker access deliberately

6. Verify Compose and Buildx

Working with Docker Daily

Debugging & Common Pitfalls

docker: permission denied

APT cannot find docker-ce

Docker service fails to start

Published ports bypass expected firewall rules

The server runs out of disk

FAQ

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

Can I run Docker without sudo?

Does installing Docker automatically start the daemon?

Is the convenience script better than the APT repository?

How do I completely uninstall Docker?

Installing Debian on WSL2 in Windows 11

Installing Debian on WSL2 in Windows 11

Key Takeaways

What Is WSL2?

The Mental Model

Prerequisites

Walkthrough

1. Install WSL2 and Debian

2. Launch Debian After Reboot

3. Launch Debian — Four Ways

4. Enable systemd

5. Update and Install Base Packages

6. Install Windows Terminal

7. Export a Backup Snapshot Before Installing Anything Else

Accessing Files Between Windows and Linux

WSL Command Reference

Advanced Configuration

Capping WSL2 Memory Usage

Mirrored Networking (Windows 11 23H2+)

Debugging & Common Pitfalls

Error: 0x80370102 — virtualization not enabled

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

systemctl reports "System is degraded"

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

FAQ

Can I run WSL2 on Windows 10?

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

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

`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?