Create a Docker Context with docker context create

Typing ssh and docker into the wrong terminal is how staging tests end up on production, and docker context create is the tidy way out. You will end with a named context pointing at the engine you chose, plus checks that show what it holds before you use it.

The examples use Docker CLI 29.8.1 from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes.

• You need: the Docker CLI, plus a local Unix socket, an SSH account on a host running Docker, or the TLS files and endpoint for a secured daemon.
• Privileges: creating a context is an ordinary user operation. Reaching the engine may need membership of the Docker socket group, SSH access or suitable certificate permissions. Do not use sudo unless your local Docker setup specifically requires it.

1. Check the command you have

Start with the installed help output. This reads local command metadata and does not contact a Docker daemon:

$ docker --version
Docker version 29.8.1, build 4a63305

$ docker context create --help
Usage:  docker context create [OPTIONS] CONTEXT

Create a context

The command takes one context name and these options:

• --description is a free-text label.
• --docker describes the endpoint. Its recognised fields are host, ca, cert, key and skip-tls-verify.
• --from copies the Docker endpoint configuration from an existing named context.

$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT
default *                                             unix:///var/run/docker.sock

2. Create a context for a local socket

For a local daemon, pass the socket as a Docker endpoint. This example creates a separate name without selecting it:

$ docker context create \
    --description "Local engine for testing" \
    --docker host=unix:///var/run/docker.sock \
    local-test
local-test
Successfully created context "local-test"

Use the exact socket path your host exposes. /var/run/docker.sock and /run/docker.sock commonly refer to the same location, but do not assume that on a customised installation.

The context stores endpoint metadata in Docker's context configuration under your Docker configuration directory. It does not start, stop or reconfigure the daemon.

$ docker context inspect local-test
[
    {
        "Name": "local-test",
        "Metadata": {},
        "Endpoints": {
            "docker": {
                "Host": "unix:///var/run/docker.sock"
            }
        }
    }
]

Additional fields can appear in the inspection output. Treat the endpoint as the authoritative detail.

3. Create a context for an SSH endpoint

SSH is usually the simplest remote option. Docker uses the SSH connection for transport, so you do not have to distribute a Docker TLS key pair. Use an account that is allowed to access the remote Docker socket:

$ docker context create \
    --description "Staging engine over SSH" \
    --docker host=ssh://[email protected] \
    staging
staging
Successfully created context "staging"

Replace both the account and host with values you control. Creating this record does not prove that SSH login or remote Docker access works, so verify the connection without making it the default:

$ docker --context staging version
Client:
 Version:           29.8.1
...
Server:
 Engine:
  Version:          29.x

The server section is the useful result. If you get an SSH authentication failure, a socket permission error or an unreachable host, fix that access path before using the context.

4. Create a TLS context when certificates are required

For a Docker daemon that exposes a TLS-protected TCP socket, supply the endpoint and certificate paths together:

$ docker context create \
    --description "Production engine over TLS" \
    --docker "host=tcp://engine.example.com:2376,ca=/home/USER/.docker/ca.pem,cert=/home/USER/.docker/cert.pem,key=/home/USER/.docker/key.pem" \
    production-tls
production-tls
Successfully created context "production-tls"

Replace USER, the host name and every certificate path. Each file has a job:

• The CA file limits which certificate authorities the client trusts.
• The certificate and key authenticate the client.
• The private key should be readable only by the intended user. Do not put real private key contents in a shell command or paste them into tickets.

5. Copy an existing context deliberately

Use --from when the new context should inherit the endpoint configuration of an existing one:

$ docker context create \
    --from staging \
    --description "Staging smoke tests" \
    staging-smoke
staging-smoke
Successfully created context "staging-smoke"

Check both names with docker context inspect. The source is named after --from and the new name is the final positional argument.

The endpoint form can also copy endpoint configuration with --docker from=staging. Pick one approach, use it consistently and verify the resulting endpoint:

$ docker context create \
    --docker from=staging \
    staging-copy
$ docker context inspect staging-copy

6. Test without changing the default

Use the global --context option for a one-off check:

$ docker --context staging info
$ docker --context staging ps

These commands use staging for that invocation only.

For a whole shell session, use DOCKER_CONTEXT=staging. The environment variable overrides the configured context for every command in that shell:

$ export DOCKER_CONTEXT=staging
$ docker context show
staging
$ unset DOCKER_CONTEXT

$ docker context use default
default
Current context is now "default"

7. Remove a context you no longer need

Context creation changes local Docker configuration, so remove a test record when it stops being useful:

$ docker context rm local-test
local-test

This removes the context definition, not the Docker daemon, its images, its containers or its volumes.

• Do not remove the selected context. Switch away first.
• Do not remove a context just because its endpoint is briefly unreachable.
• Inspect first if unsure.

$ docker context show
$ docker context inspect local-test

If a context name already exists, creation fails rather than silently replacing it. Choose another name, or use the separate context update command after checking that changing the existing definition is intended.