Evaggelos Balaskas - System Engineer

Introduction

If you work with Docker long enough, you stop having one Docker environment.

• You have your local laptop.
• You have a remote VM or homelab server.
• You might have a staging host, a production host, or a CI runner somewhere in the cloud.

And sooner or later, you start asking yourself:

“Wait… where am I running this container?”

Docker contexts exist to solve exactly this problem—cleanly, safely, and without shell hacks.

This blog post explains what Docker contexts are, how they work in practice, and how to use them effectively based on real-world usage.

What Is a Docker Context?

At a practical level, a Docker context is:

• A named configuration
• That defines how the Docker CLI connects to a Docker Engine
• And optionally includes credentials and TLS/SSH details

When you run any Docker command, the CLI:

1. Resolves the active context
2. Reads its endpoint configuration
3. Talks to the corresponding Docker Engine

What a Context Contains (Practically)

A context can define:

• Local Unix socket (/var/run/docker.sock)
• Remote Docker over SSH
• Remote Docker over TCP + TLS
• Cloud-managed Docker endpoints

Internally, contexts are stored under:

~/.docker/contexts/

You almost never need to touch this manually—and that’s a good thing.

Practical Example: Local Laptop → Remote Docker Host over SSH

From your home PC, you want to manage Docker running on a remote machine called remote-vps.

Disclaimer: You need to have an ssh connection already set in ~/.ssh/config or via tailscale

Creating a Context

docker context create remote-vps --docker "host=ssh://remote-vps"

That’s it.

No SSH tunnel scripts.
No DOCKER_HOST exports.
No wrapper functions.

Listing Contexts

docker context ls

Output (trimmed):

NAME         DESCRIPTION                               DOCKER ENDPOINT
default   *  Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
remote-vps                                             ssh://remote-vps

The * indicates the currently active context.

Switching Contexts

docker context use remote-vps

From this point on, every Docker command runs against the Docker Engine on remote-vps.

This includes:

• docker ps
• docker images
• docker stats
• docker compose

No mental gymnastics required.

Real-World Usage: Observing a Remote Host

Once the context is active, normal commands “just work” out of the box.

Containers and Images

docker ps     -a
docker images -a

or even compose

❯ docker compose ls
NAME                STATUS              CONFIG FILES
traefik             running(9)          /opt/services/traefik/docker-compose.yml

You are now inspecting the remote host—not your laptop.

Live Resource Usage

docker stats --no-stream

Example output:

NAME          CPU %     MEM USAGE / LIMIT
wiki          0.01%     14.16MiB / 3.825GiB
mariadb       0.10%     83.74MiB / 3.825GiB
traefik       0.00%     42.62MiB / 3.825GiB

This is extremely useful when:

• You want quick visibility without SSHing in
• You’re comparing resource usage across environments
• You’re debugging “why is this host slow?”

Example: Deploying a Service via Docker Compose

With the remote-vps context active, you can deploy services remotely using Compose as if they were local.

Example: running Dozzle (Docker log viewer).

docker-compose.yaml

services:
  dozzle:
    image: amir20/dozzle:latest
    container_name: dozzle
    hostname: dozzle
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 8083:8080

Be Aware: I’ve changed the port to 8083 for this example.

Deploying

docker compose -v up

The image is pulled on the remote host, the container runs on the remote host, and port 8083 is exposed there.

No SCP.
No SSH shell.
No surprises.

Common Mistake

• Forgetting the Active Context !

This is the most common mistake.

Run this often:

docker context ls

Better yet: configure your shell prompt to show the active context.

Best Practices from Real Usage

• Use one context per environment (local, staging, prod)
• Name contexts clearly (prod-eu, homelab, ci-runner)
• Avoid running destructive commands without checking context
• Treat contexts as infrastructure, not convenience hacks
• Combine with read-only SSH users for production when possible

That’s it !

• Evaggelos Balaskas