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();
If the bash
shell is not available in your docker image, you can specify an alternative shell.
$containerInstance = DockerContainer::create($imageName)
->shell('sh')
->start();
If the docker
binary is not globally available, you can specify the exact path.
$containerInstance = DockerContainer::create($imageName)
->dockerBin('/usr/local/bin/docker')
->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();
The default protocol for the port mapping is TCP. If you want to use UDP, you can pass it as the third argument.
$containerInstance = DockerContainer::create($imageName)
->mapPort($portOnHost, $portOnContainer, 'udp')
->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();
You can add commands using the setCommands
method.
$containerInstance = DockerContainer::create($imageName)
->setCommands('--api.insecure=true', '--providers.docker=true')
->start();
These commands will be placed at the end of to the docker run
command.
If you want to add optional arguments to the docker run
command, use setOptionalArgs
method:
$containerInstance = DockerContainer::create($imageName)
->setOptionalArgs('-it', '-a')
->start();
These arguments will be placed after docker run
immediately.
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();
If you want to attach the container to a docker network, use network
method:
$containerInstance = DockerContainer::create($imageName)
->network('my-network')
->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();
You can change the timeout for the start command with the setStartCommandTimeout
function (the default is 60s).
$containerInstance = DockerContainer::create($imageName)
->setStartCommandTimeout(120)
->start();
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]);
To change the process timeout you can pass a second parameter to the execute
method (the default is 60s).
$process = $instance->execute($command, 3600);
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 json decoded array from the docker inspect command can be retrieved with inspect
.
$inspectArray = $instance->inspect();
$inspectArray[0]['State']['Status']; // Running, Starting etc.
$inspectArray[0]['RestartCount']; // Integer
$inspectArray[0]['NetworkSettings']['IPAddress']; // 172.17.0.2
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 security@spatie.be instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.