Installing Caddy plugins in NixOS

By using custom package

  1. Custom package
  2. Install custom package

Caddy, like any other web servers, is extensible through plugins. Plugin is usually installed using xcaddy; using it is as easy as $ xcaddy build --with to build the latest caddy binary with ntlm-transport plugin.

NixOS has its own way of building Go package (Caddy is written in Go), so using xcaddy may be counterintuitive. The Nix-way to go is to build a custom package using a “*.nix” file and instruct the service (also known as a module in Nix ecosystem) to use that package instead of the repo’s.

In NixOS, the Caddy module has long included services.caddy.package option to specify custom package. It was primarily used as a way to install Caddy 2 from the unstable channel (unstable.caddy) because the package in stable channel (pkgs.caddy) of NixOS 20.03 is still Caddy 1. I talked about that option in a previous post.

Aside from installing Caddy from different channel, that option can also be used to specify a custom package by using pkgs.callPackage. I previously used callPackage as a workaround to install cloudflared in a IPv6-only instance from a repository other than GitHub because GitHub doesn’t support IPv6 yet.

If a custom package is defined in “/etc/caddy/custom-package.nix”, then the configuration will be:

services.caddy = { enable = true; package = pkgs.callPackage /etc/caddy/custom-package.nix { }; };

Custom package §

The following package patches the “main.go“ file of the upstream source to insert additional plugins. The code snippet is courtesy of @diamondburned. The marked lines show how plugins are specified through the plugins option.

{ lib, buildGoModule, fetchFromGitHub, plugins ? [], vendorSha256 ? "" }: with lib; let imports = flip concatMapStrings plugins (pkg: "\t\t\t_ \"${pkg}\"\n"); main = '' package main import ( caddycmd "" _ "" ${imports} ) func main() { caddycmd.Main() } ''; in buildGoModule rec { pname = "caddy"; version = "2.4.6"; subPackages = [ "cmd/caddy" ]; src = fetchFromGitHub { owner = "caddyserver"; repo = pname; # rev = "v${version}"; sha256 = "sha256-xNCxzoNpXkj8WF9+kYJfO18ux8/OhxygkGjA49+Q4vY="; }; inherit vendorSha256; overrideModAttrs = (_: { preBuild = "echo '${main}' > cmd/caddy/main.go"; postInstall = "cp go.sum go.mod $out/ && ls $out/"; }); postPatch = '' echo '${main}' > cmd/caddy/main.go cat cmd/caddy/main.go ''; postConfigure = '' cp vendor/go.sum ./ cp vendor/go.mod ./ ''; meta = with lib; { homepage =; description = "Fast, cross-platform HTTP/2 web server with automatic HTTPS"; license = licenses.asl20; maintainers = with maintainers; [ rushmorem fpletz zimbatm ]; }; }

Install custom package §

Specify the desired plugins in services.caddy.package.plugins:

services.caddy = { enable = true; package = (pkgs.callPackage /etc/caddy/custom-package.nix { plugins = [ "" "" ]; vendorSha256 = "0000000000000000000000000000000000000000000000000000"; }); };

The above example will install ntlm-transport and forwardproxy plugins. The first run of nixos-rebuild will fail due to mismatched vendorSha256, simply replace the “000…” with the expected value and the second run should be ok.