Connection settings

Connect through Unix sockets, TCP, HTTP or HTTPS, or a custom HTTP client.

Environment variables are optional. You can use the default local Docker socket without any configuration, set connection options through environment variables, or configure the connection directly in PHP using the bundled factory or Guzzle.

Default connection

Docker::create() uses DockerClientFactory::createFromEnv(). Without DOCKER_HOST, it connects to unix:///var/run/docker.sock.

If you choose environment variables, set them on the PHP process: in its shell, service configuration or container environment. The library reads them when creating the client and does not load .env files itself. For connection options supplied directly in PHP, see factory options or Guzzle connections.

To choose another socket:

DOCKER_HOST=unix:///run/docker.sock php your-script.php

Access to a Docker socket is privileged. Use a development daemon for examples that create containers or images, and do not expose an unauthenticated daemon to an untrusted network.

TCP and HTTP

The factory accepts both tcp:// and http:// daemon addresses:

DOCKER_HOST=tcp://docker.example.com:2375 php your-script.php
DOCKER_HOST=http://docker.example.com:2375 php your-script.php

These connections are unencrypted unless TLS is enabled. An http:// address without a port uses port 80; use the daemon’s configured port explicitly if it differs.

TLS connections

Use the daemon’s TCP address and its client certificates:

export DOCKER_HOST=tcp://docker.example.com:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/client-certificates
php your-script.php

The certificate directory must contain ca.pem, cert.pem and key.pem. If needed, set DOCKER_PEER_NAME to the name used to verify the server certificate. Set DOCKER_TLS_VERIFY to exactly 1 to enable this certificate configuration.

An https:// address also enables TLS, even without DOCKER_TLS_VERIFY:

DOCKER_HOST=https://docker.example.com:2376 php your-script.php

Without a port, HTTPS uses port 443. By default, the server certificate must be trusted by PHP’s configured certificate authorities and match the daemon’s hostname. For a private CA or mutual TLS, use DOCKER_TLS_VERIFY=1 and DOCKER_CERT_PATH as above; https:// works with those settings too.

Factory options

Environment variables are optional. You can configure the bundled socket client directly in PHP instead:

<?php

require __DIR__ . '/vendor/autoload.php';

use Docker\Docker;
use Docker\DockerClientFactory;

$httpClient = DockerClientFactory::create([
    'remote_socket' => 'unix:///var/run/docker.sock',
]);

$docker = Docker::create($httpClient, [], [], false);

The fourth argument disables the generated server plugins. The factory already adds the daemon address and versioned path. See the factory implementation for the plugins it configures.

For a private CA without client certificates, pass the CA file directly:

<?php

require __DIR__ . '/vendor/autoload.php';

use Docker\DockerClientFactory;

$httpClient = DockerClientFactory::create([
    'remote_socket' => 'https://docker.example.com:2376',
    'stream_context_options' => [
        'ssl' => ['cafile' => '/path/to/ca.pem'],
    ],
]);

For mutual TLS, add local_cert and local_pk to the SSL options:

<?php

require __DIR__ . '/vendor/autoload.php';

use Docker\Docker;
use Docker\DockerClientFactory;

$httpClient = DockerClientFactory::create([
    'remote_socket' => 'https://docker.example.com:2376',
    'stream_context_options' => [
        'ssl' => [
            'cafile' => '/path/to/ca.pem',
            'local_cert' => '/path/to/cert.pem',
            'local_pk' => '/path/to/key.pem',
        ],
    ],
]);

$docker = Docker::create($httpClient, [], [], false);

The factory keeps the socket client’s options, including timeouts and SSL context options. An HTTPS address always enables TLS, including when ssl is set to false; use http:// or tcp:// for a plaintext connection.

Custom HTTP clients

Docker::create($httpClient) accepts a compatible PSR-18 HTTP client. Configure its daemon address, TLS options and socket support. Check that it also supports unbuffered responses and Docker’s upgraded connections if you use log, attach or exec streams.

See Guzzle connections for complete PHP examples using custom Unix sockets, HTTP, private CAs and mutual TLS.

DOCKER_API_VERSION affects the default factory’s request path; it does not change the generated models. See API versions.