How to: Use Docker Remote Contexts with SSH

2025-10-10T00:00:00+00:00

The Problem: When Your Laptop Becomes a Jet Engine

Working on resource-intensive Docker projects often turns laptops into jet engines. The fans spin up, the CPU overheats, and performance degrades significantly. This is especially problematic when working with limited resources - lightweight laptops, VDI sessions, or simply wanting to preserve your hardware.

An SSH-based Docker context keeps the development tools on your local machine while running Docker workloads on a more capable remote host. Your laptop stays responsive and the remote system handles the heavier work.

Step 1: Prerequisites

Before we start, ensure you have:

SSH access configured to your remote Docker host with a proper SSH config entry like:

# ~/.ssh/config
Host docker-remote
  HostName 10.10.10.10
  IdentityFile ~/.ssh/id_rsa
  User ubuntu

Your user is in the docker group on the remote host:

sudo usermod -aG docker $USER

That's all the setup needed! Now let's create the Docker context.

Step 2: Create the SSH-Based Docker Context

Creating the Docker context is incredibly simple when you have SSH properly configured.

Create Your SSH-Based Remote Context

Create a new context using your SSH config host:

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

That's it! Docker will use your existing SSH configuration, including the hostname, user, and identity file you've already set up.

The beauty of this approach: No daemon.json changes, no TCP configuration, no port forwarding, no firewall rules, no TLS certificate generation - just leverage your existing SSH security infrastructure. Simple and elegant!

Check Your Current Contexts

First, let's see what contexts you currently have:

docker context ls

You'll probably see something like:

NAME              DESCRIPTION                               DOCKER ENDPOINT
default *         Current DOCKER_HOST based configuration   npipe:////./pipe/docker_engine
desktop-linux     Docker Desktop                            npipe:////./pipe/dockerDesktopLinuxEngine
desktop-windows   Docker Desktop                            npipe:////./pipe/dockerDesktopWindowsEngine
docker-remote                                               ssh://docker-remote

Test the Connection

Let's verify everything works:

docker --context docker-remote container ls

If you see your remote containers listed (or an empty list if none are running), congratulations! You're successfully connected to your remote Docker host via SSH.

Step 3: Make It Your Default (Optional)

If you want to use the remote context by default, you can switch to it:

docker context use docker-remote

Now all your docker commands will automatically use the remote host:

docker container ls
# This now runs on your remote host!

Environment Variable Override

For more granular control, you can also use the DOCKER_CONTEXT environment variable:

# Windows PowerShell
$env:DOCKER_CONTEXT = "docker-remote"

# Linux/macOS
export DOCKER_CONTEXT=docker-remote

This approach is particularly useful in CI/CD scenarios or when you want different shells to use different contexts.

Why SSH is Better

Using SSH for Docker remote contexts offers several advantages over TCP:

Security: All communication is encrypted by default
Authentication: Leverages existing SSH keys and authentication methods
No daemon configuration: No need to modify Docker daemon settings on the remote host
Firewall friendly: Uses standard SSH port (22)
Audit trail: SSH logging provides better security monitoring

Switching Between Contexts

Need to switch back to local Docker for something? Easy:

# List available contexts
docker context ls

# Switch to local Docker
docker context use default

# Or use a specific context for one command
docker --context default container ls

Bonus: PowerShell Function for Quick Context Switching

Here's a handy PowerShell function to make switching contexts even easier. Add this to your PowerShell profile for instant remote Docker activation:

Edit Your PowerShell Profile

First, open your PowerShell profile for editing:

notepad $PROFILE

If the file doesn't exist yet, PowerShell will ask if you want to create it - say yes.

Add the Function

Add this function to your profile:

function docker-remote-activate {
    $env:DOCKER_CONTEXT = "docker-remote"
    Write-Host "Docker context switched to remote host"
}

Replace "docker-remote" with whatever you named your remote context.

Save and Reload

Save the file and reload your PowerShell profile:

. $PROFILE

Usage

Now you can instantly activate remote Docker in any PowerShell session:

# Activate remote Docker for this session only
docker-remote-activate

# Now all Docker commands run remotely
docker ps
docker images
docker build .

The beauty of this approach is that it only affects the current PowerShell session - open a new terminal window and you're back to local Docker by default!

Global vs Terminal-Specific Context Switching

You have two ways to switch between local and remote Docker contexts:

Global Context Switching

Affects all terminals system-wide:

# Switch globally to remote
docker context use docker-remote

# Switch back to local
docker context use default

Terminal-Specific Context

Affects only the current terminal session:

# Terminal 1: Remote context
docker-remote-activate
docker ps  # runs remotely

# Terminal 2: Still local context  
docker ps  # runs locally

Whether you prefer global context switching or terminal-specific control, Docker remote contexts give you the flexibility to work exactly how you want.

Summary

Using SSH-based Docker remote contexts provides a secure, simple solution for offloading resource-intensive Docker operations to remote hosts. With just a single command and proper SSH configuration, you can transform your development workflow without compromising security.

The SSH approach eliminates the complexity of daemon configuration while providing enterprise-grade security through encrypted communication and existing authentication infrastructure.

Key Benefits:

Secure by default (encrypted communication)
No daemon configuration required
Uses standard SSH authentication
Works with existing SSH infrastructure
Simple one-command setup

References:

svnscha - docker