Contexts in the Docker CLI provide a streamlined mechanism to interact with multiple Docker endpoints. You can set up contexts for each of your hosts and switch between them on the fly.

When a context is active, Docker will direct all of your commands to that host. If you mostly use a local Docker install but sometimes need to start containers in production, Docker contexts are one option available to you.

Any valid Docker endpoint can be turned into a context. You can wire up regular Docker Engine installs, Docker Swarm clusters, and Kubernetes clusters in the cloud. Each stored context contains all the connection information for the referenced host.

Creating a Context

Contexts are managed with the

        docker context
    

command. You create new contexts using docker context create. You must supply a name for your context as well as its endpoint configuration.

Here's how to create a context that connects to a Docker socket exposed over TCP on a remote host:

        docker context create remote-host --docker host=tcp:///my-remote-host:2735
    

Contexts use Docker Swarm as their default container orchestrator. You can explicitly set this using a flag:

        docker context create remote-host 
    --default-stack-orchestrator=swarm 
    --docker host=tcp:///my-remote-host:2735
    

To create a connection to Kubernetes, change the orchestrator type. You must also add the --kubernetes flag and specify the path to a Kubernetes configuration file:

        docker context create kubernetes-host 
    --default-stack-orchestrator=kubernetes 
    --kubernetes config-file=/home/username/.kube/config 
    --docker host=unix:///var/run/docker.sock
    

Selecting Contexts

The active context is switched using docker context use. Pass the name of the context that you want to activate.

        docker context use remote-host
    

All subsequent CLI commands will be executed using the endpoint given by the new context. The active context will automatically persist until you change it. To switch to a different context, run docker context use again. You can revert to the default context with your local Docker socket by passing default as the context name.

You can always override the selected context by adding the --context flag to any Docker command:

        docker run ubuntu:latest --context remote-host
    

The DOCKER_CONTEXT environment variable also functions as an alternative to the --context flag. Either mechanism facilitates a temporary switch to a different context without making you run and revert a docker context use command.

Using the DOCKER_HOST environment variable will override the active context, too. This variable forces Docker to use a particular daemon endpoint instead of the one provided by the context.

You can inspect the active context by running docker context ls. This command lists all the contexts available in your CLI configuration. The active context is highlighted with an asterisk. To delete a context, run docker context rm, supplying the context name. It's not possible to delete the default context.

Synchronizing Contexts between Machines

Context files are stored in your Docker CLI's configuration directory. This is usually $HOME/.docker on Linux. You'll find your contexts in the contexts subdirectory. Each context gets its own folder named with a unique hash. Inside, you'll find a meta.json file that describes the context. Only created contexts have files stored on-disk. The default context inherits the settings from your Docker daemon configuration.

If you want to synchronize context configuration, you can back up the contexts folder to move it to another machine. You could use an Rsync transfer or a Git repository to simplify regular updates. Symlinking the folder to a network share might also be an option depending on your requirements.

Docker lets you export and import contexts via the CLI, too:

        docker context export my-context
    

This will create a my-context.dockercontext file in your working directory. The file includes the meta.json contents as well as some extra information, such as the context's name. Transfer this file to another machine and run docker context import my-context.dockercontext to load the context configuration.

Alternatively, you can export a standalone Kubernetes configuration file for Kubernetes contexts:

        docker context export kubernetes-context --kubeconfig
    

This will produce a regular "kubeconfig" file compatible with Kubernetes ecosystem tools such as kubectl. The ability to acquire a kubeconfig file from a Docker context improves toolchain interoperability. Nothing within the file will be specific to the Docker CLI.

If you need to edit a context, use the docker context update command. This accepts the same flags as docker context create. If you're making bulk updates, you could edit the meta.json files to directly manipulate your contexts. You can inspect a context's meta.json file from the CLI with docker context inspect my-context.

Conclusion

Docker contexts are useful when you need to deploy containers in multiple independent environments. You can set up contexts for your local Docker socket, a shared team staging server, and your production Kubernetes server.

Docker has built-in support for the Microsoft Azure and Amazon ECS container clouds, which can be added as contexts, too. There's no limit on the number of contexts you can create, so you have good versatility as you move between your hosts.

Arguably the biggest functional issue with contexts is the possibility of accidentally running a command against the wrong context. If you've forgotten that you're in your production context, running docker rm database-container could have devastating consequences. If in doubt, run docker context ls first to check what you have selected.