This package provides a nice way to start docker containers and execute commands on them.

$containerInstance = DockerContainer::create($imageName)->start();

$process = $containerInstance->execute('whoami');

$process->getOutput(); // returns the name of the user inside the docker container

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

You can install the package via composer:

composer require spatie/docker

You can get an instance of a docker container using

$containerInstance = DockerContainer::create($imageName)->start();

By default the container will be daemonized and it will be cleaned up after it exists.

If you don't want your docker being daemonized, call doNotDaemonize.

$containerInstance = DockerContainer::create($imageName)
    ->doNotDaemonize()
    ->start();

If you don't want your docker being cleaned up after it exists, call doNotCleanUpAfterExit.

$containerInstance = DockerContainer::create($imageName)
    ->doNotCleanUpAfterExit()
    ->start();

If you want your docker being privileged, call privileged.

$containerInstance = DockerContainer::create($imageName)
    ->privileged()
    ->start();

You can name the container by passing the name as the second argument to the constructor.

new DockerContainer($imageName, $nameOfContainer);

Alternatively, use the name method.

$containerInstance = DockerContainer::create($imageName)
    ->name($yourName)
    ->start();

You can map ports between the host machine and the docker container using the mapPort method. To map multiple ports, just call mapPort multiple times.

$containerInstance = DockerContainer::create($imageName)
    ->mapPort($portOnHost, $portOnContainer)
    ->mapPort($anotherPortOnHost, $anotherPortOnContainer)
    ->start();

You can set environment variables using the setEnvironmentVariable method. To add multiple arguments, just call setEnvironmentVariable multiple times.

$containerInstance = DockerContainer::create($imageName)
    ->setEnvironmentVariable($variableKey, $variableValue)
    ->setEnvironmentVariable($anotherVariableKey, $anotherVariableValue)
    ->start();

You can set volumes using the setVolume method. To add multiple arguments, just call setVolume multiple times.

$containerInstance = DockerContainer::create($imageName)
    ->setVolume($pathOnHost, $pathOnDocker)
    ->setVolume($anotherPathOnHost, $anotherPathOnDocker)
    ->start();

You can set labels using the setLabel method. To add multiple arguments, just call setLabel multiple times.

$containerInstance = DockerContainer::create($imageName)
    ->setLabel($labelName, $labelValue)
    ->setLabel($anotherLabelName, $anotherLabelValue)
    ->start();

When using this package in a testing environment, it can be handy that the docker container is stopped after __destruct is called on it (mostly this will happen when the PHP script ends). You can enable this behaviour with the stopOnDestruct method.

$containerInstance = DockerContainer::create($imageName)
    ->stopOnDestruct()
    ->start();

You can set the host used for executing the container. The docker command line accepts a daemon socket string. To connect to a remote docker host via ssh, use the syntax ssh://username@hostname. Note that the proper SSH keys will already need to be configured for this work.

$containerInstance = DockerContainer::create($imageName)
    ->remoteHost('ssh://username@hostname')
    ->start();

Upon startup of a container, docker will execute the command defined within the container. The command method gives the ability to override to default command to run within the container.

$containerInstance = DockerContainer::create($imageName)
    ->command('ls -l /etc')
    ->start();

You can get the string that will be executed when a container is started with the getStartCommand function

// returns "docker run -d --rm spatie/docker"
DockerContainer::create($imageName)->getStartCommand();

To execute a command on the container, use the execute method.

$process = $instance->execute($command);

You can execute multiple command in one go by passing an array.

$process = $instance->execute([$command, $anotherCommand]);

The execute method returns an instance of Symfony/Process.

You can check if your command ran successfully using the isSuccessful $method

$process->isSuccessful(); // returns a boolean

You can get to the output using getOutput(). If the command did not run successfully, you can use getErrorOutput(). For more information on how to work with a Process head over to the Symfony docs.

If you cant to connect to your container instance via SSH, you probably want to add a public key to it.

This can be done using the addPublicKey method.

$instance->addPublicKey($pathToPublicKey);

It is assumed that the authorized_keys file is located in at /root/.ssh/authorized_keys. If this is not the case, you can specify the path of that file as a second parameter.

$instance->addPublicKey($pathToPublicKey, $pathToAuthorizedKeys);

Note that in order to be able to connect via SSH, you should set up a SSH server in your dockerfile. Take a look at the dockerfile in the tests of this package for an example.

Files can be added to an instance with addFiles.

$instance->addFiles($fileOrDirectoryOnHost, $pathInContainer);

The Spatie\Docker\ContainerInstance class is macroable. This means you can add extra functions to it.

Spatie\Docker\DockerContainerInstance::macro('whoAmI', function () {
    $process = $containerInstance->run('whoami');


    return $process->getOutput();
});

$containerInstance = DockerContainer::create($imageName)->start();

$containerInstance->whoAmI(); // returns of name of user in the docker container

Before running the tests for the first time, you must build the spatie/docker container with:

composer build-docker

Next, you can run the tests with:

composer test

Please see CHANGELOG for more information on what has changed recently.

Please see CONTRIBUTING for details.

If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.

• Ruben Van Assche
• Freek Van der Herten
• All Contributors

The MIT License (MIT). Please see License File for more information.