Docker Contexts for Managing Remote Hosts

Docker contexts allow you to switch between multiple Docker hosts (local, remote servers, Swarm clusters) from a single CLI. Instead of SSH-ing into each server to manage containers, you can manage them all from your workstation. This guide covers setting up and using Docker contexts for multi-host management.

Understanding Contexts

# List existing contexts
docker context ls
# NAME       DESCRIPTION                DOCKER ENDPOINT              ORCHESTRATOR
# default *  Current DOCKER_HOST based   unix:///var/run/docker.sock  swarm

# Show current context
docker context show

Creating Contexts

# SSH-based context (recommended — uses SSH tunneling)
docker context create production \
    --docker "host=ssh://user@production-server.example.com"

docker context create staging \
    --docker "host=ssh://user@staging-server.example.com"

# TCP-based context (requires TLS)
docker context create remote-tls \
    --docker "host=tcp://remote-server:2376,ca=/path/ca.pem,cert=/path/cert.pem,key=/path/key.pem"

Using Contexts

# Switch active context
docker context use production

# All docker commands now run against the production server
docker ps
docker compose ps
docker service ls

# Switch back to local
docker context use default

# Run a single command against a specific context
docker --context production ps
docker --context staging logs web

# Or use environment variable
DOCKER_CONTEXT=production docker ps

Managing Multiple Servers

# Quick status check across all servers
for ctx in $(docker context ls --format "{{.Name}}"); do
    echo "=== $ctx ==="
    docker --context "$ctx" ps --format "table {{.Names}}\t{{.Status}}" 2>/dev/null
    echo
done

Docker Compose with Contexts

# Deploy to remote server
docker context use production
docker compose -f docker-compose.prod.yml up -d

# Or inline
docker --context production compose up -d

SSH Configuration

# For SSH contexts, configure SSH keys
# ~/.ssh/config
Host production-server.example.com
    User deploy
    IdentityFile ~/.ssh/deploy_key
    StrictHostKeyChecking accept-new

# Ensure Docker is installed on the remote server
# The remote user must have Docker socket access (docker group)

Context for Docker Swarm

# Create context for a Swarm manager
docker context create swarm-prod \
    --docker "host=ssh://admin@swarm-manager.example.com"

docker context use swarm-prod
docker node ls
docker service ls
docker stack deploy -c stack.yml myapp

Removing Contexts

docker context rm staging
docker context rm production

Best Practices

• Use SSH-based contexts — they are simpler and more secure than TCP+TLS
• Configure SSH keys with the deploy user to avoid password prompts
• Use descriptive context names that indicate the environment (staging, production, etc.)
• Be careful with the active context — always verify with docker context show before running destructive commands
• Use docker --context name for one-off commands to avoid accidentally switching contexts
• Set up bash/zsh prompt to show the current Docker context for safety