# sous-chefs/docker Cookbook for Chef-managed Docker

> The sous-chefs/docker cookbook gives Chef recipes declarative resources for installing Docker and managing services, images, containers, networks, volumes, registries, and Swarm objects. It fits Linux estates that already use Chef, but its documented platform matrix and installation responsibilities do not cover every Docker deployment environment.

**sous-chefs/docker** — Development repository for the docker cookbook

- Repository: https://github.com/sous-chefs/docker
- Website: https://supermarket.chef.io/cookbooks/docker
- Stars: 1,398 · Forks: 781
- Language: Ruby
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/sous-chefs-docker

## Chef resources for the Docker lifecycle in sous-chefs/docker

sous-chefs/docker solves a configuration-management problem rather than a container runtime problem. Docker still supplies the container engine, image format, daemon, networking, and workload isolation. The cookbook wraps operations that would otherwise require shell commands or ad hoc daemon configuration into Chef resources that can be declared in a cookbook recipe and included in a normal Chef run.

It is aimed at engineers who already manage Linux hosts with Chef and need Docker installation, container lifecycle operations, or Docker-related objects to remain under the same policy and idempotency model as the rest of the host. The documented resource set covers considerably more than starting a daemon. It includes image pulling and pruning, command execution inside containers, networks, volumes, plugins, registry authentication, tags, and Swarm initialization, joining, services, and tokens.

The central entry point is `docker_installation`, which uses provider resolution to select one of three documented installation resources. Package installation uses `docker_installation_package` to install Docker through the `docker-ce` package. `docker_installation_script` installs Docker through the script-based installation path, while `docker_installation_tarball` copies a precompiled Go binary tarball onto disk. The selected mechanism affects reproducibility, source dependencies, and the amount of control available during upgrades.

The cookbook automatically configures upstream Docker package repositories. Teams using different repositories must disable that functionality and configure repositories themselves, possibly with Chef's `yum_repository` or `apt_repository` resources or with the `chef-apt-docker` and `chef-yum-docker` cookbooks. This makes repository ownership explicit, but it also means adopting the cookbook does not remove repository configuration from the implementation plan.

## How docker_service composes installation and daemon management

The `docker_service` resource is a composite resource built from `docker_installation` and `docker_service_manager`. That division separates obtaining the Docker software from managing the daemon afterward. A recipe can express one desired service state, while the underlying resources handle the installation and service-manager portions through Chef's provider resolution system.

Two service-manager resources are documented: `docker_service_manager_systemd`, which manages the daemon through systemd unit files, and `docker_service_manager_execute`, which manages it through Chef. This matters because a host's service-management conventions, existing daemon settings, and organizational requirements determine which implementation fits. The README does not document a universal migration or rollback procedure for changing managers, so a team should not treat manager selection as a trivial property change.

Service group behavior also needs platform-specific attention. The README identifies RHEL as a case that may default the service to the `dockerroot` group rather than the usual Docker group. It provides a direct `group` property for that case:

```ruby
docker_service 'default' do
  group 'dockerroot'
  action [:create, :start]
end
```

This configuration tells Chef which group should own or run the configured service according to the resource's contract. It is not merely cosmetic for local socket access. Getting the group wrong can leave the daemon installed but inaccessible to the intended local operator, while an overly broad group policy can weaken host isolation. The README does not provide a universal group-membership or authorization policy, so those decisions remain with the adopting organization.

The cookbook's declared scope stops at Docker itself. It explicitly excludes Docker ecosystem tools and prerequisite technologies such as cgroups and aufs. It also does not claim to configure SELinux policy generally. For CentOS, the stated requirement is permissive or disabled SELinux, with a linked upstream Docker issue as the reason. That is a platform precondition, not an automated hardening workflow.

## Installing sous-chefs/docker and running the first busybox container

Start by making the cookbook a dependency in the consuming cookbook's `metadata.rb`. The README gives this exact declaration:

```ruby
depends 'docker'
```

After the dependency is available to the Chef run, add resource declarations to a recipe. The repository lists `test/cookbooks/test` as the location of recipes used by test-kitchen and describes them as usage examples. That is the documented place to inspect when the abbreviated README examples do not provide enough deployment context.

The shortest documented example starts the service, pulls BusyBox, and declares an echo container. Put these resources in a recipe included by the run list:

```ruby
docker_service 'default' do
  action [:create, :start]
end

docker_image 'busybox' do
  action :pull
end

docker_container 'an-echo-server' do
  repo 'busybox'
  port '1234:1234'
  command "nc -ll -p 1234 -e /bin/cat"
end
```

The first declaration creates and starts the Docker service. The second requests the `busybox` image. The third maps container port `1234` to host port `1234` and supplies the command shown in the README. A successful Chef run should report convergence for these declared resources, but the README does not define exact console output or a separate client-side connectivity check, so those should not be invented.

Before the first run, confirm that the node can reach a web server hosting the Docker binary. The cookbook also expects an appropriate Linux platform and, on CentOS, the documented SELinux state. Because automatic repository setup is part of the cookbook, check whether that behavior matches the organization's package-management policy. If repositories are managed elsewhere, disable the built-in setup before using the service resource.

## Container, registry, volume, and network resource boundaries

The resource set follows Docker's object model closely. `docker_image` handles image and repository operations, `docker_tag` handles tagging, `docker_network` handles networks, and `docker_volume` handles volumes. `docker_container` connects those pieces by accepting an image reference, command, port mappings, environment values, volume mounts, and network settings.

The README demonstrates a network and named volume being attached to an Alpine container:

```ruby
docker_network 'my_network' do
  subnet '10.9.8.0/24'
  gateway '10.9.8.1'
end

docker_volume 'my_volume' do
  action :create
end

docker_container 'my_container' do
  repo 'alpine'
  tag '3.1'
  command "nc -ll -p 1234 -e /bin/cat"
  volumes 'my_volume:/my_data'
  network_mode 'my_network'
  action :run
end
```

Here, resource declarations establish a network with the documented subnet and gateway, create a named volume, then attach both to the container. This is a useful fit for hosts whose containers should follow Chef-managed configuration. It does not establish that every runtime detail belongs in Chef. The documentation does not define orchestration, rollout sequencing, health policy, or rollback for multi-container workloads.

Registry access is exposed as another explicit resource. `docker_registry` can store registry URL and credential properties, while `docker_image` and `docker_container` can target a remote Docker host through `host` and accept TLS certificate paths. The README's private-registry example includes a password directly in the resource. It does not explain secret retrieval, vault integration, or permission handling for `metadata.rb`, recipes, node data, or Chef Server, so such security design cannot be inferred from this cookbook.

For remote daemon access, the example uses separate hosts for image retrieval and container execution, plus `tls_verify`, `tls_ca_cert`, `tls_client_cert`, and `tls_client_key`. The presence of these properties does not by itself prove how certificates are rotated, how connectivity failures are retried, or how secrets are protected. Those are adoption checks for the surrounding Chef policy.

## Installation choices, platform limits, and the tarball warning

The package path is the most conventional choice when the automatic upstream repositories and documented platforms are acceptable, because the `docker_installation_package` resource is defined around the `docker-ce` package. The script path offers another documented installation method, while the tarball resource accepts a source URL, version, and checksum.

The tarball option has an explicit warning in the README: it should not be used in production, especially with devicemapper. That is a direct boundary on adoption. Even though the resource copies a precompiled Go binary tarball and includes checksum data in its example, the project documentation advises against production use. A team selecting it for a controlled environment should record that exception rather than treating checksum validation as a substitute for the warning.

The documented platform list is also finite: Amazon Linux 2, Debian 9, 10 and 11, Fedora, Ubuntu 18.04, 20.04 and 22.04, and CentOS 7 and 8. The README does not claim current support for newer releases of those operating systems. Repository age, package availability, systemd behavior, and Docker's supported distributions can change independently of the cookbook, so platform validation remains necessary even when a node's distribution name appears on the list.

Compared with running Docker installation and lifecycle commands directly in a deployment script, the cookbook centralizes Docker declarations in Chef recipes and supplies typed resources for specific operations. Compared with `chef-apt-docker` or `chef-yum-docker`, those cookbooks are described as alternatives for setting up repositories when the main cookbook's automatic repository handling is disabled. The difference is scope: `sous-chefs/docker` covers Docker installation and management resources, while the named helper cookbooks address repository setup.

This is the wrong tool when the requirement is container orchestration rather than Docker host management. The included Swarm resources cover initialization, joining, services, and tokens, but the repository does not describe Kubernetes resources, deployment controllers, or application rollout policy. It is also a poor fit for a team without Chef because the value comes from encoding state in Chef resources and running those recipes on nodes.

## Maintenance signals and the cost of cookbook upgrades

The repository is not archived. Its last push was on 2026-10-15. The release history also shows v12.0.2 on 2026-08-13, v12.0.1 on 2026-07-09, and v12.0.0 on 2026-05-27. These facts support recent activity, but they do not establish compatibility between every version, operating system, and Docker release.

Upgrade cost comes from several layers. The cookbook may change resource behavior across major versions, while Docker itself evolves independently. A consuming cookbook must select a cookbook version through its normal Chef dependency process, review release notes and resource documentation, and rerun its test recipes. The repository includes `TESTING.md`, `kitchen.yml`, `spec/`, and `test/`, which identify testing and test-kitchen assets in the repository layout, but the README does not provide a complete upgrade or rollback runbook.

Platform compatibility is likely to be the larger operational concern for an existing estate. The README names distributions and versions but does not state a migration path to releases outside that list. It also does not document automatic handling of cgroups, aufs, or general SELinux configuration. Those prerequisites can turn a cookbook upgrade into host preparation work rather than a simple dependency bump.

The project uses the Apache-2.0 license. That identifier permits use and modification under its terms and includes notice and license obligations, but this review does not interpret legal requirements or provide legal advice. An adopting organization should review the repository's `LICENSE` file and its internal policy for redistributed or modified portions.

Repository ownership also affects long-term maintenance. The README identifies the Sous Chefs as a community of Chef cookbook maintainers. That provides a named maintenance group, but operational ownership still belongs to the adopting team. Upgrades should be exercised against the same service-manager choice, repository strategy, TLS arrangement, and container resources used in production.

## Conclusion

Adopt sous-chefs/docker when Docker lifecycle management is already part of Chef policy and the target host matches the documented platform list. Do not choose it as a replacement for Kubernetes, a general-purpose deployment tool, or infrastructure that omits the required network and operating-system configuration. Before adoption, verify the first supported Chef and Docker combination on a representative host, confirm that the selected installation resource reaches the intended binary source, and review the ownership and group settings for the Docker service. The repository is not archived, its last push was on 2026-10-15, and v12.0.2 was released on 2026-08-13.

## FAQ

### What does the sous-chefs/docker Cookbook manage?

It provides Chef resources for installing Docker and managing services, containers, images, networks, volumes, registries, plugins, tags, and selected Swarm operations. It does not manage Docker ecosystem tools or prerequisites such as cgroups and aufs.

### How do I install sous-chefs/docker in a Chef cookbook?

Add `depends 'docker'` to the consuming cookbook's `metadata.rb`, make the cookbook available to Chef, and declare the Docker resources in a recipe included in the run list.

### Can sous-chefs/docker install Docker from a tarball?

Yes, `docker_installation_tarball` can copy a precompiled Go binary tarball onto the host. The README explicitly says it should not be used in production, especially with devicemapper.

### Which operating systems does sous-chefs/docker document?

The documented list includes Amazon Linux 2, Debian 9, 10 and 11, Fedora, Ubuntu 18.04, 20.04 and 22.04, and CentOS 7 and 8. The README does not claim support for other releases.

### Does sous-chefs/docker configure SELinux on CentOS?

No general SELinux configuration is documented. Instead, the README states that CentOS requires SELinux to be permissive or disabled and links the associated upstream Docker issue.

## Sources

- [License: Apache-2.0](https://github.com/sous-chefs/docker/blob/main/LICENSE)
- [Project website](https://supermarket.chef.io/cookbooks/docker)
- [README](https://github.com/sous-chefs/docker/blob/main/README.md)
- [Releases](https://github.com/sous-chefs/docker/releases)
- [sous-chefs/docker on GitHub](https://github.com/sous-chefs/docker)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sous-chefs-docker