The sous-chefs nginx cookbook: installing and configuring nginx as a Chef resource set

What the cookbook does and what it no longer does

The cookbook installs nginx from package and sets up configuration handling similar to Debian's Apache2 scripts. That is the short description and it tells you the model: package install, then configuration managed as server configuration in the style of a Debian-style a2ensite mechanism rather than as a pile of template files you copy into place.

What has changed is the interface. The project description says the cookbook is now resource-based, and that you should use the resources described in wrapper cookbooks or recipes. There is no recipe here to include and no attribute file to set. If you arrive from an older version of this cookbook, or from a generic expectation of what a Chef cookbook looks like, that change is the first thing to understand.

The repository is described as the development repository for the nginx cookbook, and the published artifact is on the Chef Supermarket at supermarket.chef.io/cookbooks/nginx. The badge in the project description points at that page for the current cookbook version, which is the difference between the source tree and the version you would actually install.

The four resources are the whole public surface, and each has its own documentation page under a `documentation/` directory in the repository. There is nginx_install, which handles the package, nginx_config for configuration files, nginx_site for a virtual host, and nginx_service for the service itself. Splitting install, config, site and service is what makes the resource-based design useful, because it lets a wrapper declare a site without implying that the package should be reinstalled, and lets you enable or disable a server block independently of the service state.

The cookbook is Apache-2.0 licensed, the last push was on 2026-10-19, and the recent tags are 12.3.1 from 2025-09-04, v12.3.3 from 2026-08-16 and v12.3.4 from 2026-09-14.

The platform matrix and the Chef version floor

The supported platforms are listed with the qualifier that they are supported and tested with Test Kitchen, which is a stronger claim than merely installing. The list covers AlmaLinux 8 and 9, Rocky Linux 8 and 9, CentOS Stream 8 and 9, Amazon Linux 2023, Debian 11 and 12, and Ubuntu 22.04 and 24.04.

That is nine platform combinations across three major families, and the pattern in it is worth reading. The RHEL family is represented by three of its members including two major versions each of AlmaLinux, Rocky and CentOS Stream, Amazon Linux 2023 is there on its own, and the Debian family is covered by Debian 11 and 12 plus Ubuntu 22.04 and 24.04. So a cookbook that is maintained by a community and is meant to run in CI across a fleet has chosen breadth within the distributions that enterprise Linux actually uses, rather than a single vendor and a single version.

The Chef requirement is Chef 15.3 or newer, and that floor is worth relating to the resource-based design. Custom resources with the properties this cookbook exposes need a reasonably modern Chef Infra Client, and the project's major version numbering is at 12.x, which is a long-running cookbook rather than a new one.

The only cookbook dependency is `ohai`, and the reason given is that it is used for setting up the ohai plugin. Ohai is Chef's node data collection mechanism, so a plugin here means the cookbook gathers some additional facts about the node before the resources run. That is a small detail and it is also the only coupling to another cookbook, which is worth noting in a cookbook whose job is to install and configure a web server.

The Test Kitchen setup is visible in the repository, with `kitchen.yml` as the main file and separate `kitchen.dokken.yml`, `kitchen.exec.yml` and `kitchen.global.yml` files. Dokken is the containerised CI runner, the exec driver runs commands on the local machine, and the global file holds shared settings, so the cookbook can be exercised in containers in CI and against a real machine locally.

How the repository is organised, and what the tooling says about the maintainers

The top level of the tree is a well-organised Chef cookbook with a lot of supporting infrastructure, and reading the file names tells you how the project is run.

The cookbook itself is in the conventional directories. `resources/` holds the four custom resources, `templates/` holds the template files used to render configuration, `libraries/` holds Ruby helper code, `metadata.rb` is the cookbook metadata that declares the name, version and dependencies, `spec/` holds the unit tests, and `test/` holds the integration tests that Test Kitchen drives. A `documentation/` directory holds the per-resource documentation pages, and `chefignore` lists what is excluded when the cookbook is packaged for upload to the Supermarket.

`Policyfile.rb` is there, which is the lockfile-style dependency resolution format Chef uses, so a deployment can pin the exact dependency graph rather than resolving at converge time.

The rest of the tree is process, and it is unusually visible for a cookbook. There is a `CONTRIBUTING.md`, a `CODE_OF_CONDUCT.md` and a `CHANGELOG.md`. There is a Dangerfile, which is the tool that pulls in a review bot to comment on pull requests, and an `.overcommit.yml` for local git hooks. There is a `.rubocop.yml` for Ruby linting, a `.yamllint` for YAML, a `.markdownlint-cli2.yaml` and a `.mdlrc` for the two Markdown linters, and an `.editorconfig`.

Then there are the release and dependency automations. `release-please-config.json` and `.release-please-manifest.json` drive the release-please tool, which handles version bumps and changelog entries, and `renovate.json` configures Renovate to keep dependencies updated. The combination tells you that releases and dependency bumps happen through automation rather than a maintainer remembering to do them, and that is also why the version numbers move in small increments and why the changelog exists in a machine-maintained form.

There is a `.envrc` and a `.vscode/` directory, and a `TESTING.md` file that covers the testing setup separately from the main documentation.

The Sous Chefs model and where to get the cookbook

This cookbook is maintained by the Sous Chefs, described as a community of Chef cookbook maintainers working together to maintain important cookbooks. The project directs readers to sous-chefs.org for more and to the Chef Community Slack channel for chat.

That model matters more than it might appear for a widely used infrastructure cookbook. A cookbook like this one ends up in the run list of thousands of organisations, and the interesting failure mode is not that nobody maintains it, it is that it is maintained by one person who stops. The Sous Chefs arrangement is a group of maintainers sharing the load, with sponsorship through OpenCollective and a public set of backers and sponsors, and the project description credits those supporters explicitly.

The distribution route is the Chef Supermarket page, which is where the cookbook version badge points and where the current released version is published. The repository itself is the development repository, so the two are not the same thing: the git tree can be ahead of the published cookbook, and the Supermarket version is what a `depends` in another cookbook resolves to.

The alternative to the Supermarket is vendoring the cookbook into your own repository, which some organisations do for cookbooks they cannot wait for a release of. With a community-maintained cookbook that usually works, since the code is Apache-2.0 and the resource set is small, but you take on the upgrade burden yourself.

The release cadence visible in the tags is roughly monthly. Version 12.3.1 is dated 2025-09-04, v12.3.3 on 2026-08-16 and v12.3.4 on 2026-09-14, with the last push on 2026-10-19, so the tree is a few weeks ahead of the newest tag. A major version has not appeared in that window, which for a resource-based rewrite of a long-standing cookbook suggests the interface has settled.

Where the nginx cookbook is the wrong choice

The first limit is that it is a Chef cookbook and not a standalone tool. If your configuration management is Ansible, Puppet, Salt or a plain shell script, this is unusable as-is, and the design decisions that make it good, four composable resources with typed properties, are exactly the parts that do not port.

The second limit is that resource-based cookbooks have a learning cost that recipe cookbooks do not. A recipe cookbook is a list of steps you read top to bottom, and a wrapper cookbook that includes it is a familiar shape. Custom resources mean learning the property names, the actions and the defaults of each of the four resources, and the project description deliberately does not list them, which means you are expected to read the documentation pages before you write anything.

The third is the platform list. Nine tested distributions sounds like coverage and is a limit at the same time, because an nginx cookbook is exactly the kind of thing that people need on a platform nobody tested. If your fleet includes an unusual distribution or a specific version not on that list, you are outside what the maintainers have verified, and the config handling that mimics Debian's Apache2 scripts will behave differently on a system whose package layout differs.

The fourth is scope. This cookbook installs nginx and manages its configuration. It is not a full web platform stack, so TLS termination strategy, load balancer configuration, PHP or application runtime, log shipping and monitoring are all outside it, and a team that expects the cookbook to be a complete ingress story will be disappointed.

Compare that with installing nginx by hand and templating a vhost file from your own configuration management. The difference in approach is that the cookbook gives you the Debian-style site enabling model, tested across platforms, with the configuration handling already solved, and in exchange you take a dependency on the Chef ecosystem and on a four-resource interface you have to learn. For a team already running Chef at scale, the trade is obviously worth it. For a single server, a package install and one template file is less machinery.

Licence, and what to check before you add it to a run list

The cookbook is licensed under Apache-2.0, with the LICENSE file in the repository root and the licence badge in the project description pointing at the Apache 2.0 text. That is a permissive licence with an express patent grant, which is the right choice for infrastructure code that organisations vendor and modify internally, and you should read the LICENSE file yourself for the exact terms.

What to check before you add it to a run list is a short list, and most of it is reading rather than doing.

Read the four documentation pages. The project description links documentation for nginx_install, nginx_config, nginx_site and nginx_service, and those pages are where the properties and their defaults live. The single sentence about configuration handling being similar to Debian's Apache2 scripts tells you the model but not the options, and the options are what you need.

Then confirm your platform is on the list. AlmaLinux 8 and 9, Rocky Linux 8 and 9, CentOS Stream 8 and 9, Amazon Linux 2023, Debian 11 and 12, and Ubuntu 22.04 and 24.04 are supported and tested with Test Kitchen. If you are on anything else, the package names, the service name and the configuration paths are the things that will differ.

Confirm your Chef Infra Client is 15.3 or newer, and that the `ohai` dependency resolves in your Policyfile or Berksfile, since the cookbook uses it for the ohai plugin setup.

And decide the upgrade policy before the first converge. Because the cookbook moved to resources only, the migration from an older version is not a version bump, it is a rewrite of your wrapper, so pinning the version in your Policyfile and reading CHANGELOG.md before each bump is the practice that keeps that from becoming an incident.

Editorial conclusion

The sous-chefs nginx cookbook fits a team that has already moved to Chef custom resources and wants nginx server blocks, configuration and service control declared in a wrapper cookbook rather than in templates and file drops. It does not fit a team that wants a recipe to include and a directory of vhosts to point at, because the cookbook is resource-based only and the documentation for each resource lives in separate pages rather than in the project description. Before you adopt it, read the documentation pages for nginx_config and nginx_site, confirm your platform is on the tested list of nine distributions, and check the version of the cookbook you are pulling against Chef 15.3 or newer.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. sous-chefs/nginx on GitHub