# Kitchen::Docker A Test Kitchen Driver for Docker. This driver utilizes the [docker-api](https://github.com/swipely/docker-api) gem as the docker client making a CLI client unnecessary. If you would prefer a docker driver which uses the docker CLI you should look at the original [kitchen-docker](https://github.com/portertech/kitchen-docker) from which this fork originated. Substantial credit for this driver goes to Sean Porter for the CLI implementation & his support in developing the docker-api based version. We ultimately decided it would be best to have two versions so folks could choose to use the CLI or docker-api based client. ## Requirements * [Docker][docker_getting_started] ## Known Issues * Upstart is neutered due to [this issue][docker_upstart_issue]. ## Installation and Setup Please read the Test Kitchen [docs][test_kitchen_docs] for more details. Example `.kitchen.local.yml`: ``` --- driver_plugin: docker platforms: - name: ubuntu run_list: - recipe[apt] - name: centos driver_config: image: centos platform: rhel run_list: - recipe[yum] ``` ## Default Configuration This driver can determine an image and platform type for a select number of platforms. Currently, the following platform names are supported: ``` --- platforms: - name: ubuntu-12.04 - name: centos-6.4 ``` This will effectively generate a configuration similar to: ``` --- platforms: - name: ubuntu-12.04 driver_config: image: ubuntu:12.04 platform: ubuntu - name: centos-6.4 driver_config: image: centos:6.4 platform: centos ``` ## Configuration ### socket The Docker daemon socket to use. By default, Docker will listen on `unix:///var/run/docker.sock`, and no configuration here is required. If Docker is binding to another host/port or Unix socket, you will need to set this option. If a TCP socket is set, its host will be used for SSH access to suite containers. Examples: ``` socket: unix:///tmp/docker.sock ``` ``` socket: tcp://docker.example.com:4242 ``` ### image The Docker image to use as the base for the suite containers. You can find images using the [Docker Index][docker_index]. The default will be determined by the Platform name, if a default exists (see the Default Configuration section for more details). If a default cannot be computed, then the default value is `base`, an official Ubuntu [image][docker_default_image]. ### platform The platform of the chosen image. This is used to properly bootstrap the suite container for Test Kitchen. Kitchen Docker currently supports: * `debian` or `ubuntu` * `rhel` or `centos` The default will be determined by the Platform name, if a default exists (see the Default Configuration section for more details). If a default cannot be computed, then the default value is `ubuntu`. ### require\_chef\_omnibus Determines whether or not a Chef [Omnibus package][chef_omnibus_dl] will be installed. There are several different behaviors available: * `true` - the latest release will be installed. Subsequent converges will skip re-installing if chef is present. * `latest` - the latest release will be installed. Subsequent converges will always re-install even if chef is present. * `` (ex: `10.24.0`) - the desired version string will be passed the the install.sh script. Subsequent converges will skip if the installed version and the desired version match. * `false` or `nil` - no chef is installed. The default value is `true`. ### container\_name Allows for specification of a container name which will be visible in `docker ps`. This makes tracking down containers associated w/ cookbook testing easier. This defaults to a calculated value which is a combination of 4 attributes: - platform name - CWD basename (where kitchen was run from) - suite name - hostname of initiating system For example, a cookbook named `test-gem` has this name when run from my laptop on a remote system: `ubuntu-12.04..test-gem..default..anichols-mbr` ### disable\_upstart Disables upstart on Debian/Ubuntu containers, as many images do not support a working upstart. The default value is `true`. ### provision\_command Custom command(s) to be run when provisioning the base for the suite containers. Examples: ``` provision_command: curl -L https://www.opscode.com/chef/install.sh | bash ``` ``` provision_command: - apt-get install dnsutils - apt-get install telnet ``` ``` driver_config: provision_command: curl -L https://www.opscode.com/chef/install.sh | bash require_chef_omnibus: false ``` ### remove\_images This determines if intermediate images are removed after container creation. Equivalent to `-rm` docker cli option. The default value is `true`. ### run_command Sets the command used to run the suite container. The default value is `/usr/sbin/sshd -D -o UseDNS=no -o UsePAM=no`. Examples: ``` run_command: /sbin/init ``` ### memory Sets the memory limit for the suite container in bytes. Otherwise use Dockers default. You can read more about `memory.limit_in_bytes` [here][memory_limit]. ### cpu Sets the CPU shares (relative weight) for the suite container. Otherwise use Dockers defaults. You can read more about cpu.shares [here][cpu_shares]. ### volume Adds a data volume(s) to the suite container. Examples: ``` volume: /ftp ``` ``` volume: - /ftp - /srv ``` ## dns Adjusts `resolv.conf` to use the dns servers specified. Otherwise use Dockers defaults. Examples: ``` dns: 8.8.8.8 ``` ``` dns: - 8.8.8.8 - 8.8.4.4 ``` ### forward Set suite container port(s) to forward to the host machine. You may specify the host (public) port in the mappings, if not, Docker chooses for you. Examples: ``` forward: 80 ``` ``` forward: - 22:2222 - 80:8080 ``` ### hostname Set the suite container hostname. Otherwise use Dockers default. Examples: ``` hostname: foobar.local ``` ### privileged Run the suite container in privileged mode. This allows certain functionality inside the Docker container which is not otherwise permitted. The default value is `false`. Examples: ``` privileged: true ``` ## Development * Source hosted at [GitHub][repo] * Report issues/questions/feature requests on [GitHub Issues][issues] Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example: 1. Fork the repo 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Added some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request ## Authors Created and maintained by [Aaron Nichols][author] () Original kitchen-docker by [Sean Porter]() ## License Apache 2.0 (see [LICENSE][license]) [author]: https://github.com/adnichols [issues]: https://github.com/adnichols/kitchen-docker-api/issues [license]: https://github.com/adnichols/kitchen-docker-api/blob/master/LICENSE [repo]: https://github.com/adnichols/kitchen-docker-api [docker_getting_started]: http://www.docker.io/gettingstarted/ [docker_upstart_issue]: https://github.com/dotcloud/docker/issues/223 [docker_index]: https://index.docker.io/ [docker_default_image]: https://index.docker.io/_/base/ [test_kitchen_docs]: http://kitchen.ci/docs/getting-started/ [chef_omnibus_dl]: http://www.opscode.com/chef/install/ [cpu_shares]: https://docs.fedoraproject.org/en-US/Fedora/17/html/Resource_Management_Guide/sec-cpu.html [memory_limit]: https://docs.fedoraproject.org/en-US/Fedora/17/html/Resource_Management_Guide/sec-memory.html